J. Richer, Ed.
December 7, 2015

Health Relationship Trust Profile for OpenID Connect 1.0
openid-heart-openid-connect

Abstract

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.


Table of Contents

1. Introduction

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 [HEART.OAuth2]. All requirements herein are in addition to the OAuth 2.0 profile.

1.1. Requirements Notation and Conventions

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 [RFC2119].

All uses of JSON Web Signature (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] 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.

1.2. Terminology

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 [RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519], and the terms defined by OpenID Connect Core 1.0 [OpenID.Core].

2. ID Tokens

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) [RFC7517] format. ID Tokens MAY be encrypted using the appropriate key of the requesting client.

All clients MUST verify the following in received ID tokens:

iss
The "issuer" field is the Uniform Resource Locater (URL) of the expected issuer
aud
The "audience" field contains the client ID of the client
exp, iat, nbf
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

The ID Token MUST expire and SHOULD have an active lifetime no longer than five minutes.

This example ID token has been signed using the server's RSA key:

eyJhbGciOiJSUzI1NiJ9.eyJhdXRoX3RpbWUiOjE0
MTg2OTg3ODIsImV4cCI6MTQxODY5OTQxMiwic3ViI
joiNldaUVBwblF4ViIsIm5vbmNlIjoiMTg4NjM3Yj
NhZjE0YSIsImF1ZCI6WyJjMWJjODRlNC00N2VlLTR
iNjQtYmI1Mi01Y2RhNmM4MWY3ODgiXSwiaXNzIjoi
aHR0cHM6XC9cL2lkcC1wLm1pdHJlLm9yZ1wvIiwia
WF0IjoxNDE4Njk4ODEyfQ.mQc0rtL56dnJ7_zO_fx
8-qObsQhXcn-qN-FC3JIDBuNmP8i11LRA_sgh_omR
RfQAUhZD5qTRPAKbLuCD451lf7ALAUwoGg8zAASI5
QNGXoBVVn7buxPd2SElbSnHxu0o8ZsUZZwNpircWN
UlYLje6APJf0kre9ztTj-5J1hRKFbbHodR2I1m5q8
zQR0ql-FoFlOfPhvfurXxCRGqP1xpvLLBUi0JAw3F
8hZt_i1RUYWMqLQZV4VU3eVNeIPAD38qD1fxTXGVE
d2XDJpmlcxjrWxzJ8fGfJrbsiHCzmCjflhv34O22z
b0lJpC0d0VScqxXjNTa2-ULyCoehLcezmssg

Its claims are as follows:

 {
   "auth_time": 1418698782,
   "exp": 1418699412,
   "sub": "6WZQPpnQxV",
   "nonce": "188637b3af14a",
   "aud": [
      "c1bc84e4-47ee-4b64-bb52-5cda6c81f788"
   ],
   "iss": "https:\\/\\/idp-p.example.com\\/",
   "iat": 1418698812
}

3. UserInfo Endpoint

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:

GET /userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTg3MDI0MTIs
ImF1ZCI6WyJjMWJjODRlNC00N2VlLTRiNjQtYmI1Mi01Y2RhNmM4MWY3ODgiXSwiaXN
zIjoiaHR0cHM6XC9cL2lkcC1wLm1pdHJlLm9yZ1wvIiwianRpIjoiZDNmN2I0OGYtYm
M4MS00MGVjLWExNDAtOTc0YWY3NGM0ZGUzIiwiaWF0IjoxNDE4Njk4ODEyfQ.iHMz_t
zZ90_b0QZS-AXtQtvclZ7M4uDAs1WxCFxpgBfBanolW37X8h1ECrUJexbXMD6rrj_uu
WEqPD738oWRo0rOnoKJAgbF1GhXPAYnN5pZRygWSD1a6RcmN85SxUig0H0e7drmdmRk
PQgbl2wMhu-6h2Oqw-ize4dKmykN9UX_2drXrooSxpRZqFVYX8PkCvCCBuFy2O-HPRo
v_SwtJMk5qjUWMyn2I4Nu2s-R20aCA-7T5dunr0iWCkLQnVnaXMfA22RlRiU87nl21z
appYb1_EHF9ePyq3Q353cDUY7vje8m2kKXYTgc_bUAYuW-W3SMSw5UlKaHtSZ6PQICo
A
Accept: text/plain, application/json, application/*+json, */*
Host: idp-p.example.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2.3 (java 1.5)

And receives a document in response like the following:

HTTP/1.1 200 OK
Date: Tue, 16 Dec 2014 03:00:12 GMT
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=ISO-8859-1
Content-Language: en-US
Content-Length: 333
Connection: close

{
   "sub": "6WZQPpnQxV",
   "name": "Steve Emeritus",
   "preferred_username": "steve",
   "given_name": "Stephen",
   "family_name": "Emeritus",
   "nickname": "Steve",
   "gender": "M",
   "updated_time": "2014-09-24 14:27:43.701000",
   "birthdate": "1980-01-01",
   "email": "steve.e@example.com",
   "email_verified": true,
   "phone_number": "857-555-1234",
   "phone_number_verified": true
}

Servers MUST support the generation of JWT [RFC7519] encoded responses from the UserInfo Endpoint in addition to unsigned JSON objects. Signed responses MUST be signed by the OpenID Provider's key, and encrypted responses MUST be encrypted with the authorized client's key. The OpenID Provider MUST support the RS256 signature method (the Rivest, Shamir, and Adleman (RSA) signature algorithm with a 256-bit hash) and MAY use other asymmetric signature and encryption methods listed in the JSON Web Algorithms (JWA [RFC7518]) specification.

4. Request Objects

Clients MAY optionally send requests to the authorization endpoint as signed or encrypted request objects using the request parameter as defined by OpenID Connect [OpenID.Core]. 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 [HEART.OAuth2] 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.

5. Authentication Context

OpenID Providers MUST 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.

It is RECOMMENDED that the standardized Uniform Resource Identifiers (URIs) established by the Federal Identity, Credential, and Access Management (FICAM) Trust Framework be used for the acr values:

Note that OpenID Connect cannot provide LOA 4 identity assertions due to the way that the FICAM LOA values are currently defined.

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 [I-D.richer-vectors-of-trust] standard.

6. Discovery

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 [OpenID.Discovery]. The discovery document MUST contain at minimum the following fields:

issuer
The fully qualified issuer URL of the server
authorization_endpoint
The fully qualified URL of the server's authorization endpoint defined by [RFC6749]
token_endpoint
The fully qualified URL of the server's token endpoint defined by [RFC6749]
introspection_endpoint
The fully qualified URL of the server's introspection endpoint defined by OAuth Token Introspection [RFC7662]
revocation_endpoint
The fully qualified URL of the server's revocation endpoint defined by OAuth Token Revocation [RFC7009]
jwks_uri
The fully qualified URI of the server's public key in JWK Set [RFC7517] format

The following example shows the JSON document found at a discovery endpoint for an authorization server:

{
  "request_parameter_supported": true,
  "id_token_encryption_alg_values_supported": [
    "RSA-OAEP", "RSA1_5", "RSA-OAEP-256"
  ],
  "registration_endpoint": "https://idp-p.example.com/register",
  "userinfo_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "token_endpoint": "https://idp-p.example.com/token",
  "request_uri_parameter_supported": false,
  "request_object_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512",
    "A128CBC+HS256", "A256CBC-HS512",
    "A128CBC-HS256", "A128GCM", "A256GCM"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic",
    "client_secret_jwt",
    "private_key_jwt",
    "none"
  ],
  "userinfo_encryption_alg_values_supported": [
    "RSA-OAEP", "RSA1_5",
    "RSA-OAEP-256"
  ],
  "subject_types_supported": [
    "public", "pairwise"
  ],
  "id_token_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512",
    "A128CBC+HS256", "A256CBC-HS512", "A128CBC-HS256",
    "A128GCM", "A256GCM"
  ],
  "claims_parameter_supported": false,
  "jwks_uri": "https://idp-p.example.com/jwk",
  "id_token_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "none"
  ],
  "authorization_endpoint": "https://idp-p.example.com/authorize",
  "require_request_uri_registration": false,
  "introspection_endpoint": "https://idp-p.example.com/introspect",
  "request_object_encryption_alg_values_supported": [
    "RSA-OAEP", ?RSA1_5", "RSA-OAEP-256"
  ],
  "service_documentation": "https://idp-p.example.com/about",
  "response_types_supported": [
    "code", "token"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "revocation_endpoint": "https://idp-p.example.com/revoke",
  "request_object_signing_alg_values_supported": [
    "HS256", "HS384", "HS512", "RS256", "RS384", "RS512"
  ],
  "claim_types_supported": [
    "normal"
  ],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "client_credentials",
    "urn:ietf:params:oauth:grant_type:redelegate"
  ],
  "scopes_supported": [
    "profile", "openid", "email", "address", "phone", "offline_access"
  ],
  "userinfo_endpoint": "https://idp-p.example.com/userinfo",
  "userinfo_encryption_enc_values_supported": [
    "A192CBC-HS384", "A192GCM", "A256CBC+HS512","A128CBC+HS256",
    "A256CBC-HS512", "A128CBC-HS256", "A128GCM", "A256GCM"
  ],
  "op_tos_uri": "https://idp-p.example.com/about",
  "issuer": "https://idp-p.example.com/",
  "op_policy_uri": "https://idp-p.example.com/about",
  "claims_supported": [
    "sub", "name", "preferred_username", "given_name", "family_name",
    "middle_name", "nickname", "profile", "picture", "website",
    "gender", "zone_info", "locale", "updated_time", "birthdate",
    "email", "email_verified", "phone_number", "address"
  ]
}

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 [RFC7517] format, such as the following 2048-bit RSA key:

{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "n": "o80vbR0ZfMhjZWfqwPUGNkcIeUcweFyzB2S2T-hje83IOVct8gVg9FxvHPK1ReEW3-p7-A8GNcLAuFP_8jPhiL6LyJC3F10aV9KPQFF-w6Eq6VtpEgYSfzvFegNiPtpMWd7C43EDwjQ-GrXMVCLrBYxZC-P1ShyxVBOzeR_5MTC0JGiDTecr_2YT6o_3aE2SIJu4iNPgGh9MnyxdBo0Uf0TmrqEIabquXA1-V8iUihwfI8qjf3EujkYi7gXXelIo4_gipQYNjr4DBNlE0__RI0kDU-27mb6esswnP2WgHZQPsk779fTcNDBIcYgyLujlcUATEqfCaPDNp00J6AbY6w",
      "kty": "RSA",
      "kid": "rsa1"
    }
  ]
}

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.

7. Security Considerations

All transactions MUST be protected in transit by TLS as described in BCP195 [BCP195].

All clients MUST conform to applicable recommendations found in the Security Considerations sections of [RFC6749] and those found in the OAuth 2.0 Threat Model and Security Considerations document [RFC6819].

8. Normative References

[BCP195] Sheffer, Y., Holz, R. and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015.
[HEART.OAuth2] Richer, J., "Health Relationship Trust Profile for OAuth 2.0", December 2015.
[I-D.ietf-oauth-pop-architecture] Hunt, P., Richer, J., Mills, W., Mishra, P. and H. Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security Architecture", Internet-Draft draft-ietf-oauth-pop-architecture-07, December 2015.
[I-D.richer-vectors-of-trust] Richer, J. and L. Johansson, "Vectors of Trust", Internet-Draft draft-richer-vectors-of-trust-02, November 2015.
[OpenID.Core] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", August 2015.
[OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M. and E. Jay, "OpenID Connect Discovery 1.0", August 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, DOI 10.17487/RFC2246, January 1999.
[RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008.
[RFC5322] Resnick, P., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012.
[RFC6819] Lodderstedt, T., McGloin, M. and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013.
[RFC7009] Lodderstedt, T., Dronia, S. and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013.
[RFC7033] Jones, P., Salgueiro, G., Jones, M. and J. Smarr, "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 2013.
[RFC7515] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015.
[RFC7519] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.
[RFC7662] Richer, J., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015.

Appendix A. Acknowledgements

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/

Appendix B. Notices

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.

Appendix C. Document History

-2015-12-01

-2015-04-01

Author's Address

Justin Richer (editor) EMail: openid@justin.richer.org URI: http://justin.richer.org/