openid@justin.richer.org http://justin.richer.org/

OpenID Heart Working Group The User-Managed Access (UMA) protocol defines a method for an end user to introduce a resource to an authorization server, define a set of policies governing access to that resource, and for a requesting party to provide claims to fulfill those policies in order to gain access to the resource. This specification profiles the UMA protocol to increase baseline security, provide greater interoperability, and structure deployments in a manner specifically applicable to (but not limited to) the healthcare domain.

This document profiles the User-Managed Access specification for use in the context of securing web-facing application programming interfaces (APIs), particularly Representational State Transfer (RESTful) APIs, in potentially multi-party cross-domain scenarios. Because User-Managed Access is built on OAuth 2.0 and OpenID Connect 1.0, this profile inherits all requirements of the HEART profiles for the use of OAuth 2.0 and OpenID Connect 1.0 where applicable. All requirements herein are in addition to the OAuth 2.0 and OpenID Connect 1.0 profiles where appropriate. The requirements in this document serve two purposes: Define a mandatory baseline set of security controls suitable for a wide range of use cases, while maintaining reasonable ease of implementation and functionality Identify optional advanced security controls for sensitive use cases where heightened risks justify more stringent controls that increase the required implementation effort and may reduce or restrict functionality This UMA profile is intended to be shared broadly, and ideally to influence OAuth implementations in other domains besides health care.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. All uses of JSON Web Signature (JWS) and JSON Web Encryption (JWE) data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0, the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT), the terms defined by OpenID Connect Core 1.0, and the terms defined by UMA.

This specification defines requirements for the following components: UMA 1.0 client UMA 1.0 authorization server UMA 1.0 resource server The specification also defines features for interaction between these components: Client to authorization server Protected resource to authorization server When a HEART-compliant component is interacting with other HEART-compliant components, in any valid combination, all components MUST fully conform to the features and requirements of this specification. All interaction with non-HEART components is outside the scope of this specification. A HEART-compliant UMA authorization server MUST support all features as described in this specification. A general-purpose authorization server MAY support additional features for use with non-HEART clients and protected resources. All OAuth 2.0 functionality used to implement the UMA protocol MUST conform to the OAuth 2.0 HEART profile. A HEART-compliant UMA authorization server MAY also provide HEART-compliant OAuth 2.0 authorization server functionality. In such cases, the authorization server MUST fully implement the OAuth 2.0 HEART profile. A HEART-compliant UMA client MUST use all functions as described in this specification. A general-purpose client library MAY support additional features for use with non-HEART authorization servers and protected resources. A HEART-compliant UMA resource server MUST use all functions as described in this specification. A general-purpose resource server library MAY support additional features for use with non-HEART authorization servers and clients.

All clients MUST authenticate to the RPT endpoint using a private key as described in the HEART OAuth 2.0 profile section 2.2.

Clients MUST present the RPT as an OAuth 2.0 bearer token as described in .

The authorization server MUST implement the UMA discovery mechanism defined in UMA as well as the discovery mechanisms described in the HEART OAuth 2.0 profile.

The authorization server MUST support claims being presented in at least two methods: by redirecting the requesting party to a web page where they can log in to the authorization server using OpenID Connect directly by the client in the form of an OpenID Connect ID Token When the ID token is presented directly to the RPT endpoint, the authorization server MUST validate the token, including its audience and signature. Since the audience of an ID token is the client's identifier with the IdP, and this client identifier is known only to the client and the IdP, this restriction effectively means that ID tokens can only be presented at the RPT endpoint in the special case when the authorization server is also the IdP or there is another closely bound relationship between the AS and IdP. The authorization server MUST implement the security extension defined in .

Since UMA protected resources will act as OAuth clients during parts of the process, all requirements for interaction between OAuth authorization servers and OAuth clients in the HEART OAuth 2.0 profile apply to these as well. The authorization server MUST make its introspection endpoint accessible to the protected resource by use of the PAT.

Authorization servers MUST support the "bearer" profile of all token categories. All issued tokens (whether AAT, PAT, or RPT) MUST be JSON Web Tokens (JWTs) signed with JSON Web Signatures (JWS) using the authorization server's key as described in the HEART OAuth 2.0 profile section 4.2. AATs and PATs MUST be issued using a standard OAuth 2.0 token flow appropriate to the type of application (whether client or protected resource) described in the HEART OAuth 2.0 profile.

The AAT MUST at minimum define the following fields inside the JWT and return them from the introspection endpoint. Other fields MAY also be defined. The issuer URL of the authorization server. An array containing the URL of the RPT endpoint The issuer-specific identifier of the user that authorized the AAT. The client identifier of the authorized client.

The PAT MUST at minimum define the following fields inside the JWT and return them from the introspection endpoint. Other fields MAY also be defined. The issuer URL of the authorization server. An array containing the URL of the introspection endpoint and the URL of the resource set registration endpoint The issuer-specific identifier of the user that authorized the PAT. The client identifier of the protected resource.

The RPT MUST at minimum define the following fields inside the JWT and return them from the introspection endpoint. Other fields MAY also be defined. The issuer URL of the authorization server. An array of resource identifiers where this token can be used. The issuer-specific identifier of the user that authorized the RPT (the resource owner). The client identifier of the authorized client.

It is RECOMMENDED that AATs and PATs have a lifetimes as specified in the HEART OAuth 2.0 profile section 4.3 depending on the nature of the client or protected resource they were issued to. Since the PAT is intended to be used for managing access to resources when the resource owner is no longer present, it SHOULD have a lifetime and lifecycle that allows that use pattern, such as the use of refresh tokens issued alongside the PAT. It is RECOMMENDED that RPTs follow a lifetime of an access token as specified in the HEART OAuth 2.0 profile section 4.3 depending on the nature of the client.

All UMA clients MUST register with the authorization server as OAuth clients, as described in the HEART OAuth 2.0 profile. Since all UMA resource servers also act as OAuth clients, they MUST also register with the authorization server under the same requirements as regular OAuth clients. The authorization server MUST allow for dynamic client registration and dynamic resource set registration. The authorization server MAY prohibit dynamically registered clients and resource sets from requesting specific scopes, as described in the HEART OAuth 2.0 profile. The authorization server MUST indicate to end users that a client or protected resource was dynamically registered in the UI, such as on the policy editing screen presented to the resource owner.

Resource servers that allow resource owners to specify their own authorization server MUST be capable of using webfinger to discover the authorization server's issuer URL.

Resource servers MUST authenticate to the token endpoint of the authorization server using a private key as described in the HEART OAuth 2.0 profile section 2.2.

Resource servers MUST allow connections from clients in an unauthorized state to start the discovery process. The Resource server MUST return the issuer URL of the authorization server as well as a permission ticket for the client to use. Resource servers MUST accept RPTs as an OAuth bearer token in the authorization header.

All transactions MUST be protected in transit by TLS as described in BCP195. All clients MUST conform to applicable recommendations found in the Security Considerations sections of and those found in the OAuth 2.0 Threat Model and Security Considerations document.

When a client makes an unauthenticated call to a medical record protected by UMA, the resource server will respond back with an indicator of which authorization server protects that resource. If the operator of the client knows out-of-band that a particular user owns or controls a given authorization server, such disclosure could inadvertently leak information about the patient without divulging the medical record itself.

Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases. Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce MIT MIT Synergetics

openid@justin.richer.org http://justin.richer.org/

openid@justin.richer.org http://justin.richer.org/

The OpenID Community would like to thank the following people for their contributions to this specification: Dale Moberg, Adrian Gropper, Eve Maler, Danny van Leeuwen, John Moehrke, Aaron Seib, John Bradley, Debbie Bucci, Josh Mandel, and Sarah Squire.

Copyright (c) 2015 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

-2017-04-10 Renamed "protected resource" to "Resource server" throughout Clarified compliance with regard to OAuth 2.0 functionality -2017-03-20 Updated UMA references Clarified PAT TTL -2016-10-03 Added UMA claims gathering extension as requirement. Added privacy considerations. -2016-09-19 Reorganized document against different conformance aspects. -2016-04-30 Added conformance statements. -2016-02-15 Implementer's Draft 1 -2015-12-09 Removed recommendations for issuing different kinds of UMA tokens. -2015-12-01 Updated references. Clarified component registration. Clarified the nature of tokens and their lifetimes. -2015-04-23 Created UMA shell specification.