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

OpenID Heart Working Group The User Managed Access 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 User Managed Access 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. All requirements herein are in addition to the OAuth 2.0 and OpenID Connect 1.0 profiles.

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.

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 client 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 authorization 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. It is RECOMMENDED that RPTs have a lifetime of no greater than one hour.

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

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.

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 webpage 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.

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.

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

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.

-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.