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

OpenID Heart Working Group The OpenID Connect protocol defines an identity federation system that allows a relying party to request and receive authentication and profile information about an end user. This specification profiles the OpenID Connect 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 OpenID Connect specification for use in providing identity information supporting secure Representational State Transfer (RESTful) interfaces. Because OpenID Connect is built on OAuth 2.0, this profile inherits all requirements of the HEART Profile for the use of OAuth 2.0 where appropriate. All requirements herein are in addition to the OAuth 2.0 profile 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 OpenID Connect 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), and the terms defined by OpenID Connect Core 1.0.

This specification defines requirements for the following components: OpenID Connect 1.0 relying parties (also known as OpenID Clients) OpenID Connect 1.0 identity providers (also known as OpenID Providers) The specification also defines features for interaction between these components: Relying party to identity provider 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 OpenID Connect IdP MUST support all features as described in this specification. A general-purpose IdP MAY support additional features for use with non-HEART clients. All OAuth 2.0 functionality used to implement the OpenID Connect protocol MUST conform to the OAuth 2.0 HEART profile. A HEART-compliant OpenID Connect IdP 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. If a HEART-compliant OpenID Connect IdP does not provide HEART-compliant OAuth 2.0 authorization server services, all features related to interaction between the authorization server and protected resource are therefore OPTIONAL. A HEART-compliant OpenID Connect client MUST use all functions as described in this specification. A general-purpose client library MAY support additional features for use with non-HEART IdPs.

All clients MUST verify the signature of ID tokens against the key of the identity provider. All clients MUST verify the following in received ID tokens: The "issuer" field is the Uniform Resource Locater (URL) of the expected issuer The "audience" field contains the client ID of the client The "expiration", "issued at", and "not before" timestamps for the token are dates (integer number of seconds since from 1970-01-01T00:00:00Z UTC) within acceptable ranges

Clients MAY optionally send requests to the authorization endpoint as request objects using the request parameter as defined by OpenID Connect. Clients MAY send requests to the authorization endpoint by reference using the request_uri parameter. Request objects MUST be signed by the client's registered key. Request objects MAY be encrypted to the authorization server's public key.

All ID Tokens MUST be signed by the OpenID Provider's private signature key. All clients MUST validate the signature of an ID Token before accepting it using the public key of the issuing server, which is published in JSON Web Key (JWK) format. ID Tokens MAY be encrypted using the appropriate key of the requesting client. The ID Token MUST expire and SHOULD have an active lifetime no longer than five minutes. Since the ID token is consumed by the client and not presented to remote systems, much shorter expiration times are RECOMMENDED where possible. This example ID token has been signed using the server's RSA key:

Its claims are as follows:

Servers MUST support the UserInfo Endpoint and, at a minimum, the openid scope and sub (subject) claims. In an example transaction, the client sends a request to the UserInfo Endpoint like the following:

And receives a document in response like the following:

Servers MUST support the generation of JWT encoded responses from the UserInfo Endpoint in addition to unsigned JSON objects to allow clients to operate at a higher security level. Signed responses MUST be signed by the IdP's key, and encrypted responses MUST be encrypted with the authorized client's key. The IdP MUST support the RS256 signature method and MAY use other asymmetric signature and encryption methods listed in the JSON Web Algorithms (JWA) specification.

Authorization servers MUST accept requests containing a request object signed by the client's private key. Servers MUST validate the signature on such requests against the client's registered public key. Clients must register their keys during client registration as described in the HEART OAuth 2.0 profile. Servers MUST accept request objects encrypted with the server's public key. Servers MAY accept request objects by reference using the request_uri parameter. Both of these methods allow for clients to create a request that is protected from tampering through the browser, allowing for a higher security mode of operation for clients and applications that require it. Clients are not required to use request objects, but authorization servers are required to support requests using them.

OpenID Providers MAY provide acr (authentication context class reference, equivalent to the Security Assertion Markup Language (SAML) element of the same name) and amr (authentication methods reference) values in ID tokens. The amr value is an array of strings describing the set of mechanisms used to authenticate the user to the OpenID Provider. Providers that require multi-factor authentication will typically provide multiple values (for example, memorized password plus hardware-token-generated one-time password). The specific values MUST be agreed upon and understood between the OpenID Provider and any Relying Parties. In the future, this profile will likely reference and make use of the draft Vectors of Trust standard.

All OpenID Connect servers are uniquely identified by a URL known as the issuer. This URL serves as the prefix of a service discovery endpoint as specified in the OpenID Connect Discovery standard. The discovery document MUST contain at minimum the following fields: The fully qualified issuer URL of the server The fully qualified URL of the server's authorization endpoint defined by The fully qualified URL of the server's token endpoint defined by The fully qualified URL of the server's introspection endpoint defined by OAuth Token Introspection The fully qualified URL of the server's revocation endpoint defined by OAuth Token Revocation The fully qualified URI of the server's public key in JWK Set format The following example shows the JSON document found at a discovery endpoint for an authorization server:

Clients and protected resources SHOULD cache this discovery information. It is RECOMMENDED that servers provide cache information through HTTP headers and make the cache valid for at least one week. The server MUST provide its public key in JWK Set format, such as the following 2048-bit RSA key:

Clients and protected resources SHOULD cache this key. It is RECOMMENDED that servers provide cache information through HTTP headers and make the cache valid for at least one week.

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 Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila

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

The OpenID Community would like to thank the following people for their contributions to this specification: Mark Russel, Mary Pulvermacher, David Hill, Dale Moberg, Adrian Gropper, Eve Maler, Danny van Leeuwen, John Moehrke, Aaron Seib, John Bradley, Debbie Bucci, Josh Mandel, and Sarah Squire. The original version of this specification was part of the Secure RESTful Interfaces project from The MITRE Corporation, available online at http://secure-restful-interface-profile.github.io/pages/

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 Clarified conformance with regard to OAuth 2.0 functions. -2016-09-19 Reorganized document against different conformance aspects. -2016-08-10 Clarified ID token lifetime. Justified support for request objects. Justified support for JWT-based userinfo responses. Removed ACR/AMR requirement (pending rewrite if there's demand). -2016-04-30 Added conformance statements. -2016-02-15 Implementer's Draft 1 -2015-12-01 Replaced "mitre.org" with "example.com". Updated references. Added VoT. -2015-04-01 Imported content from Secure RESTful OAuth profile.