TOC |
|
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
This specification only defines the endpoints and the associated message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Standard 1.0.
1.
Introduction
1.1.
Requirements Notation and Conventions
1.2.
Terminology
1.3.
Overview
2.
Messages
2.1.
Authorization Endpoint
2.1.1.
Authorization Request
2.1.1.1.
Request Parameters
2.1.2.
Authorization Response
2.1.2.1.
ID Token
2.1.3.
Authorization Error Response
2.2.
Token Endpoint
2.2.1.
Client Authentication
2.2.2.
Access Token Request
2.2.3.
Access Token Response
2.2.4.
Access Token Error Response
2.3.
UserInfo Endpoint
2.3.1.
UserInfo Request
2.3.2.
UserInfo Response
2.3.3.
UserInfo Error Response
2.4.
Scope Values
2.5.
Standard Claims
2.5.1.
Address Claim
2.5.2.
Claims Languages and Scripts
2.5.3.
Claim Stability and Uniqueness
2.5.4.
Additional Claims
2.6.
Claims Request
2.6.1.
Individual Claims Requests
2.6.2.
Languages and Scripts for Individual Claims
2.7.
Claim Types
2.7.1.
Normal Claims
2.7.2.
Aggregated and Distributed Claims
2.7.2.1.
Example of Aggregated Claims
2.7.2.2.
Example of Distributed Claims
2.8.
Subject Identifier Types
2.8.1.
Pairwise Identifier Algorithm
2.9.
Request Object
2.10.
Using the "request_uri" Parameter
2.10.1.
"request_uri" Rationale
3.
Signatures and Encryption
3.1.
Supported Algorithms
3.2.
Keys
3.3.
Signing
3.3.1.
Rotation of Asymmetric Signing Keys
3.4.
Encryption
3.4.1.
Rotation of Asymmetric Encryption Keys
4.
Validation
4.1.
Authorization Request Validation
4.1.1.
Encrypted Request Object
4.1.2.
Signed Request Object
4.1.3.
Parameter Validation
4.2.
ID Token Validation
4.3.
UserInfo Response Validation
4.4.
Access Token Validation
4.5.
Code Validation
5.
Offline Access
6.
Self-Issued OpenID Provider
6.1.
Self-Issued OpenID Provider Discovery
6.2.
Self-Issued OpenID Provider Registration
6.2.1.
Providing Additional Registration Information
6.3.
Self-Issued OpenID Provider Request
6.4.
Self-Issued OpenID Provider Response
6.5.
Self-Issued ID Token Validation
7.
String Operations
8.
Implementation Considerations
8.1.
Mandatory to Implement Features for All OpenID Providers
8.2.
Mandatory to Implement Features for Dynamic OpenID Providers
8.3.
Related Specifications
9.
Security Considerations
9.1.
Request Disclosure
9.2.
Server Masquerading
9.3.
Token Manufacture/Modification
9.4.
Server Response Disclosure
9.5.
Server Response Repudiation
9.6.
Request Repudiation
9.7.
Access Token Redirect
9.8.
Token Reuse
9.9.
Eavesdropping or Leaking Authorization Codes (Secondary Authenticator Capture)
9.10.
Token Substitution
9.11.
Timing Attack
9.12.
Other Crypto Related Attacks
9.13.
Signing and Encryption Order
9.14.
Issuer Identifier
9.15.
TLS Requirements
9.16.
Lifetimes of Access Tokens and Refresh Tokens
9.17.
Symmetric Key Entropy
9.18.
Need for Signed Requests
9.19.
Need for Encrypted Requests
10.
Privacy Considerations
11.
IANA Considerations
11.1.
JSON Web Token Claims Registry
11.1.1.
Registry Contents
11.2.
OAuth Parameters Registry
11.2.1.
Registry Contents
11.3.
OAuth Extensions Error Registry
11.3.1.
Registry Contents
12.
References
12.1.
Normative References
12.2.
Informative References
Appendix A.
Acknowledgements
Appendix B.
Notices
Appendix C.
Document History
§
Authors' Addresses
TOC |
TOC |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.
All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [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.
TOC |
This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], and the terms "Claim Names" and "Claim Values" defined by JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT].
This specification also defines the following terms:
- Authentication
- Act of verifying End-User's possession of previously provisioned credentials.
- Authentication Context
- Information that the Relying Party may require before it makes an entitlement decision with respect to an authentication response. Such context may include, but is not limited to, the actual authentication method used or level of assurance such as ISO/IEC 29115 (International Organization for Standardization, “ISO/IEC FDIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” December 2012.) [ISO29115] entity authentication assurance level.
- Authentication Context Class
- A set of authentication methods or procedures that are considered to be equivalent to each other in a particular context.
- Authentication Context Class Reference
- Identifier for an Authentication Context Class.
- Claim
- Piece of information about an Entity that a Claims Provider asserts about that Entity.
- Claim Type
- Syntax used for representing a Claim Value. This specification defines Normal, Aggregated, and Distributed Claim Types.
- Claims Provider
- Server that can return Claims about an Entity.
- End-User
- Human Resource Owner.
- Entity
- Something that has a separate and distinct existence and that can be identified in context. An End-User is one example of an Entity.
- Essential Claim
- Claim specified by the Client as being necessary to ensure a smooth authorization experience for the specific task requested by the End-User.
- ID Token
- Token that contains Claims about the authentication event. It may contain other Claims.
- Issuer
- Entity that issues a set of Claims.
- Issuer Identifier
- Verifiable identifier for an Issuer. An Issuer Identifier is a URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components. (No query or fragment components may be present.)
- Message
- Request or a response between an OpenID Relying Party and an OpenID Provider.
- OpenID Provider (OP)
- OAuth 2.0 Authorization Server that is capable of returning Claims to a Relying Party about the authentication event and the End-User in an ID Token and/or a UserInfo Endpoint response.
- OP Endpoints
- Authorization Endpoint, Token Endpoint, and UserInfo Endpoint.
- Request Object
- JWT that contains a set of request parameters as its Claims.
- Personally Identifiable Information (PII)
- Any information that (a) can be used to identify the natural person to whom such information relates, or (b) is or might be directly or indirectly linked to a natural person to whom such information relates.
- Pairwise Pseudonymous Identifier (PPID)
- Identifier that identifies the Entity to a Relying Party. An Entity's PPID at one Relying Party cannot be correlated with the Entity's PPID at another Relying Party.
- Relying Party (RP)
- Application requiring Claims from an OpenID Provider. It is an extended OAuth 2.0 Client.
- Self-Issued OpenID Provider
- Personal OpenID Provider that issues self-signed ID Tokens.
- UserInfo Endpoint
- Protected Resource that, when presented with an Access Token by the Client, returns Claims about the End-User represented by that Access Token.
- Voluntary Claim
- Claim specified by the Client as being useful but not Essential for the specific task requested by the End-User.
TOC |
The OpenID Connect protocol, in abstract, follows the following steps.
This specification only defines the abstract message flow and message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Standard 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” May 2013.) [OpenID.Standard], OpenID Connect Basic Client Profile 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” May 2013.) [OpenID.Basic], or OpenID Connect Implicit Client Profile 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” May 2013.) [OpenID.Implicit].
TOC |
In OpenID Connect, the RP interacts with these endpoints at the OP:
TOC |
The RP sends an Authorization Request to the Authorization Endpoint of the OP to obtain an Authorization Response, which may contain an ID Token and Access Token, depending on the response_type value used.
TOC |
An Authorization Request is a message sent from an RP to the OP's Authorization Endpoint. It is an extended OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] Authorization Request. Section 4.1.1 and 4.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] define the OAuth 2.0 Authorization Request parameters.
TOC |
OpenID Connect uses the following OAuth 2.0 request parameters:
- response_type
- REQUIRED. Value that controls the parameters returned in the response from the Authorization Endpoint.
- The OAuth 2.0 specification defines two response types:
- code
- When supplied as the value for the response_type parameter, a successful response MUST include an Authorization Code as defined in the OAuth 2.0 specification. Both successful and error responses MUST be added as parameters to the query component of the response. All tokens are returned from the Token Endpoint. When used by OpenID Connect, an ID Token is also returned from the Token Endpoint. OpenID Providers that are not Self-Issued OPs MUST support this response_type.
- token
- When supplied as the value for the response_type parameter, a successful response MUST include an Access Token as defined in the OAuth 2.0 specification. Both successful and error responses MUST be fragment-encoded. No ID Token is provided to the Client; therefore, this response_type is not used by OpenID Connect.
- OpenID Connect supports these additional response types (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” March 2013.) [OAuth.Responses], which have been registered with IANA:
- id_token
- When supplied as the value for the response_type parameter, a successful response MUST include an ID Token. Both successful and error responses SHOULD be fragment-encoded. OpenID Providers MUST support this response_type.
- id_token token
- When supplied as the value for the response_type parameter, a successful response MUST include both an Access Token and an ID Token. Both successful and error responses SHOULD be fragment-encoded. OpenID Providers MUST support this response_type.
- code token
- When supplied as the value for the response_type parameter, a successful response MUST include both an Access Token and an Authorization Code as defined in the OAuth 2.0 specification. When used by OpenID Connect, an ID Token is also returned from the Token Endpoint. Both successful and error responses SHOULD be fragment-encoded.
- code id_token
- When supplied as the value for the response_type parameter, a successful response MUST include both an Authorization Code and an ID Token. Both successful and error responses SHOULD be fragment-encoded.
- code id_token token
- When supplied as the value for the response_type parameter, a successful response MUST include an Authorization Code, an ID Token, and an Access Token. Both successful and error responses SHOULD be fragment-encoded.
- All OpenID Providers MUST support the id_token and token id_token response types and all OpenID Providers that are not Self-Issued OPs MUST also support the code response type.
- The Client may use any OAuth 2.0 registered response type supported by the OpenID Provider other than token (which provides no ID Token).
- client_id
- REQUIRED. OAuth 2.0 Client Identifier.
- scope
- REQUIRED. Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. OpenID Connect requests MUST contain the openid scope value. OPTIONAL scope values of profile, email, address, phone, and offline_access are also defined. See Section 2.4 (Scope Values) for more about the scope values defined by this specification.
- redirect_uri
- REQUIRED. Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider. If the Client uses the OAuth implicit grant type, the redirection URI MUST NOT use the http scheme unless the Client is a native application, in which case it MAY use the http: scheme with localhost as the hostname. If the Client only uses the OAuth authorization_code grant type, the redirection URI MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0.
- state
- RECOMMENDED. Opaque value used to maintain state between the request and the callback; it can serve as a protection against XSRF attacks, among other uses.
This specification also defines the following request parameters:
- nonce
- REQUIRED or OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. Use of the nonce is REQUIRED for all requests where an ID Token is returned directly from the Authorization Endpoint. It is OPTIONAL when the ID Token is returned from the Token Endpoint.
- display
- OPTIONAL. ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The defined values are:
- page
- The Authorization Server SHOULD display authentication and consent UI consistent with a full User-Agent page view. If the display parameter is not specified this is the default display mode.
- popup
- The Authorization Server SHOULD display authentication and consent UI consistent with a popup User-Agent window. The popup User-Agent window SHOULD be 450 pixels wide and 500 pixels tall.
- touch
- The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface. The Authorization Server MAY attempt to detect the touch device and further customize the interface.
- wap
- The Authorization Server SHOULD display authentication and consent UI consistent with a "feature phone" type display.
- prompt
- OPTIONAL. Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are:
The prompt parameter can be used by the Client to make sure that the End-User is still present for the current session or to bring attention to the request. If this parameter contains none with any other value, an error is returned.
- none
- The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims. This can be used as a method to check for existing authentication and/or consent.
- login
- The Authorization Server MUST prompt the End-User for reauthentication.
- consent
- The Authorization Server MUST prompt the End-User for consent before returning information to the Client.
- select_account
- The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for.
- max_age
- OPTIONAL. Maximum Authentication Age. Specifies that the End-User must be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. (The max_age request parameter corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] max_auth_age request parameter.) When max_age is used, the ID Token returned MUST include an auth_time Claim Value.
- ui_locales
- OPTIONAL. End-User's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
- claims_locales
- OPTIONAL. End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
- id_token_hint
- OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. This SHOULD be present when prompt=none is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response. The Authorization Server need not be listed as an audience of the ID Token when it is used as an id_token_hint value.
- If the ID Token received by the RP is encrypted, the Client MUST decrypt the signed ID Token contained within the encrypted ID Token. The Client MAY re-encrypt the signed ID token to the Authentication Server using a key that enables the server to decrypt the ID Token.
- For a Self-Issued ID Token, the sub (subject) of the signed ID Token MUST be sent as the kid (Key ID) of the JWE.
- login_hint
- OPTIONAL. Hint to the Authorization Server about the login identifier the End-User may use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the phone_number Claim. The use of this parameter is left to the OP's discretion.
- acr_values
- OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server MUST use for processing requests from this Client. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2.1.2.1 (ID Token).
- claims
- OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object, as specified in Section 2.6 (Claims Request).
- registration
- OPTIONAL. This parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration, as specified in Section 6.2.1 (Providing Additional Registration Information). The registration parameter SHOULD NOT be used when the OP is not a Self-Issued OP.
- request
- OPTIONAL. This parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. The parameter value is a Request Object value, as specified in Section 2.9 (Request Object). It represents the request as a JWT whose Claims are the request parameters above.
- When the request parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. Even if a scope parameter is present in the Request Object value, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.
- request_uri
- OPTIONAL. This parameter enables OpenID Connect requests to be passed by reference, rather than by value. The request_uri value is a URL using the https scheme referencing a resource containing a Request Object value, which is a JWT containing the request parameters. This parameter is used identically to the request parameter, other than that the Request Object value is retrieved from the specified URL, rather than passed by value. See Section 2.10 (Using the "request_uri" Parameter) for more information on using the request_uri parameter.
TOC |
An Authorization Response is a message returned from the OP's Authorization Endpoint in response to the Authorization Request by the RP.
This specification only describes OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750]. The OAuth 2.0 response parameter token_type MUST be set to Bearer unless another Token Type has been negotiated with the Client.
When the response_type in the request is code, the Authorization Response MUST return the parameters defined in Section 4.1.2 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
When the response_type includes other values, they must be returned as defined by their registration. The id_token and token id_token response types are defined in OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” March 2013.) [OAuth.Responses].
TOC |
The ID Token is a security token that contains Claims about the authentication event and other requested Claims. The ID Token is represented as a JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT].
The ID Token is used to manage the authentication event and user identifier and is scoped to a particular Client via the aud (audience) and nonce Claims.
The following Claims are used within the ID Token:
- iss
- REQUIRED. Issuer Identifier for the Issuer of the response.
- sub
- REQUIRED. Subject identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client. e.g. 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length.
- aud
- REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences.
- exp
- REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.
- iat
- REQUIRED. Time at which the JWT was issued. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
- auth_time
- OPTIONAL or REQUIRED. Time when the End-User authentication occurred. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] auth_time response parameter.)
- nonce
- OPTIONAL or REQUIRED. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authorization Request. If present in the Authorization Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authorization Request. Authorization Servers SHOULD perform no other processing on nonce values used. Use of the nonce is REQUIRED for all requests where an ID Token is returned directly from the Authorization Endpoint. It is OPTIONAL when the ID Token is returned from the Token Endpoint.
- at_hash
- OPTIONAL or REQUIRED. Access Token hash value. If the ID Token is issued from the Authorization Endpoint with an access_token, this is REQUIRED. This is OPTIONAL when the ID Token is issued from the Token Endpoint. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them.
- c_hash
- Sometimes REQUIRED. Code hash value. If the ID Token is issued from the Authorization Endpoint with a code, this is REQUIRED. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url encode them.
- acr
- OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 (International Organization for Standardization, “ISO/IEC FDIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” December 2012.) [ISO29115] level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of "level 0" is appropriate. Authentications with level 0 should never be used to authorize access to any resource of any monetary value. (This corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] nist_auth_level 0.) An absolute URI or a registered name (Johansson, L., “An IANA Registry for Level of Assurance (LoA) Profiles,” August 2012.) [RFC6711] MAY be used as an acr value.
- amr
- OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the amr Claim is beyond the scope of this specification.
- azp
- OPTIONAL or REQUIRED. Authorized Party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 client_id of the Relying Party. This Claim is only REQUIRED when the party requesting the ID Token is not the same as the sole audience of the ID Token. It MAY be included even when the Authorized Party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.
- sub_jwk
- NOT RECOMMENDED or REQUIRED. Public key value used to check the signature of an ID Token issued by a Self-Issued OpenID Provider, as specified in Section 6 (Self-Issued OpenID Provider). The key is a bare key in JWK format (not an X.509 certificate value). Use of the sub_jwk Claim is REQUIRED when the OP is a Self-Issued OP and is NOT RECOMMENDED when the OP is not Self-Issued.
The JWT MAY contain other Claims. Any Claims used that are not understood MUST be ignored.
ID Tokens MUST be signed using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and OPTIONALLY both signed and then encrypted using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality, per Section 9.13 (Signing and Encryption Order).
ID Tokens SHOULD NOT use the JWS or JWE x5u, x5c, jku, or jwk header parameter fields. Instead, key values and key references used for ID Tokens are communicated in advance using Discovery and Registration parameters.
Clients MUST directly validate the ID Token per Section 4.2 (ID Token Validation).
The following is a non-normative example of a base64url decoded ID Token (with line wraps for display purposes only):
{ "iss": "https://server.example.com", "sub": "24400320", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "auth_time": 1311280969, "acr": "urn:mace:incommon:iap:silver", "at_hash": "MTIzNDU2Nzg5MDEyMzQ1Ng" }
TOC |
If the End-User denies the access request or if the request fails, the OP (Authorization Server) informs the RP (Client) by using the Error Response parameters defined in Sections 4.1.2.1 or 4.2.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], according to the response_type used.
In addition to the error codes defined in Sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0, this specification also defines the following error codes:
- interaction_required
- The Authorization Server requires End-User interaction of some form to proceed. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server should not display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End-User interaction.
- login_required
- The Authorization Server requires End-User authentication. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server should not display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for user authentication.
- session_selection_required
- The End-User is required to select a session at the Authorization Server. The End-User MAY be authenticated at the Authorization Server with different associated accounts, but the End-User did not select a session. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server should not display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface to prompt for a session to use.
- consent_required
- The Authorization Server requires End-User consent. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server should not display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End-User consent.
- invalid_request_uri
- The request_uri in the Authorization Request returns an error or contains invalid data.
- invalid_request_object
- The request parameter contains an invalid Request Object.
- registration_not_supported
- The OP does not support use of the registration parameter.
- request_not_supported
- The OP does not support use of the request parameter.
- request_uri_not_supported
- The OP does not support use of the request_uri parameter.
TOC |
The RP (Client) sends an Access Token Request to the Token Endpoint to obtain an Access Token Response, which MAY include an Access Token, a Refresh Token, an ID Token, and other results.
TOC |
During Client Registration, the RP (Client) MAY register an authentication method. If no method is registered, the default method of client_secret_basic MUST be used.
The Supported options are:
- client_secret_basic
- Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization Server in accordance with Section 3.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] using HTTP Basic authentication scheme.
- client_secret_post
- Clients that have received a client_secret value from the Authorization Server, authenticate with the Authorization Server in accordance with Section 3.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] by including the Client Credentials in the request body.
- client_secret_jwt
- Clients that have received a client_secret value from the Authorization Server create a JWT using an HMAC SHA algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of the UTF-8 representation of the client_secret as the shared key.
- The Client authenticates in accordance with Section 2.2 of OAuth JWT Bearer Token Profiles (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” March 2013.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) [OAuth.Assertions]. The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values:
- iss
- REQUIRED. Issuer. This MUST contain the client_id of the OAuth Client.
- sub
- REQUIRED. Subject. This MUST contain the client_id of the OAuth Client.
- aud
- REQUIRED. Audience. The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.
- jti
- REQUIRED. JWT ID. A unique identifier for the token. The JWT ID MAY be used by implementations requiring message de-duplication for one-time use assertions.
- exp
- REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
- iat
- OPTIONAL. Time at which the JWT was issued.
- The JWT MAY contain other Claims. Any Claims used that are not understood MUST be ignored.
- The authentication token MUST be sent as the value of the [OAuth.Assertions] (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) client_assertion parameter.
- The value of the [OAuth.Assertions] (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", per [OAuth.JWT] (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” March 2013.).
- private_key_jwt
- Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with Section 2.2 of OAuth JWT Bearer Token Profiles (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” March 2013.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) [OAuth.Assertions]. The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values:
- iss
- REQUIRED. Issuer. This MUST contain the client_id of the OAuth Client.
- sub
- REQUIRED. Subject. This MUST contain the client_id of the OAuth Client.
- aud
- REQUIRED. Audience. The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.
- jti
- REQUIRED. JWT ID. A unique identifier for the token. The JWT ID MAY be used by implementations requiring message de-duplication for one-time use assertions.
- exp
- REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
- iat
- OPTIONAL. Time at which the JWT was issued.
- The JWT MAY contain other Claims. Any Claims used that are not understood MUST be ignored.
- The authentication token MUST be sent as the value of the [OAuth.Assertions] (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) client_assertion parameter.
- The value of the [OAuth.Assertions] (Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” March 2013.) client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", per [OAuth.JWT] (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” March 2013.).
For example (with line wraps for display purposes only):
POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=i1WsRn1uB1& client_id=s6BhdRkqt3& client_assertion_type= urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT
TOC |
The Client obtains an Access Token by authenticating with the Authorization Server and presenting its Authorization Grant (in the form of an Authorization Code or Refresh Token).
In addition to the Client authentication parameters, if this is a Refresh Token Request, the Client MUST send the additional parameters specified in Section 6 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. Otherwise, the Client MUST send the request parameters as specified in Section 4.1.3 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
TOC |
After receiving and validating a valid and authorized Access Token Request from the Client, the Authorization Server returns a successful response that includes an Access Token and an ID Token. The parameters in the successful response are defined in Section 4.1.4 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
This specification only describes OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750]. The OAuth 2.0 response parameter token_type MUST be set to Bearer unless another Token Type has been negotiated with the Client. Servers SHOULD support OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] for interoperability. For security reasons Servers may only allow Clients to register specific token_type. Clients MUST support OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] and MAY support other token_type.
In addition to the OAuth 2.0 response parameters, the following parameters MUST be included in the response if the grant_type value is authorization_code and the Authorization Request scope parameter contained openid:
- id_token
- ID Token value associated with the authenticated session.
An id_token MUST be returned when the grant_type value is authorization_code and MAY be returned when other grant types are used.
Following is a non-normative example:
{ "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso" }
As in the OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], Clients SHOULD ignore unrecognized response parameters.
If an ID Token is returned as a result of a token refresh request, the following requirements apply:
TOC |
If the Token Request is invalid or unauthorized, the Authorization Server constructs the error response. The parameters of the Token Error Response are defined as in Section 5.2 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
TOC |
The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. The location of the UserInfo Endpoint MUST be a URL using the https scheme, which MAY contain port, path, and query parameter components.
TOC |
Clients send requests to the UserInfo Endpoint to obtain Claims about the End-User. The UserInfo Endpoint is an OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] Protected Resource that complies with the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification. The Access Token SHOULD be sent using the Authorization header field. The following parameters are defined for use in UserInfo Requests:
- access_token
- REQUIRED. Access Token obtained from an OpenID Connect Authorization Request.
TOC |
The UserInfo Claims MUST be returned as the members of a JSON object unless a signed or encrypted response was requested during Client Registration. The Claims defined in Section 2.5 (Standard Claims) can be returned, as can additional Claims not specified there.
If a Claim is not returned, that Claim Name SHOULD be omitted from the JSON object representing the Claims; it SHOULD NOT be present with a null or empty string value.
The sub (subject) Claim MUST always be returned in the UserInfo Response.
NOTE: The UserInfo Endpoint response is not guaranteed to be about the End-User identified by the sub (subject) element of the ID Token. The sub Claim in the UserInfo Endpoint response MUST be verified to exactly match the sub Claim in the ID Token before using additional UserInfo Endpoint Claims.
TOC |
When an error condition occurs, the UserInfo Endpoint returns an Error Response as defined in Section 3 of OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750].
TOC |
OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. This specification describes only the scope values used by OpenID Connect.
OpenID Connect allows additional scope values to be defined and used. Scope values used that are not understood by an implementation SHOULD be ignored.
Claims requested by the following scopes are treated by Authorization Servers as Voluntary Claims.
OpenID Connect defines the following scope values:
- openid
- REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the openid scope value is not present, the behavior is entirely unspecified.
- profile
- OPTIONAL. This scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
- OPTIONAL. This scope value requests access to the email and email_verified Claims.
- address
- OPTIONAL. This scope value requests access to the address Claim.
- phone
- OPTIONAL. This scope value requests access to the phone_number and phone_number_verified Claims.
- offline_access
- OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the user is not present (not logged in).
Multiple scope values MAY be used by creating a space delimited, case sensitive list of ASCII scope values.
The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 2.3.2 (UserInfo Response), when a response_type value is used that results in an Access Token being issued. However, when the response_type value used is id_token (which issues no Access Token), the resulting Claims are returned in the ID Token.
In some cases, the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by Clients. To minimize the amount of information that the user is being asked to disclose, a Client may elect to only request a subset of the information available from the UserInfo Endpoint.
The following is a non-normative example of a scope Request.
scope=openid profile email phone
TOC |
This specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response or in the ID Token.
Member | Type | Description |
---|---|---|
sub | string | Subject - Identifier for the End-User at the Issuer. |
name | string | End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences. |
given_name | string | Given name(s) or first name(s) of the End-User. Note that in some cultures, people may have multiple given names; all may be present, with the names being separated by space characters. |
family_name | string | Surname(s) or last name(s) of the End-User. Note that in some cultures, people may have multiple family names; all may be present, with the names being separated by space characters. |
middle_name | string | Middle name(s) of the End-User. Note that in some cultures, people may have multiple middle names; all may be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used. |
nickname | string | Casual name of the End-User that MAY or MAY not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael. |
preferred_username | string | Shorthand name that the End-User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. This value MUST NOT be relied upon to be unique by the RP. (See Section 2.5.3 (Claim Stability and Uniqueness).) |
profile | string | URL of the End-User's profile page. The contents of this Web page should be about the End-User. |
picture | string | URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User. |
website | string | URL of the End-User's Web page or blog. This Web page should contain information published by the End-User or an organization that the End-User is affiliated with. |
string | End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 (Resnick, P., Ed., “Internet Message Format,” October 2008.) [RFC5322] addr-spec syntax. This value MUST NOT be relied upon to be unique by the RP, as discussed in Section 2.5.3 (Claim Stability and Uniqueness). | |
email_verified | boolean | True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address must be verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. |
gender | string | End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable. |
birthdate | string | End-User's birthday, represented as an ISO 8601:2004 (International Organization for Standardization, “ISO 8601:2004. Data elements and interchange formats - Information interchange - Representation of dates and times,” 2004.) [ISO8601‑2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. Note that depending on the underlying platform's date related function, providing just year may result in varying month and day, so the implementers should take this factor into account to correctly process the dates. |
zoneinfo | string | String from zoneinfo [zoneinfo] (Public Domain, “The tz database,” June 2011.) time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles. |
locale | string | End-User's locale, represented as a BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 (International Organization for Standardization, “ISO 639-1:2002. Codes for the representation of names of languages -- Part 1: Alpha-2 code,” 2002.) [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 (International Organization for Standardization, “ISO 3166-1:1997. Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes,” 1997.) [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Implementations MAY choose to accept this locale syntax as well. |
phone_number | string | End-User's preferred telephone number. E.164 (International Telecommunication Union, “E.164: The international public telecommunication numbering plan,” 2010.) [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 (Schulzrinne, H., “The tel URI for Telephone Numbers,” December 2004.) [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678. |
phone_number_verified | boolean | True if the End-User's phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number must be verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in E.164 format and any extensions MUST be represented in RFC 3966 format. |
address | JSON object | End-User's preferred address. The value of the address member is a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] structure containing some or all of the members defined in Section 2.5.1 (Address Claim). |
updated_at | string | Time the End-User's information was last updated. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
Table 1: Reserved Member Definitions |
For privacy reasons, OpenID Providers MAY elect to not return values for some requested Claims.
The sub (subject) Claim in the UserInfo Endpoint response MUST exactly match the sub Claim in the ID Token, before using additional UserInfo Endpoint Claims.
The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during Registration [OpenID.Registration] (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.). The UserInfo Endpoint MAY return Claims in JWT format, which can be signed and/or encrypted. The UserInfo Endpoint MUST return a content-type header to indicate the format that is being returned. The following are accepted content types:
Content-Type | Format Returned |
---|---|
application/json | plain text JSON object |
application/jwt | JSON Web Token (JWT) |
The following is a non-normative example of such a response:
{ "sub": "248289761001", "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "preferred_username": "j.doe", "email": "janedoe@example.com", "picture": "http://example.com/janedoe/me.jpg" }
TOC |
The components of a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information.
Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields should be combined.
- formatted
- Full mailing address, formatted for display or use on a mailing label. This field MAY contain multiple lines, separated by newline characters. This is the primary member of this Claim value, for the purposes of sorting and filtering.
- street_address
- Full street address component, which may include house number, street name, Post Office Box, and multi-line extended street address information. This field MAY contain multiple lines, separated by newline characters.
- locality
- City or locality component.
- region
- State, province, prefecture or region component.
- postal_code
- Zip code or postal code component.
- country
- Country name component.
TOC |
Human-readable Claim Values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags are added to member names, delimited by a # character. For example, family_name#ja-Kana-JP expresses the Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same represented as family_name#ja-Hani-JP. As another example, both website and website#de Claim Values might be returned, referencing a Web site in an unspecified language and a Web site in German.
Since Claim Names are case sensitive, it is strongly RECOMMENDED that language tag values used in Claim Names be spelled using the character case with which they are registered in the IANA Language Subtag Registry (Internet Assigned Numbers Authority (IANA), “Language Subtag Registry,” 2005.) [IANA.Language]. In particular, normally language names are spelled with lowercase characters, region names are spelled with uppercase characters, and languages are spelled with mixed case characters. However, since BCP47 language tag values are case insensitive, implementations SHOULD interpret the language tag values supplied in a case insensitive manner.
Per the recommendations in BCP47, language tag values for Claims should only be as specific as necessary. For instance, using fr might be sufficient in many contexts, rather than fr-CA or fr-FR. Where possible, OPs should try to match requested Claim locales with Claims it has. For instance, if the Client asks for a Claim with a de (German) language tag and the OP has a value tagged with de-CH (Swiss German) and no generic German value, it would be appropriate for the OP to return the Swiss German value to the Client. (This intentionally moves as much of the complexity of language tag matching to the OP as possible, to simplify Clients.)
A claims_locales request can be used to specify the preferred languages and scripts to use for the returned Claims. Section 2.6.2 (Languages and Scripts for Individual Claims) describes how to request that specific Claims use particular languages and scripts.
When the OP determines, either through the claims_locales parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags.
TOC |
The sub (subject) and iss (issuer) Claims are the only Claims that a Client can rely upon as a stable identifier for the End-User, since the sub Claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2.1.2.1 (ID Token). Therefore, the only guaranteed unique identifier for a given End-User is the combination of the iss Claim and the sub Claim.
All other Claims carry no such guarantees across different issuers in terms of stability over time or uniqueness across users, and Issuers are permitted to apply local restrictions and policies. For instance, an Issuer MAY re-use an email Claim value across different End-Users at different points in time, and the claimed email address for a given End-User MAY change over time. Therefore, other Claims such as email, phone_number, and preferred_username and MUST NOT be used as unique identifiers for the End-User.
TOC |
While this specification defines only small set of Claims as standard Claims, other Claims MAY be used in conjunction with the standard Claims. When using such Claims, it is RECOMMENDED that collision resistant names be used for the Claim Names, as described in Section 4.2 (Public Claim Names) of the JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification. Alternatively, Private Claim Names can be safely used when naming conflicts are unlikely to arise, as described in 4.3 of the JWT specification. Or, if specific additional Claims will have broad and general applicability, they can be registered with Reserved Claim Names, per Sections 4.1 and 9.1 of the JWT specification.
TOC |
The claims parameter requests that specific Claims be returned from the UserInfo Endpoint and/or in the ID Token. It is represented as a JSON object containing lists of Claims being requested from these locations. Properties of the Claims being requested may also be specified.
Support for the claims parameter is OPTIONAL. Should an OP not support this parameter and an RP uses it, the OP SHOULD return a set of Claims to the RP that it believes would be useful to the RP and the End-User using whatever heuristics it believes are appropriate. The claims_parameter_supported Discovery result indicates whether the OP supports this parameter.
The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON (which ends up being form-urlencoded when passed as an OAuth parameter). When used in a Request Object value, per Section 2.9 (Request Object), the JSON is used as the value of the claims member.
The top-level members of the Claims request JSON object are:
- userinfo
- OPTIONAL. Requests that the listed individual Claims be returned from the UserInfo Endpoint. If present, the listed Claims are being requested to be added to any Claims that may have also been requested using scope values. If not present, the Claims being requested from the UserInfo Endpoint are only those requested using scope values.
- When the userinfo member is used, the request MUST also use a response_type value that results in an Access Token being issued to use at the UserInfo Endpoint.
- id_token
- OPTIONAL. Requests that the listed individual Claims be returned in the ID Token. If present, the listed Claims are being requested to be added to the default Claims in the ID Token. If not present, the default ID Token Claims are requested.
Other members MAY be present. Any members used that are not understood MUST be ignored.
An example Claims request is as follows:
{ "userinfo": { "given_name": {"essential": true}, "nickname": null, "email": {"essential": true}, "email_verified": {"essential": true}, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": {"essential": true}, "acr": {"values": ["urn:mace:incommon:iap:silver"] } } }
TOC |
The userinfo and id_token members of the claims request both are JSON objects with the names of the individual Claims being requested as the member names. The member values MUST be one of the following:
- null
- Indicates that this Claim is being requested in the default manner. In particular, this is a Voluntary Claim. For instance, the Claim request:
requests the given_name Claim in the default manner."given_name": null- JSON Object
- Used to provide additional information about the Claim being requested. This specification defines the following members:
Other members MAY be defined to provide additional information about the requested Claims. Any members used that are not understood MUST be ignored.
- essential
- OPTIONAL. Indicates whether the Claim being requested is an Essential Claim. If the value is true, this indicates that the Claim is an Essential Claim. For instance, the Claim request:
can be used to specify that it is Essential to return an auth_time Claim Value."auth_time": {"essential": true}- If the value is false, it indicates that it is a Voluntary Claim. The default is false.
- By requesting Claims as Essential Claims the Client indicates to the End-User that releasing these Claims will ensure a smooth authorization for the specific task requested by the End-User. Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary.
- value
- OPTIONAL. Requests that the Claim be returned with a particular value. For instance the Claim request:
can be used to specify that the request apply to the End-User with subject identifier 248289761001."sub": {"value": "248289761001"}- The value of the value member MUST be a valid value for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the value qualifier is to be used when requesting that Claim.
- values
- OPTIONAL. Requests that the Claim be returned with one of a set of values, with the values appearing in order of preference. For instance the Claim request:
specifies that it is Essential that the acr Claim be returned with either the value urn:mace:incommon:iap:silver or urn:mace:incommon:iap:bronze."acr": {"essential": true, "values": ["urn:mace:incommon:iap:silver", "urn:mace:incommon:iap:bronze"]}- The values in the values member array MUST be valid values for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the values qualifier is to be used when requesting that Claim.
Note that when the claims request parameter is supported, the scope values that request Claims, as defined in Section 2.4 (Scope Values), are effectively shorthand methods for requesting sets of individual Claims. For example, using the scope value openid email and a response_type that returns an Access Token is equivalent to using the scope value openid and the following request for individual Claims.
Equivalent of using the email scope value:
{ "userinfo": { "email": null, "email_verified": null } }
TOC |
As described in Section 2.5.2 (Claims Languages and Scripts), human-readable Claims values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. Within a request for individual Claims, requested languages and scripts for particular Claims may be requested by including Claim Names that contain #-separated BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags in the Claims request, using the Claim Name syntax specified in Section 2.5.2 (Claims Languages and Scripts). For example, a Family Name in Katakana in Japanese can be requested using the Claim Name family_name#ja-Kana-JP and a Kanji representation of the Family Name in Japanese can be requested using the Claim Name family_name#ja-Hani-JP. A German-language Web site can be requested with the Claim Name website#de.
If an OP receives a request for human-readable Claims in a language and script that it doesn't have, any versions of those Claims returned that don't use the requested language and script SHOULD use a language tag in the Claim Name.
TOC |
The UserInfo Endpoint MAY return the following three types of Claims:
- Normal Claims
- Claims that are directly asserted by the OpenID Provider.
- Aggregated Claims
- Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned by OpenID Provider.
- Distributed Claims
- Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned as references by the OpenID Provider.
The UserInfo Endpoint MUST support Normal Claims.
Aggregated and Distributed Claims support is OPTIONAL.
TOC |
Normal Claims are represented as members in a JSON object. The Claim Name is the member name and the Claim Value is the member value.
The following is a non-normative response containing Normal Claims:
{ "name": "Jane Doe" "given_name": "Jane", "family_name": "Doe", "email": "janedoe@example.com", "picture": "http://example.com/janedoe/me.jpg" }
TOC |
Aggregated and distributed Claims are represented by using special _claim_names and _claim_sources members of the JSON object containing the Claims.
- _claim_names
- JSON object whose member names are the Claim Names for the Aggregated and Distributed Claims. The member values are references to the member names in the _claim_sources member from which the actual Claim Values can be retrieved.
- _claim_sources
- JSON object whose member names are referenced by the member values of the _claim_names member. The member values contain sets of Aggregated Claims or reference locations for Distributed Claims. The member values can have one of the following formats depending on whether it is providing Aggregated or Distributed Claims:
- Aggregated Claims
- JSON object that MUST contain the JWT member whose value is a JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] that MUST contain all the Claims in the _claim_names object that references the corresponding _claim_sources member. Other members MAY be present. Any members used that are not understood MUST be ignored.
- JWT
- REQUIRED. JWT containing Claim Values.
- The JWT SHOULD NOT contain a sub (subject) Claim unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a sub Claim SHOULD NOT be provided.
- Distributed Claims
- JSON object that contains the following members and values:
- endpoint
- REQUIRED. OAuth 2.0 resource endpoint from which the associated Claim can be retrieved. The endpoint URL MUST return the Claim as a JWT.
- access_token
- OPTIONAL. Access Token enabling retrieval of the Claims from the endpoint URL by using the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] protocol. Claims SHOULD be requested using the Authorization Request header field and Claims Providers MUST support this method. If the Access Token is not available, Clients MAY need to retrieve the Access Token out of band or use an a priori Access Token that was negotiated between the Claims Provider and Client, or the Claims Provider MAY reauthenticate the End-User and/or reauthorize the Client.
- A sub (subject) Claim SHOULD NOT be returned from the Claims Provider unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a sub Claim SHOULD NOT be provided.
TOC |
In this non-normative example, Claims from Claims Provider A are combined with other Claims held by the OpenID provider, with the Claims from Claims Provider A being returned as Aggregated Claims.
In this example, these Claims about Jane Doe have been issued by Claims Provider A:
{ "address": { "street_address": "1234 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US"}, "phone_number": "+1 (310) 123-4567" }
Claims Provider A signs the JSON Claims, representing them in a signed JWT: jwt_header.jwt_part2.jwt_part3. It is this JWT that is used by the OpenID Provider.
In this example, this JWT containing Jane Doe's Aggregated Claims from Claims Provider A is combined with other Normal Claims, and returned as the following set of Claims:
{ "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "birthdate": "0000-03-22", "eye_color": "blue", "email": "janedoe@example.com", "_claim_names": { "address": "src1", "phone_number": "src1" }, "_claim_sources": { "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"} } }
TOC |
In this non-normative example, the OpenID Provider combines Normal Claims that it holds with references to Claims held by two different Claims Providers, B and C, incorporating references to some of the Claims held by B and C as Distributed Claims.
In this example, these Claims about Jane Doe are held by Claims Provider B (Jane Doe's bank):
{ "shipping_address": { "street_address": "1234 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US"}, "payment_info": "Some_Card 1234 5678 9012 3456", "phone_number": "+1 (310) 123-4567" }
Also in this example, this Claim about Jane Doe is held by Claims Provider C (a credit agency):
{ "credit_score": 650 }
The OpenID Provider returns Jane Doe's Claims along with references to the Distributed Claims from Claims Provider B and Claims Provider C by sending the Access Tokens and URLs of locations from which the Distributed Claims can be retrieved:
{ "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "email": "janedoe@example.com", "birthdate": "0000-03-22", "eye_color": "blue", "_claim_names": { "payment_info": "src1", "shipping_address": "src1", "credit_score": "src2" }, "_claim_sources": { "src1": {"endpoint": "https://bank.example.com/claim_source"}, "src2": {"endpoint": "https://creditagency.example.com/claims_here", "access_token": "ksj3n283dke"} } }
TOC |
The OpenID Provider's Discovery document SHOULD list its supported identifier types in the subject_types_supported element. If there is more than one type listed in the array, the Client MAY elect to provide its preferred identifier type using the subject_type parameter during Registration. The types supported by this specification are:
- public
- This provides the same sub (subject) value to all Clients. It is the default if the provider has no subject_types_supported element in its discovery document.
- pairwise
- This provides a different sub value to each Client, to prevent correlation of the user's activities by Clients without the user's permission.
TOC |
The OpenID Provider MUST calculate a unique sub (subject) value for each Sector Identifier. The subject value MUST NOT be reversible by any party other than the OpenID Provider.
Providers who use pairwise sub values SHOULD support the sector_identifier_uri in Dynamic Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration]. It provides a way for a group of websites under common administrative control to have consistent pairwise sub values independent of the individual domain names. It also provides a way for Clients to change redirect_uri domains without having to reregister all of their users.
If the Client has not provided a value for sector_identifier_uri in Dynamic Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration], the Sector Identifier used for pairwise identifier calculation is the host component of the registered redirect_uri. If there are multiple hostnames in the registered redirect_uris, the Client MUST register a sector_identifier_uri.
When a sector_identifier_uri is provided, the host component of that URL is used as the Sector Identifier for the pairwise identifier calculation. The value of the sector_identifier_uri must be a URL using the https scheme that points to a JSON file containing an array of redirect_uri values. The values of the registered redirect_uris must be included in the elements of the array, or the registration MUST fail.
A number of algorithms can be used by OpenID Providers to calculate pairwise identifiers. Three example methods are:
TOC |
The request parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. It represents the request as a JWT whose Claims are the request parameters specified in Section 2.1.1.1 (Request Parameters). This JWT is called a Request Object.
Support for the request parameter is OPTIONAL. The request_parameter_supported Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the request_not_supported error.
When the request parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a Request Object is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that may vary with each request, such as state and nonce, are passed as OAuth 2.0 parameters.
Even if a scope parameter is present in the Request Object value, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.
The Request Object MAY be signed or unsigned (plaintext). When it is plaintext, this is indicated by use of the none algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) in the JWS header. If signed, the Request Object SHOULD contain the Claims iss (issuer) and aud (audience) as members, with their semantics being as defined in the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification.
The Request Object MAY also be encrypted using JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE], with nested signing and encryption performed as described in the JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) specification.
request and request_uri parameters MUST NOT be included in Request Objects.
An example set of Request Object Claims before base64url encoding and JWS signing is as follows:
{ "response_type": "code id_token", "client_id": "s6BhdRkqt3", "redirect_uri": "https://client.example.org/cb", "scope": "openid", "state": "af0ifjsldkj", "login_hint": "janedoe@example.org", "max_age": 86400, "claims": { "userinfo": { "given_name": {"essential": true}, "nickname": null, "email": {"essential": true}, "email_verified": {"essential": true}, "picture": null }, "id_token": { "auth_time": {"essential": true}, "acr": { "values":["urn:mace:incommon:iap:silver"] } } } }
TOC |
The request_uri parameter enables OpenID Connect requests to be passed by reference, rather than by value. This parameter is used identically to the request parameter, other than that the Request Object value is retrieved from the resource at the specified URL, rather than passed by value.
The request_uri_parameter_supported Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the request_uri_not_supported error.
When the request_uri parameter is used, the OpenID Connect request parameter values contained in the referenced JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a request_uri is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that may vary with each request, such as state and nonce, are passed as OAuth 2.0 parameters.
Even if a scope parameter is present in the referenced Request Object, a scope parameter MUST always be passed using the OAuth 2.0 request syntax containing the openid scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request.
Servers MAY cache the contents of the resources referenced by request URIs. If the contents of the referenced resource could ever change, the URI SHOULD include the base64url encoded SHA-256 hash of the referenced resource contents as the fragment component of the URI. If the fragment value used for a URI changes, that signals the server that any cached value for that URI with the old fragment value is no longer valid.
Note that Clients MAY pre-register request_uri values using the request_uris parameter defined in Section 2 of the OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration] specification.
TOC |
There are several reasons that one might choose to use the request_uri parameter:
TOC |
Depending on the transport through which the messages are sent, the integrity of the message may not be guaranteed and the originator of the message may not be authenticated. To mitigate these risks, Request Object, Token Request, ID Token, and UserInfo Response values MAY utilize JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] to sign the contents.
To achieve message confidentiality, Request Object, Token Request, ID Token, and UserInfo Response values MAY use JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] to encrypt the content.
When the message is both signed and encrypted, it MUST be signed first and then encrypted, per Section 9.13 (Signing and Encryption Order), with nesting performed in the same manner as specified for JWTs [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.). Note that all JWE encryption methods perform integrity checking.
TOC |
The server advertises its supported signing and encryption algorithms in its discovery document. The algorithm identifiers are specified in JWA (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA]. The related elements are:
- userinfo_signing_alg_values_supported
- JSON array containing a list of the JWS [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) signing algorithms (alg values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- userinfo_encryption_alg_values_supported
- JSON array containing a list of the JWE [JWE] (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) encryption algorithms (alg values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- userinfo_encryption_enc_values_supported
- JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- id_token_signing_alg_values_supported
- JSON array containing a list of the JWS signing algorithms (alg values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- id_token_encryption_alg_values_supported
- JSON array containing a list of the JWE encryption algorithms (alg values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- id_token_encryption_enc_values_supported
- JSON array containing a list of the JWE encryption algorithms (enc values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
- request_object_signing_alg_values_supported
- JSON array containing a list of the JWS signing algorithms (alg values) supported by the Authorization Server for Request Object values. Servers SHOULD support none and RS256.
- request_object_encryption_alg_values_supported
- JSON array containing a list of the JWE encryption algorithms (alg values) supported by the Authorization Server for Request Object values.
- request_object_encryption_enc_values_supported
- JSON array containing a list of the JWE encryption algorithms (enc values) supported by the Authorization Server for Request Object values.
- token_endpoint_auth_signing_alg_values_supported
- JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the private_key_jwt and client_secret_jwt methods to encode the JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.). Servers SHOULD support RS256.
The Client registers its required algorithms for Signing and Encryption using the following Registration parameters:
- request_object_signing_alg
- OPTIONAL. JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for Request Objects by the Authorization Server. All Request Objects from this client_id MUST be rejected if not signed by this algorithm. Servers SHOULD support RS256.
- userinfo_signed_response_alg
- OPTIONAL. JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for UserInfo Responses. If this is specified the response will be JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] serialized.
- userinfo_encrypted_response_alg
- OPTIONAL. JWE alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for UserInfo Responses. If this is requested in combination with signing, the response MUST be signed first then encrypted, per Section 9.13 (Signing and Encryption Order). If this is specified, the response will be JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] serialized.
- userinfo_encrypted_response_enc
- OPTIONAL. JWE enc algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for UserInfo Responses. If userinfo_encrypted_response_alg is specified the default for this value is A128CBC-HS256.
- id_token_signed_response_alg
- OPTIONAL. JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for ID Tokens issued to this client_id. The default if not specified is RS256. The public key for validating the signature is provided by retrieving the JWK Set referenced by the jwks_uri element from Discovery.
- id_token_encrypted_response_alg
- OPTIONAL. JWE alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for ID Tokens issued to this client_id. If this is requested, the response MUST be signed then encrypted. The default if not specified is no encryption.
- id_token_encrypted_response_enc
- OPTIONAL. JWE enc algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) required for ID Tokens issued to this client_id. If id_token_encrypted_response_alg is specified the default for this value is A128CBC-HS256.
TOC |
The OpenID Provider provides its public keys during Discovery using the following element:
- jwks_uri
- REQUIRED. URL of the OP's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” May 2013.) document. This contains the signing key(s) the Client uses to validate signatures from the OP. The JWK Set MAY also contain the Server's encryption key(s), which are used by Clients to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the document to indicate each key's intended usage.
Likewise, the Client can provide its public keys during Registration using the following element:
- jwks_uri
- OPTIONAL. URL for the Client's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” May 2013.) document. If the Client signs requests to the Server, it contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain the Client's encryption keys(s), which are used by the Server to encrypt responses to the Client. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the document to indicate each key's intended usage.
When both signing and encryption keys are made available, the use (Key Use) parameter value is REQUIRED for all keys in the JWK Set at the jwks_uri to indicate each key's intended usage. Although some algorithms allow the same key pair to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure.
In both cases, the JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.
TOC |
The signing party MUST select a signature algorithm based on the supported algorithms of the recipient in Section 3.1 (Supported Algorithms).
- Asymmetric Signatures
- When using RSA or ECDSA Signatures, the alg Claim of the JWS header MUST be set to the appropriate algorithm as defined in JSON Web Algorithms (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA]. The private key MUST be the one associated with the Public Signing Key provided in Section 3.2 (Keys). If there are multiple keys in the referenced JWK document, a kid value MUST be provided in the JWS header. The key usage of the respective keys MUST support signature.
- Symmetric Signatures
- When using MAC-based signatures, the alg Claim of the JWS header MUST be set to a MAC algorithm, as defined in JSON Web Algorithms (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA]. The MAC key used is the octets of the UTF-8 representation of the client_secret value. See Section 9.17 (Symmetric Key Entropy) for a discussion of entropy requirements for client_secret values.
See Section 9.18 (Need for Signed Requests) for Security Considerations about the need for signed requests.
TOC |
Rotation of signing keys can be accomplished with the following approach. The signer publishes its keys in a JWK Set at the jwks_uri location and includes the kid of the signing key in the JWS header of each message to indicate to the verifier which key is to be used to validate the signature. Keys can be rolled over by periodically adding new keys to the JWK Set at jwks_uri. The signer can begin using a new key at its discretion and signals the change to the verifier using the kid value. The verifier knows to go back to the jwks_uri to re-retrieve the keys when it sees an unfamiliar kid value. The JWK Set document at the jwks_uri should retain recently decommissioned signing keys for a reasonable period of time to facilitate a smooth transition.
TOC |
The encrypting party MUST select an encryption algorithm based on the supported algorithms of the recipient in Section 3.1 (Supported Algorithms). All JWTs MUST be signed before encryption to enable verification of the Issuer.
- Asymmetric Encryption: RSA
- Use the link registered/discovered in Section 3.2 (Keys) to retrieve the relevant key. If there are multiple keys in the referenced JWK document, a kid value MUST be provided in the JWE header. Use the supported RSA key wrapping algorithm to wrap a random Content Master Key to be used for encrypting the signed JWT. The key usage of the respective keys MUST include encryption.
- Asymmetric Encryption: Elliptic Curve
- Create an ephemeral Elliptic Curve public key for the epk element of the JWE header. Use the link registered/discovered in Section 3.2 (Keys) to retrieve the relevant key. If there are multiple keys in the referenced JWK document, a kid value MUST be provided in the JWE header. Use the ECDH-ES algorithm to wrap a random Content Master Key to be used for encrypting the signed JWT. The key usage of the respective keys MUST support encryption.
- Symmetric Encryption
- The symmetric encryption key is derived from the client_secret value by using a left truncated SHA-256 hash of the octets of the UTF-8 representation of the client_secret. The SHA-256 value MUST be left truncated to the appropriate bit length for the AES key wrapping algorithm used, for instance, to 128 bits for A128KW. If a key wrapping key with greater than 256 bits is needed, a different method of deriving the key from the client_secret would have to be defined by an extension.
See Section 9.19 (Need for Encrypted Requests) for Security Considerations about the need for encrypted requests.
TOC |
Rotating encryption keys is necessarily a different process than for signing keys because the encrypting party starts the process and thus cannot rely on a change in kid as a signal to know that keys need to change. The encrypting party still uses the kid header in the JWE to tell the decrypting party which private key to use to decrypt, however, the encrypting party needs to first select the most appropriate key from those provided in the JWK Set at jwks_uri. To rotate keys, the decrypting party can publish new keys at jwks_uri and remove from the JWK Set those that are being decommissioned. The jwks_uri should include a Cache-Control header in the response that contains a max-age directive, as defined in RFC 2616 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616], which allows the encrypting party to safely cache the JWK Set and not have to re-retrieve the document for every encryption event. The decrypting party should remove decommissioned keys from the JWK Set at jwks_uri but retain them internally for some reasonable period of time, coordinated with the cache duration, to facilitate a smooth transition between keys by allowing the encrypting party some time to obtain the new keys. The cache duration should also be coordinated with the issuance of new signing keys as described in Section 3.3.1 (Rotation of Asymmetric Signing Keys).
TOC |
If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used.
TOC |
Authorization Request Validation consists of two main steps: (1) decryption and signature validation of the value of request or the content of request_uri, and (2) parameter validation. If a Request Object value was sent in the request parameter or by reference in the request_uri parameter, the Request Object MUST validate as JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] or JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] encoded objects, for which nested encryption and signing may have been performed in the manner described in the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification.
TOC |
If the Authorization Server has advertised JWE encryption algorithms in the request_object_encryption_alg_values_supported and request_object_encryption_enc_values_supported elements of its Discovery Document, these are used by the Client to encrypt the JWT.
The Authorization Server MUST decode the JWT in accordance with the JSON Web Encryption (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] specification. The result MAY be either a signed or unsigned (plaintext) Request Object. In the former case, signature validation MUST be performed as defined in Section 4.1.2 (Signed Request Object).
The Authorization Server MUST return the error if there is a decryption error.
TOC |
To perform Signature Validation, the alg parameter in the JWS header MUST match the value of the request_object_signing_alg set during Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration] or a value that was pre-registered by other means.
The signature must be validated against the key registered for that client_id and algorithm, in accordance with the JSON Web Signature (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] specification.
The Authorization Server MUST return the Authorization Error Response if there is a signature validation error.
TOC |
The Authorization Server MUST construct the Authorization Request Message from the Request Object value and the OAuth 2.0 Authorization Request parameters. If the same parameter exists both in the Request Object and the OAuth Authorization Request parameters, the parameter in the Request Object is used. Using this Authorization Request Message, the Authorization Server performs the following steps of the request validation:
If the Authorization Server encounters any error, it MUST return the error response.
TOC |
To validate the ID Token in the Authorization or Token Endpoint Response, the Client MUST do the following:
TOC |
To validate the UserInfo Response, the Client MUST do the following:
TOC |
To validate an Access Token issued from the Authorization Endpoint with an ID Token in response to a request containing a response_type of token id_token or code token id_token, the Client SHOULD do the following:
TOC |
To validate a code issued from the Authorization Endpoint with an ID Token in response to a request containing a response_type of code id_token or code token id_token, the Client SHOULD do the following:
TOC |
The offline_access scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the user is not present (not logged in). When offline access is requested, a prompt parameter value of consent MUST be used. The user MUST always explicitly consent to the return of a Refresh Token that enables offline access. A previously saved user consent is not sufficient to grant offline access.
Upon receipt of a scope parameter containing the offline_access value, the Authorization Server:
The use of Refresh Tokens is not exclusive to the offline_access use case. The Authorization Server MAY grant Refresh Tokens in other contexts that are beyond the scope of this specification.
TOC |
OpenID Connect supports Self-Issued OpenID Providers - personal OPs that issue self-signed ID Tokens. Self-Issued OPs use the special Issuer Identifier https://self-issued.me.
TOC |
If the input identifier for the discovery process contains the domain self-issued.me, dynamic discovery is not performed. Instead, then the following static configuration values are used:
{ "authorization_endpoint": "openid:", "issuer": "https://self-issued.me", "scopes_supported": ["openid", "profile", "email", "address", "phone"], "response_types_supported": ["id_token"], "subject_types_supported": ["pairwise"], "id_token_signing_alg_values_supported": ["RS256"], "request_object_signing_alg_values_supported": ["none", "RS256"] }
Note: The OpenID Foundation may consider hosting a site https://self-issued.me/ that returns the above static configuration file so that the Client would not need any special treatment for discovery of the Self-Issued OP.
TOC |
When using a Self-Issued OP, the Client is deemed to have registered with the OP and obtained following Client Registration Response.
- client_id
- redirect_uri value of the Client.
- client_secret_expires_at
- 0
Note: The OpenID Foundation may consider hosting the (stateless) endpoint https://self-issued.me/registration/1.0/ that returns the response above so that the Client would not need to perform any special processing for registration of a Self-Issued OP.
TOC |
The registration request parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration. The value is a JSON object containing name/value pairs defined in Section 2.1 of the OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration] specification. None of this information is required by Self-Issued OPs, so the use of this parameter is OPTIONAL.
The registration parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON (which ends up being form-urlencoded when passed as an OAuth parameter). When used in a Request Object value, per Section 2.9 (Request Object), the JSON is used as the value of the registration member.
The Registration parameters that would typically be used in requests to Self-Issued OPs are policy_uri, tos_uri, and logo_uri. If the Client uses more than one redirect URI, the redirect_uris parameter would be used to register them. Finally, if the Client is requesting encrypted responses, it would use the jwks_uri, id_token_encrypted_response_alg and id_token_encrypted_response_enc parameters.
TOC |
The Client sends the Authorization Request to the Authorization Endpoint with the following parameters:
- response_type
- REQUIRED. Constant string value id_token.
- client_id
- REQUIRED. Client ID value for the Client, which in this case contains the redirect_uri value of the Client. Since the Client's redirect_uri URI value is communicated as the Client ID, a redirect_uri parameter is NOT REQUIRED to also be included in the request.
- scope
- REQUIRED. scope parameter value, as specified in Section 2.4 (Scope Values).
- id_token_hint
- OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. This SHOULD be present when prompt=none is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response.
- If the ID Token received by the RP is encrypted, the Client MUST decrypt the signed ID Token contained within the encrypted ID Token. The Client MAY re-encrypt the signed ID token to the Authentication Server using a key that enables the server to decrypt the ID Token. In this case, the sub (subject) of the signed ID Token MUST be sent as the kid (Key ID) of the JWE. Encrypting content to Self-Issued OPs is currently only supported when the OP's JWK key type is RSA and the encryption algorithm used is RSA1_5.
- claims
- OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object, as specified in Section 2.6 (Claims Request).
- registration
- OPTIONAL. This parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration, as specified in Section 6.2.1 (Providing Additional Registration Information).
- request
- OPTIONAL. Request Object value, as specified in Section 2.9 (Request Object). The Request Object may be encrypted in a JWE by the Client. In this case, the sub (subject) of a previously issued ID Token for this Client MUST be sent as the kid (Key ID) of the JWE. Encrypting content to Self-Issued OPs is currently only supported when the OP's JWK key type is RSA and the encryption algorithm used is RSA1_5.
Other parameters MAY be sent. Note that all Claims are returned in the ID Token.
The entire URL MUST NOT exceed 2048 ASCII characters.
Following is a non-normative example (with line wraps for display purposes only):
HTTP/1.1 302 Found Location: openid:// ?response_type=id_token &client_id=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj registration=&%7B%22logo_uri%22%3A%22https%3A%2F%2F client.example.org%2Flogo.png%22%7D
TOC |
The Self-Issued OpenID Provider response is the same as the normal implicit flow response with the following refinements. Since it is an implicit flow response, the response parameters will be returned in a fragment.
TOC |
If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used.
To validate the ID Token in the Authorization or Token Endpoint Response, the Client MUST do the following:
The following is a non-normative example of a base64url decoded Self-Issued ID Token (with line wraps for display purposes only):
{ "iss": "https://self-issued.me", "sub": "wBy8QvHbPzUnL0x63h13QqvUYcOur1X0cbQpPVRqX5k", "aud": "https://client.example.org/cb", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "sub_jwk": { "kty":"RSA", "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", "e":"AQAB" } }
TOC |
Processing some OpenID Connect messages requires comparing values in the messages to known values. For example, the Claim Names returned by the UserInfo Endpoint might be compared to specific Claim Names such as sub. Comparing Unicode strings, however, has significant security implications.
Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below:
In several places, this specification uses space delimited lists of strings. In all such cases, only the ASCII space character (0x20) MAY be used for this purpose.
TOC |
This specification defines features used by both Relying Parties and OpenID Providers. Features that are mandatory to implement for Relying Parties are already described in the OpenID Connect Basic Client Profile 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” May 2013.) [OpenID.Basic] and OpenID Connect Implicit Client Profile 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” May 2013.) [OpenID.Implicit] specifications, and so are not discussed again here.
It is expected that some OpenID Providers will require static, out-of-band configuration of RPs using them, whereas others will support dynamic usage by RPs without a pre-established relationship between them. For that reason, the mandatory-to-implement features for OPs are listed below in two groups: the first for all OPs and the second for "Dynamic" OpenID Providers.
TOC |
All OpenID Providers MUST implement the following features defined in this specification. This list augments the set of features that are already listed elsewhere as being "REQUIRED" or are described with a "MUST", and so is not, by itself, a comprehensive set of implementation requirements for OPs.
- Signing ID Tokens with RSA SHA-256
- OPs MUST support signing ID Tokens with the RSA SHA-256 algorithm (an alg value of RS256).
- Prompt Parameter
- OPs must support the prompt parameter, as defined in Section 2.1.1.1 (Request Parameters), including the specified user interface behaviors such as none and login.
- Display Parameter
- OPs must support the display parameter, as defined in Section 2.1.1.1 (Request Parameters). (Note that the minimum level of support required for this parameter is simply to have its use not result in an error.)
- Preferred Locales
- OPs MUST support requests for preferred languages and scripts for the user interface and for Claims via the ui_locales and claims_locales request parameters, as defined in Section 2.1.1.1 (Request Parameters). (Note that the minimum level of support required for these parameters is simply to have their use not result in errors.)
- Authentication Time
- OPs MUST support returning the time at which the user authenticated via the auth_time Claim, as defined in Section 2.1.2.1 (ID Token).
- Maximum Authentication Age
- OPs MUST support enforcing a maximum authentication age via the max_age parameter, as defined in Section 2.1.1.1 (Request Parameters).
- Authentication Context Class Reference
- OPs MUST support requests for specific Authentication Context Class Reference values via the acr_values parameter, as defined in Section 2.1.1.1 (Request Parameters). (Note that the minimum level of support required for this parameter is simply to have its use not result in an error.)
TOC |
In addition to the features listed above, OpenID Providers supporting dynamic establishment of relationships with RPs that they do not have a pre-configured relationship with MUST also implement the following features defined in this and related specifications.
- Discovery
- These OPs MUST support Discovery, as defined in OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” May 2013.) [OpenID.Discovery].
- Dynamic Registration
- These OPs MUST support Dynamic Client Registration, as defined in OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013.) [OpenID.Registration].
- UserInfo Endpoint
- All dynamic OPs that issue Access Tokens MUST support the UserInfo Endpoint, as defined in Section 2.3 (UserInfo Endpoint). (Self-Issued OPs do not issue Access Tokens.)
- Public Keys Published as Bare Keys
- These OPs MUST publish their public keys as bare keys, rather than in in X.509 format.
- Request URI
- These OPs MUST support requests made using a Request Object value that is retrieved from a Request URI that is provided with the request_uri parameter, as defined in Section 2.1.1.1 (Request Parameters).
TOC |
This specification is an abstract specification. It needs to be bound to a protocol to be used in practice. One such example of protocol binding is:
These related OpenID Connect specifications MAY OPTIONALLY be used in combination with this specification to provide additional functionality:
TOC |
OAuth 2.0 Threat Model and Security Considerations (Lodderstedt, T., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.) [RFC6819] provides an extensive list of threats and controls that applies to this standard as well. ISO/IEC 29115 (International Organization for Standardization, “ISO/IEC FDIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” December 2012.) [ISO29115] also provides threats and controls that implementers should take into account. In addition, this standard provides additional control measures listed below.
TOC |
If appropriate measures are not taken, a request may be disclosed to an attacker, posing security and privacy threats.
In addition to what is stated in Section 5.1.1 of [RFC6819] (Lodderstedt, T., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.), this standard provides a way to provide the confidentiality of the request end to end through the use of request or request_uri parameters, where the content of the request is an encrypted JWT with the appropriate key and cipher. This protects even against a compromised User-Agent in the case of indirect request.
TOC |
A malicious Server may masquerade as the legitimate server using various means. To detect such an attack, the Client needs to authenticate the server.
In addition to what is stated in Section 5.1.2 of [RFC6819] (Lodderstedt, T., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.), this standard provides a way to authenticate the Server through either the use of Signed or Encrypted JWTs with an appropriate key and cipher.
TOC |
An Attacker may generate a bogus token or modify the token content (such as the authentication or attribute statements) of an existing parseable token, causing the RP to grant inappropriate access to the Client. For example, an Attacker may modify the parseable token to extend the validity period; a Client may modify the parseable token to have access to information that they should not be able to view.
There are two ways to mitigate this attack:
TOC |
Server response may contain authentication and attribute statements that include sensitive Client information. Disclosure of the response contents can make the Client vulnerable to other types of attacks.
The server response disclosure can be mitigated in the following two ways:
TOC |
A response may be repudiated by the server if the proper mechanisms are not in place. For example, if a Server does not digitally sign a response, the Server can claim that it was not generated through the services of the Server.
To mitigate this threat, the response may be digitally signed by the Server using a key that supports non-repudiation. The Client SHOULD validate the digital signature to verify that it was issued by a legitimate Server and its integrity is intact.
TOC |
Since it is possible for a compromised or malicious Client to send a request to the wrong party, a Client that was authenticated using only a bearer token can repudiate any transaction.
To mitigate this threat, the Server MAY require that the request be digitally signed by the Client using a key that supports non-repudiation. The Server SHOULD validate the digital signature to verify that it was issued by a legitimate Client and the integrity is intact.
TOC |
An Attacker uses the Access Token generated for one resource to obtain access to a second resource.
To mitigate this threat, the Access Token should be audience and scope restricted. One way of implementing it is to include the identifier of the resource for whom it was generated as audience. The resource verifies that incoming tokens include its identifier as the audience of the token.
TOC |
An Attacker attempts to use a one-time use token such as an Authorization Code that has already been used once with the intended Resource. To mitigate this threat, the token SHOULD include a timestamp and a short validity lifetime. The Relying Party then checks the timestamp and lifetime values to ensure that the token is currently valid.
Alternatively, the server may record the state of the use of the token and check the status for each request.
TOC |
In addition to the attack patterns described in Section 4.4.1.1 of [RFC6819] (Lodderstedt, T., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.), an Authorization Code can be captured in the User-Agent where the TLS session is terminated if the User-Agent is infected by malware. However, capturing it is not useful as long as the profile uses either Client authentication or an encrypted response.
TOC |
A user may attempt to impersonate a more privileged user by subverting the communication channel between the Token Endpoint and Client, for example by reordering the messages, to convince the Token Endpoint that his or her authorization grant corresponds to the grant sent on behalf of the more privileged user.
Responses to Token Requests are bound to the corresponding requests by message order in HTTP, as both token and requests are protected by TLS that can detect and disallow malicious reordering of packets.
TOC |
A timing attack allows the attacker to obtain an unnecessary large amount of information through the elapsed time differences in the code paths taken by successful and unsuccessful decryption operations or successful and unsuccessful signature validation of a message. It can be used to reduce the effective key length of the cipher used.
Implementations should not terminate the validation process at the instant of the finding an error but should continue running until all the octets have been processed to avoid this attack.
TOC |
There are various crypto related attacks possible depending on the method used for encryption and signature / integrity checking. Implementers should consult the Security Considerations for the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] specification and specifications that it references to avoid the vulnerabilities identified in these specifications.
TOC |
Signatures over encrypted text are not considered valid in many jurisdictions. Therefore, for integrity and non-repudiation, this specification requires signing the plain text JSON Claims.
TOC |
OpenID Connect supports multiple issuers per Host and Port combination. The issuer returned by discovery MUST exactly match the value of iss in the ID Token.
OpenID Connect treats the path component of any URI as part of the user identifier. For instance, the subject "1234" with an issuer of "https://example.com" is not equivalent to the subject "1234" with an issuer of "https://example.com/sales".
It is RECOMMENDED that only a single issuer per host be used.
TOC |
Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 [RFC5246] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) is the most recent version, but has very limited actual deployment, and might not be readily available in implementation toolkits. TLS version 1.0 [RFC2246] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) is the most widely deployed version, and will give the broadest interoperability.
To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.
Whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125 (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),” March 2011.) [RFC6125].
TOC |
Access Token grants are not revocable by the Authorization Server. Access Token grant lifetimes SHOULD be kept to single use or very short lifetimes.
If access to the UserInfo Endpoint or other protected resources is required, a Refresh Token should be used. The Client may then exchange the Refresh Token at the Token Endpoint for a fresh short-lived Access Token that can be used to access the resource.
The Authorization Server SHOULD clearly identify long-term grants to the User during Authorization. The Authorization Server SHOULD provide a mechanism for the user to revoke Refresh Tokens granted to a Client.
TOC |
In Section 3.3 (Signing) and Section 3.4 (Encryption), keys are derived from the client_secret value. Thus, when used with symmetric signing or encryption operations, client_secret values MUST contain sufficient entropy to generate cryptographically strong keys. Also, client_secret values MUST also contain at least the minimum of number of octets required for MAC keys for the particular algorithm used. So for instance, for HS256, the client_secret value MUST contain at least 8 octets (and almost certainly SHOULD contain more, since client_secret values are likely to use a restricted alphabet.
TOC |
In some situations, Clients may need to use signed requests to ensure that the desired request parameters are delivered to the OP without having been tampered with. For instance, the max_age and acr_values provide more assurance about the nature of the authentication performed when delivered in signed requests.
TOC |
In some situations, knowing the contents of an OpenID Connect request may, in and of itself, reveal sensitive information about the End-User. For instance, knowing that the Client is requesting a particular Claim or that it is requesting that a particular authentication method be used may reveal sensitive information about the End-User. OpenID Connect enables requests to be encrypted to the OpenID Provider to prevent such potentially sensitive information from being revealed.
TOC |
The UserInfo Response typically contains Personally Identifiable Information (PII). As such, End-User consent for the release of the information for the specified purpose SHOULD be obtained at or prior to the authorization time in accordance with relevant regulations. The purpose of use is typically registered in association with the redirect_uris.
Only necessary UserInfo data should be stored at the Client and the Client SHOULD associate the received data with the purpose of use statement.
The Resource Server SHOULD make the UserInfo access log available to the End-User so that the End-User can monitor who accessed his data.
To protect the End-User from a possible correlation among Clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the sub SHOULD be considered.
TOC |
TOC |
This specification registers the Claims defined in Section 2.5 (Standard Claims) and Section 2.1.2.1 (ID Token) in the IANA JSON Web Token Claims registry defined in [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).
TOC |
TOC |
This specification registers the following parameters in the IANA OAuth Parameters registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
TOC |
TOC |
This specification registers the following errors in the IANA OAuth Extensions Error registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
TOC |
TOC |
TOC |
[E.164] | International Telecommunication Union, “E.164: The international public telecommunication numbering plan,” 2010. |
[IANA.Language] | Internet Assigned Numbers Authority (IANA), “Language Subtag Registry,” 2005. |
[ISO29115] | International Organization for Standardization, “ISO/IEC FDIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” ISO/IEC 29115, December 2012. |
[ISO3166-1] | International Organization for Standardization, “ISO 3166-1:1997. Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes,” 1997. |
[ISO639-1] | International Organization for Standardization, “ISO 639-1:2002. Codes for the representation of names of languages -- Part 1: Alpha-2 code,” 2002. |
[ISO8601-2004] | International Organization for Standardization, “ISO 8601:2004. Data elements and interchange formats - Information interchange - Representation of dates and times,” 2004. |
[ITU.X690.1994] | International Telecommunications Union, “Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER),” ITU-T Recommendation X.690, 1994. |
[JWA] | Jones, M., “JSON Web Algorithms (JWA),” draft-ietf-jose-json-web-algorithms (work in progress), May 2013 (HTML). |
[JWE] | Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” draft-ietf-jose-json-web-encryption (work in progress), May 2013 (HTML). |
[JWK] | Jones, M., “JSON Web Key (JWK),” draft-ietf-jose-json-web-key (work in progress), May 2013 (HTML). |
[JWS] | Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” draft-ietf-jose-json-web-signature (work in progress), May 2013 (HTML). |
[JWT] | Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” draft-ietf-oauth-json-web-token (work in progress), May 2013 (HTML). |
[OAuth.Assertions] | Campbell, B., Mortimore, C., Jones, M., and Y. Goland, “Assertion Framework for OAuth 2.0,” draft-ietf-oauth-assertions (work in progress), March 2013 (HTML). |
[OAuth.JWT] | Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” draft-ietf-oauth-jwt-bearer (work in progress), March 2013 (HTML). |
[OAuth.Responses] | de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” March 2013. |
[OpenID.Discovery] | Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” May 2013. |
[OpenID.Registration] | Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” May 2013. |
[RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
[RFC2246] | Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” RFC 2246, January 1999 (TXT). |
[RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML). |
[RFC3339] | Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML). |
[RFC3966] | Schulzrinne, H., “The tel URI for Telephone Numbers,” RFC 3966, December 2004 (TXT). |
[RFC4627] | Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT). |
[RFC4648] | Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” RFC 4648, October 2006 (TXT). |
[RFC5246] | Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT). |
[RFC5280] | Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile,” RFC 5280, May 2008 (TXT). |
[RFC5322] | Resnick, P., Ed., “Internet Message Format,” RFC 5322, October 2008 (TXT, HTML, XML). |
[RFC5646] | Phillips, A. and M. Davis, “Tags for Identifying Languages,” BCP 47, RFC 5646, September 2009 (TXT). |
[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, March 2011 (TXT). |
[RFC6711] | Johansson, L., “An IANA Registry for Level of Assurance (LoA) Profiles,” RFC 6711, August 2012 (TXT). |
[RFC6749] | Hardt, D., “The OAuth 2.0 Authorization Framework,” RFC 6749, October 2012 (TXT). |
[RFC6750] | Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” RFC 6750, October 2012 (TXT). |
[RFC6819] | Lodderstedt, T., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” RFC 6819, January 2013 (TXT). |
[USA15] | Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” Unicode Standard Annex 15, 09 2009. |
[zoneinfo] | Public Domain, “The tz database,” June 2011. |
TOC |
[OpenID.2.0] | OpenID Foundation, “OpenID Authentication 2.0,” December 2007 (TXT, HTML). |
[OpenID.Basic] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” May 2013. |
[OpenID.Implicit] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” May 2013. |
[OpenID.PAPE] | Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008 (TXT, HTML). |
[OpenID.Session] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” May 2013. |
[OpenID.Standard] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” May 2013. |
TOC |
As a successor version of OpenID, this specification heavily relies on ideas explored in OpenID Authentication 2.0 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0]. Please refer to Appendix C of OpenID Authentication 2.0 for the full list of the contributors for that specification.
In addition, the OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification.
Naveen Agarwal (naa@google.com), Google
Amanda Anganes (aanganes@mitre.org), Mitre
Casper Biering (cb@peercraft.com), Peercraft
John Bradley (ve7jtb@ve7jtb.com), Ping Identity
Johnny Bufu (jbufu@janrain.com), Janrain
Tim Bray (tbray@textuality.com), Google
Brian Campbell (bcampbell@pingidentity.com), Ping Identity
Breno de Medeiros (breno@gmail.com), Google
Pamela Dingle (pdingle@pingidentity.com), Ping Identity
Vladimir Dzhuvinov (vladimir@nimbusds.com), NimbusDS
George Fletcher (george.fletcher@corp.aol.com), AOL
Roland Hedberg (roland.hedberg@adm.umu.se), Independent
Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.
Edmund Jay (ejay@mgi1.com), Illumila
Michael B. Jones (mbj@microsoft.com), Microsoft
Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom
Nov Matake (nov@matake.jp), Independent
Chuck Mortimore (cmortimore@salesforce.com), Salesforce
Anthony Nadalin (tonynad@microsoft.com), Microsoft
Hideki Nara (hideki.nara@gmail.com), Takt Communications
Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom
David Recordon (dr@fb.com), Facebook
Justin Richer (jricher@mitre.org), Mitre
Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.
Luke Shepard (lshepard@fb.com), Facebook
Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET
Paul Tarjan (pt@fb.com), Facebook
TOC |
Copyright (c) 2013 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.
TOC |
[[ To be removed from the final specification ]]
-19
-18
-17
-16
-15
-14
-13
-12
-11
-10
-09
-08
-07
-06
-05
-04
-03
-02
-01
TOC |
Nat Sakimura | |
Nomura Research Institute, Ltd. | |
Email: | n-sakimura@nri.co.jp |
John Bradley | |
Ping Identity | |
Email: | ve7jtb@ve7jtb.com |
Michael B. Jones | |
Microsoft | |
Email: | mbj@microsoft.com |
Breno de Medeiros | |
Google Inc. | |
Email: | breno@google.com |
Chuck Mortimore | |
Salesforce | |
Email: | cmortimore@salesforce.com |
Edmund Jay | |
Illumila | |
Email: | ejay@mgi1.com |