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 RESTful 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.
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.
OpenID Request Object
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.
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.
Standard Claims
2.4.1.
Address Claim
2.4.2.
Claim Stability and Uniqueness
2.5.
Subject Identifier Types
2.5.1.
Pairwise Identifier Algorithm
2.6.
Claim Types
2.6.1.
Normal Claims
2.6.2.
Aggregated and Distributed Claims
3.
Serializations
3.1.
JSON Serialization
4.
Signatures and Encryption
4.1.
Supported Algorithms
4.2.
Keys
4.3.
Signing
4.4.
Encryption
5.
Validation
5.1.
Authorization Request Validation
5.1.1.
Encrypted Request Object
5.1.2.
Signed Request Object
5.1.3.
Parameter Validation
5.2.
ID Token Validation
5.3.
UserInfo Response Validation
5.4.
Access Token Validation
5.5.
Code Validation
6.
Offline Access
7.
String Operations
8.
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.
Refresh Token, and Access Token Lifetime
10.
Privacy Considerations
11.
IANA Considerations
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.
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,” December 2012.) [JWT]. This specification also defines the following terms:
- Authentication
- An act of verifying End-User's possession of previously provisioned credentials.
- Authentication Context
- Information that the Relying Party may require before it makes an entitlements 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 ITU-T X.1254 | ISO/IEC 29115 (International Telecommunication Union and International Organization for Standardization, “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” November 2011.) [ISO29115] entity authentication assurance level.
- Authentication Context Class Reference
- Identifier that identifies the Authentication Context.
- Claim
- A piece of information about an Entity that a Claims Provider asserts about that Entity.
- Claims Provider
- A Server that can return Claims about an Entity.
- End-User
- A 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.
- 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)
- An 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.
- ID Token
- A token that contains Claims about the authentication event. It may contain other claims.
- Issuer
- An Entity that issues a set of Claims.
- Issuer Identifier
- A verifiable identifier for an Issuer. An Issuer Identifier is an HTTPS URL that contains scheme, host, and OPTIONALLY, port number and path components. (No query or fragment components may be present.)
- Message
- A request or a response between an OpenID Relying Party and an OpenID Provider.
- OpenID Provider (OP)
- A service capable of providing Claims to a Relying Party. It is an OAuth 2.0 Authorization Server that is capable of returning claims around the authentication event and other Claims in id_token and UserInfo Endpoint response.
- OP Endpoints
- Authorization Endpoint, Token Endpoint, and UserInfo Endpoint.
- OpenID Request Object
- A JSON object that holds the OpenID request parameters.
- Relying Party (RP)
- An application requiring Claims from an OpenID Provider. It is an extended OAuth 2.0 client.
- UserInfo Endpoint
- A Protected Resource that, when presented with an Access Token by the Client, returns Claims about the End-User represented by that Access Token.
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 Basic Client (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” December 2012.) [OpenID.Basic] or OpenID Connect Standard (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” December 2012.) [OpenID.Standard].
TOC |
In OpenID Connect protocols, in abstract, the process proceeds by the RP interacting with endpoints. There are a number of endpoints involved.
TOC |
The RP sends an Authorization Request to the Authorization Endpoint of the OP to obtain either an Authorization Response or an ID Token (ID Token) or both depending on response_type and scope.
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] defines the OAuth 2.0 Authorization Request parameters. In this specification, the values to the parameters are defined as follows.
- response_type
- This parameter controls the parameters returned in the response from the Authorization Endpoint.
- The OAuth 2.0 specification documents 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. Authorization Servers 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.
- OpenID Connect supports these additional response types (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” November 2012.) [OAuth.Responses] that have been registered:
- 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. Authorization Servers 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 as well as an ID Token. Both successful and error responses SHOULD be fragment-encoded. Authorization Servers 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. 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 as well as 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.
- The Authorization Server MUST support all three of the code, id_token, and id_token token values for response_type.
- The Client may request any OAuth 2.0 registered response type supported by the Authorization Server.
- scope
- A space delimited, case sensitive list of ASCII string values. The values profile, email, address, and phone, specify an additive list of voluntary Claims being requested from the UserInfo Endpoint. The following scope values are defined:
- openid
- REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the openid scope value is not present, the request MUST NOT be treated as an OpenID Connect request.
- profile
- OPTIONAL. This scope value requests that access to the End-User's default profile Claims (Reserved Member Definitions) at the UserInfo Endpoint be granted by the issued Access Token. These claims are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_time.
- OPTIONAL. This scope value requests that access to the email and email_verified Claims at the UserInfo Endpoint be granted by the issued Access Token.
- address
- OPTIONAL. This scope value requests that access to address Claim at the UserInfo Endpoint be granted by the issued Access Token.
- phone
- OPTIONAL. This scope value requests that access to the phone_number Claim at the UserInfo Endpoint be granted by the issued Access Token.
- 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 the End-User's UserInfo endpoint even when the user is not present (not logged in). See Section 6 (Offline Access) for more information about offline access.
Other REQUIRED OAuth 2.0 parameters in the request include:
- client_id
- The OAuth 2.0 Client Identifier.
- redirect_uri
- A redirection URI where the response will be sent.
The request MAY contain the following OAuth 2.0 parameters:
- state
- RECOMMENDED. An opaque value used to maintain state between the request and the callback; it can serve as a protection against XSRF attacks, among other uses.
The following extension parameters are also defined:
- nonce
- A random, unique string value used to mitigate replay attacks. Use of the nonce is REQUIRED when using the implicit flow and OPTIONAL when using the code flow.
- display
- OPTIONAL. An ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User.
- 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. A space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The possible 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 scopes. 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.
- request
- OPTIONAL. An OpenID Request Object (OpenID Request Object) value.
- request_uri
- OPTIONAL. An URL that points to an OpenID Request Object. This is used to pass an OpenID Request Object by reference.
- id_token_hint
- OPTIONAL. An ID Token (ID Token) passed to the Authorization server as a hint about the user's current or past authenticated session with the client. This SHOULD be present if prompt=none is sent. The value is a JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] encoded ID token as signed by the issuer, the JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] may be JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] encrypted by the public key of the issuer for additional confidentiality. If the id_token received by the RP was encrypted, the Client MUST decrypt the signed id_token (JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS]). The Client MAY re-encrypt using the key that the server is capable of decrypting.
- login_hint
- OPTIONAL. A hint to the authorization service as to the login identifier the user may use to authenticate at the authorization service (if necessary). This hint can be used by an RP if it first asks the user for their email 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. The use of this parameter is up to the OP's discretion.
TOC |
The OpenID Request Object is used to provide OpenID request parameters that MAY differ from the default ones. Implementing support for the OpenID Request Object is OPTIONAL. Supporting it is necessary for implementations that need to request or provide sets of Claims other than the default UserInfo (UserInfo Endpoint), and ID Token Claim sets.
The OpenID Request Object is a JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] signed base64url encoded JSON object that is passed as the value of the "request" parameter in the Authorization Request. The OpenID Request Object MAY also be encrypted using JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] after signing, with nesting performed in the same manner as specified for JWTs [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.). The OpenID Request Object MAY alternatively be sent by reference using request_uri parameter. Parameters that affect the information returned from the UserInfo Endpoint are in the "userinfo" member. Parameters that affect the information returned in the ID Token are in the "id_token" member.
Authorization Request parameters that are included in the OAuth 2.0 Authorization Request MAY also be included in the OpenID Request Object (so that they can be part of the signed request). All parameter values that are present both in the OAuth 2.0 Authorization Request and in the OpenID Request Object MUST exactly match.
Authorization Request parameters that are OPTIONAL in the OAuth 2.0 specification MAY be included in the OpenID Request Object without also passing them as OAuth 2.0 Authorization Request parameters, with one exception: The scope parameter MUST always be present in OAuth 2.0 Authorization Request parameters (so that the OAuth 2.0 implementation has access to the openid scope value). However, the request and request_uri parameters MUST NOT be included in the OpenID Request Object.
The OpenID Request Object MAY contain other members that are not defined by this specification. With only one exception, OpenID Request Object members MUST be understood by both parties; that exception is that OpenID Providers MAY ignore requests for Claims they cannot provide or do not understand; however, Relying Parties MAY also consider it an error condition if all requested required Claims are not provided.
The OpenID 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),” December 2012.) in the JWS header. If signed, the OpenID Request Object SHOULD contain the Claims iss (issuer) and aud (audience) as members, with their semantics being the same as defined in the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] specification.
The OpenID Request Object members defined by this specification are:
- userinfo
- OPTIONAL. (UserInfo request): Requests affecting the values to be returned from the UserInfo Endpoint. If not present, the UserInfo Endpoint behaves in the default manner.
- id_token
- OPTIONAL. (ID Token request): Requests affecting the values to be returned in the ID Token. If not present, the default ID Token contents are used. If present, these parameters are used to request additional Claims incremental to the default Claims of the ID Token. (ID Token)
- registration
- OPTIONAL. (Registration request): Requests the client to be to be registered at the authorization server for the self-issued case. The value is the key-values defined in section 2.1 of the OpenID Connect Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2012.) [OpenID.Registration] serialized into JSON.
An example OpenID Request Object body 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 profile", "state": "af0ifjsldkj", "login_hint": "janedoe@example.org", "userinfo": { "claims": { "name": {"essential": true}, "nickname": null, "email": {"essential": true}, "email_verified": {"essential": true}, "picture": null } }, "id_token": { "claims": { "auth_time": {"essential": true}, "acr": { "values":["2"] } }, "max_age": 86400 } "registration": { "redirect_uris": "https://rp.com/authz/callback", "logo_url": "https://rp.com/logo.png", "jwk_url": "https://rp.com/public_key.jwks", "id_token_encrypted_response_alg": "RSA1_5", "id_token_encrypted_response_enc": "A128CBC+HS256" } }
TOC |
The structure of the userinfo (UserInfo Request) member is a JSON object that MAY contain the following members:
- claims
- OPTIONAL. (Requested Claims): A JSON object containing a set of individual Claims being requested from the UserInfo Endpoint in addition to those requested by the scope values used. If not present, only the UserInfo Claims held by the OP that are requested by the scope values used are returned. For details about this claim, refer to "claims" member in "userinfo" and "id_token" section. ("claims" member in "userinfo" and "id_token" members)
- preferred_locales
- OPTIONAL. A list of preferred languages and scripts for the entire Claims request, represented as a JSON array of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference.
All members of the userinfo object are OPTIONAL. Other members MAY be present and if so, SHOULD understood by both parties.
TOC |
The structure and function of the id_token (ID Token request) member of the OpenID Request Object is similar to that of the userinfo member. It MAY include the OPTIONAL claims and preferred_locales members. The structure of these members is the same as that for the userinfo member. If the claims member is present in the id_token object, the Claims requested within it augment the Claim set that would otherwise be returned in the ID Token.
Following Claims, in addition to the claims described in "claims" member in "userinfo" and "id_token" section. ("claims" member in "userinfo" and "id_token" members), MAY be requested in the ID Token by specifying it in the claims member:
- sub
- OPTIONAL. Subject identifier - The sub (subject) identifier for which an ID Token is being requested. If the specified user is not currently authenticated to the Authorization Server, they may be prompted for authentication, unless the prompt parameter in the Authorization Request is set to none. The Claim Value in the request is an object containing the single element value.
"sub": {"value":"248289761001"}- auth_time
- OPTIONAL. (authenticated at): Requests that the auth_time Claim be present in the ID Token (ID Token) response. The Claim Value in the request must be {"essential": true} to require auth_time in the response. If the Claim Value in the request is null the Authorization Server has the option of not including the claim in the response.
- acr
- OPTIONAL. (Authentication Context Class Reference): Requests the desired Authentication Context Class References. The element values is an ordered array of strings representing acceptable Authentication Context Class Reference values appearing in order of preference.
"acr": {"essential": true, "values":["2","http://id.incommon.org/assurance/bronze"]}
In addition to the claims member, these additional members are defined within the id_token member of the OpenID Request Object:
- max_age
- OPTIONAL. (max authentication age): Specifies that the End-User must be actively authenticated if any present authentication is older 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.)
It is anticipated that additional id_token parameters MAY be defined to request that additional properties hold for the authentication - for instance, that certain authentication policies be applied (in the same spirit of 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_policies values), or that the authentication conform to the policies defined by a specified trust framework. These parameters MAY be defined by extension specifications.
All members of the id_token object are OPTIONAL. Other members MAY be present and if so, SHOULD be understood by both parties.
TOC |
The claims member is a JSON object with a member for each requested Claim. The member names are the requested Claim names. Each Claim MAY either be an essential claim or voluntary claim. The default is voluntary.
By requesting Claims as essential, the client indicates to the user that releasing these claims will ensure a smooth authorization for the specific task requested by the user. Note that even if the claims are not available because the user did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when essential claims are not returned.
The Client may request additional Claims on voluntary basis that it requires to perform other tasks offered to the user.
The member values MAY be either:
- null
- This indicates that this Claim is being requested in the default manner. In particular, this is a voluntary Claim.
- A JSON Object
- This is used to provide additional information about the Claim being requested. This specification defines the following member:
- essential
- OPTIONAL. If the value is set to true, this indicates that the claim being requested is an essential claim. If the value is set to false, it indicates that it is a voluntary claim. The default is false.
- Other members MAY be defined to provide additional information about the requested Claim.
The Claims MAY be represented in multiple languages and scripts. To specify languages and scripts for the Claim request, BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags delimited by a "#" MUST be added to each requested Claim Name for which a particular language and script is requested. For example, the Claim family_name#ja-Kana-JP is used for expressing Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same value represented as family_name#ja-Hani-JP.
All members of the claims object are OPTIONAL.
TOC |
An Authorization Response is a message returned from the OP's Authorization Endpoint in response to the Authorization Request by the RP.
When the response_type in the request is token, the Authorization Response MUST return the parameters defined in Section 4.2.2 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. This specification only supports 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".
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 return type is 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,” November 2012.) [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,” December 2012.) [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 REQUIRED and OPTIONAL within the ID Token:
- iss
- REQUIRED. The 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. This member identifies the audience that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Client.
- azp
- OPTIONAL. Authorized Party - This member identifies an OAuth 2.0 client authorized to use this ID Token as an OAuth access token, if different than the Client that requested the ID Token. It MUST contain the client_id of the authorized party.
- exp
- REQUIRED. Type Integer. Identifies the 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 value is number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired 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. Type Integer. The iat (issued at) Claim identifies the time at which the JWT was issued. The value is number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired 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.
- acr
- OPTIONAL. (Authentication Context Class Reference): Type String. Specifies an Authentication Context Class Reference of the ID Token. The values "1", "2", "3", and "4" map to the ITU-T X.1254 | ISO/IEC 29115 (International Telecommunication Union and International Organization for Standardization, “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” November 2011.) [ISO29115] entity authentication assurance level of the authentication performed. The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 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.
- nonce
- A 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 (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 (ID Token) with the Claim value being the nonce value sent in the Authorization Request. Use of the nonce is REQUIRED when using the implicit flow and OPTIONAL when using the code flow.
- auth_time
- OPTIONAL. If the id_token ("id_token" member) member of the OpenID Request Object (OpenID Request Object) contains the Claim request auth_time with a parameter of {"essential": true}, then this Claim is REQUIRED. The Claim Value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time that the End-User authentication occurred. (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.)
- at_hash
- OPTIONAL. If the ID Token is issued with an access_token in an implicit flow, this is REQUIRED. The value is produced by base64url encoding the left-most half of the hash created by hashing the access_token with the SHA-2 family hash algorithm of the same length as the hash used in the alg parameter of the JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] header. For instance, if the alg is HS256, hash access_token with SHA-256, then take the left-most 128 bits and base64url encode them.
- c_hash
- OPTIONAL. If the ID Token is issued with a code in an implicit flow, this is REQUIRED. The value is produced by base64url encoding the left-most half of the hash created by hashing the code with the SHA-2 family hash algorithm of the same length as the hash used in the alg parameter of the JWS header. For instance, if the alg is HS256, hash code with SHA-256, then take the left-most 128 bits and base64url encode them.
ID Tokens MUST be signed using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] and OPTIONALLY both signed and encrypted using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality (Signing and Encryption order).
Clients MUST directly validate the ID Token per ID Token Validation (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://client.example.com", "sub": "24400320", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "auth_time": 1311280969, "acr": "2", "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 returning parameters defined in sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].
In addition to the error codes defined in Sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], this specification defines the following error codes:
- invalid_redirect_uri
- The redirect_uri in the Authorization Request does not match any of the Client's pre-registered redirect_uris.
- 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 invalid data.
- invalid_openid_request_object
- The request parameter contains an invalid OpenID Request Object.
Errors are returned as defined by the registered OAuth 2.0 response_type.
TOC |
The RP (Client) sends an Access Token Request to the Token Endpoint to obtain Access Token Response, which MAY include Access Token, Refresh Token (Refresh Token, and Access Token Lifetime), ID Token (ID Token), and other variables.
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 [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.), such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the value of 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,” December 2012.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Mortimore, C., Ed., Campbell, B., Jones, M., and Y. Goland, “OAuth 2.0 Assertion Profile,” December 2012.) [OAuth.Assertions]. The JWT MUST contain the Claims:
- iss
- REQUIRED. The iss (issuer) Claim. This MUST contain the client_id of the OAuth Client.
- sub
- REQUIRED. The sub (subject) Claim. This MUST contain the client_id of the OAuth Client.
- aud
- REQUIRED. The aud (audience) Claim. A 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. The jti (JWT ID) Claim. 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. The exp (expiration) Claim that limits the time window during which the JWT can be used.
- iat
- OPTIONAL. The iat (issued at) Claim that identifies the time at which the JWT was issued.
- The authentication token MUST be sent as the value of the client_assertion parameter.
- The value of the client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
- private_key_jwt
- Clients that have registered a public key sign a JWT using the RSA algorithm if a RSA key was registered or the ECDSA algorithm if an Elliptic Curve key was registered (see JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA] for the algorithm identifiers). 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,” December 2012.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Mortimore, C., Ed., Campbell, B., Jones, M., and Y. Goland, “OAuth 2.0 Assertion Profile,” December 2012.) [OAuth.Assertions]. The JWT MUST contain the Claims:
- iss
- REQUIRED. The iss (issuer) Claim. This MUST contain the client_id of the OAuth Client.
- sub
- REQUIRED. The sub (subject) Claim. This MUST contain the client_id of the OAuth Client.
- aud
- REQUIRED. The aud (audience) Claim. A 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. The jti (JWT ID) Claim. A unique identifier for the token. The token ID MAY be used by implementations requiring message de-duplication for one-time use assertions.
- exp
- REQUIRED. The exp (expiration) Claim that limits the time window during which the JWT can be used.
- iat
- OPTIONAL. The iat (issued at) Claim that identifies the time at which the JWT was issued.
- The authentication token MUST be sent as the value of the client_assertion parameter.
- The value of the client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
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...[omitted for brevity]...ZT
TOC |
The Client obtains an Access Token by authenticating with the Authorization Server and presenting its access 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 parameter for the Access Token Endpoint 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 further constrains that only OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] are issued at the Token Endpoint. The OAuth 2.0 response parameter "token_type" MUST be set to "Bearer".
In addition to the OAuth 2.0 response parameters, the following parameters MUST be included in the response if the grant_type is authorization_code and the Authorization Request scope parameter contained openid:
- id_token
- The ID Token value associated with the authentication session.
Note that id_token MUST NOT be returned if the grant_type is not authorization_code.
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.
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 a Protected Resource that returns Claims about the authenticated End-User. Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.
TOC |
Clients MAY send requests with the following parameters to the UserInfo Endpoint to obtain further information about the End-User.
- access_token
- REQUIRED. The Access Token obtained from an OpenID Connect Authorization Request.
- schema
- REQUIRED. The schema in which the data is to be returned. The only defined schema value is openid.
- id
- This identifier is reserved. It MUST be ignored by the endpoint when the openid schema is used.
TOC |
If the requested schema is openid, the UserInfo claims must be returned as the members of a JSON object. The Claims defined below can be returned, as can additional Claims (not specified below).
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.
TOC |
When an error condition occurs, the UserInfo Endpoint returns an Error Response. In addition to the error codes defined in Section 3.1 of OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750], this specification defines the following error codes:
- invalid_schema
- The requested schema is invalid or unsupported.
TOC |
This specification defines a set of standard claims. They can be requested to be returned either in id_token or userinfo response.
The members 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 MUST be added to each member names delimited by a #, e.g., family_name#ja-Kana-JP for expressing 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.
Member | Type | Description |
---|---|---|
sub | string | Subject - Identifier for the End-User at the Issuer. The sub (subject) Claim MUST always be returned in the UserInfo response. |
name | string | End-User's full name in displayable form including all name parts, ordered according to End-User's locale and preferences. |
given_name | string | Given name or first name of the End-User. |
family_name | string | Surname or last name of the End-User. |
middle_name | string | Middle name of the End-User. |
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.4.2 (Claim Stability and Uniqueness).) |
profile | string | URL of the End-User's profile page. |
picture | string | URL of the End-User's profile picture. |
website | string | URL of the End-User's web page or blog. |
string | The End-User's preferred e-mail address. This value MUST NOT be relied upon to be unique by the RP. (See Section 2.4.2 (Claim Stability and Uniqueness).) | |
email_verified | boolean | True if the End-User's e-mail address has been verified; otherwise false. |
gender | string | The 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 | The 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 9999, 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. For example, Europe/Paris or America/Los_Angeles. |
locale | string | The 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 | The 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. |
address | JSON object | The 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.4.1 (Address Claim). |
updated_time | string | Time the End-User's information was last updated, represented as a RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] datetime. For example, 2011-01-03T23:58:42+0000. |
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 OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2012.) [OpenID.Registration]. 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
- The full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.
- street_address
- The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.
- locality
- The city or locality component.
- region
- The state, province, prefecture or region component.
- postal_code
- The zip code or postal code component.
- country
- The country name component.
TOC |
The sub (subject) claim is the only claim that a client can rely upon to be stable, 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 a combination of the Issuer's identifier and the sub claim; other fields such as preferred_username and email MUST NOT be used as unique identifiers for a given End-User.
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 a given preferred_username or email address claim across different End-Users at different points in time, and the claimed preferred_username or email address for a given End-User MAY change over time.
TOC |
Provider's Discovery documents SHOULD list their 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_url in Dynamic Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2012.) [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_url in Dynamic Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2012.) [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_url.
When a sector_identifier_url 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_url must be a HTTPS URL 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 MAY be used by OpenID Providers to calculate the pairwise identifier. This specification includes three examples.
1. The Sector Identifier can be concatenated with a local account ID and a salt value that is kept secret by the Provider. The concatenated string is then hashed by an appropriate algorithm.
Calculate sub = SHA-256 ( sector_identifier | local_account_id | salt ).
2. The Sector Identifier can be concatenated with a local account ID and a salt value that is kept secret by the Provider. The concatenated string is then encrypted by an appropriate algorithm.
Calculate sub = AES-128 ( sector_identifier | local_account_id | salt ).
3. The Issuer creates a Globally Unique Identifier (GUID) for the tuple of Sector Identifier and local account ID. This is stored in a table and the value looked up each time.
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 normal Claims response:
{ "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
- This value is a 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
- This value is a 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:
Other members MAY be present, if understood by both parties.
- Aggregated Claims
- A JSON object that MUST contain the JWT member whose value is a JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] that MUST contain all the Claims in the _claim_names object that references the corresponding _claim_sources member. Other members MAY be present if they are understood by both parties.
- JWT
- REQUIRED. JWT Value.
- Distributed Claims
- A JSON object that contains the following members and values:
- endpoint
- REQUIRED. The value is the 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 Sources 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 Claim Source and Client, or the Claim Source MAY reauthenticate the End-User and/or reauthorize the Client.
The following is a non-normative response with Aggregated Claims:
Claims Provider A contains the following Claims for Jane Doe: { "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, resulting in a signed JWT: jwt_header.jwt_part2.jwt_part3 Authorization Server returns Jane Doe's Aggregated Claims from Claims Provider A: { "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "birthdate": "2001-03-23", "eye_color": "blue", "email": "janedoe@example.com", "_claim_names": { "address": "src1", "phone_number": "src1" }, "_claim_sources": { "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"} } }
The following is a non-normative response with Distributed Claims:
Claims Provider A (Jane Doe's Bank) contains the following Claims for Jane Doe: { "shipping_address": { "street_address": "1234 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US"}, "payment_info": "Some_Card 1234 5678 90123 4562", "phone_number": "+1 (310) 123-4567" } A Claims Provider B (Credit Agency) contains the following Claims for Jane Doe: { "credit_score": "650" } Authorization Server returns Jane Doe's Claims along with the Distributed Claims from Claims Provider A and B by sending the Access Tokens and URL locations where the Claims may be retrieved: { "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "email": "janedoe@example.com", "birthdate": "2001-03-23", "eye_color": "blue", "_claim_names": { "payment_info": "src1", "shipping_address": "src1", "credit_score": "src2" }, "_claim_sources": { "src1": {"endpoint": "https://bank.example.com/claimsource"}, "src2": {"endpoint": "https://creditagency.example.com/claimshere", "access_token": "ksj3n283dke"} } }
TOC |
Parameter names and values MAY be JSON serialized into a JSON structure.
TOC |
The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. Each parameter MAY have JSON Structure as its value.
Following is a non-normative example of such serialization:
{ "access_token":"SlAV32hkKG", "expires_in":3600, "refresh_token":"8xLOxBtZp8" }
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, the OpenID Request Object, token request, ID Token, and UserInfo response MAY utilize JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) [JWS] to sign the contents.
To achieve message confidentiality, the OpenID Request Object, token request, ID Token, and UserInfo response MAY use JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] to encrypt the content.
When the message is both signed and encrypted, it MUST be signed first and then encrypted (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,” December 2012.). 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),” December 2012.) [JWA]. The related elements are:
- userinfo_signing_alg_values_supported
- A JSON array containing a list of the JWS [JWS] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” December 2012.) signing algorithms (alg values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) supported by the UserInfo Endpoint to encode the claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.).
- userinfo_encryption_alg_values_supported
- A JSON array containing a list of the JWE [JWE] (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) encryption algorithms (alg values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) supported by the UserInfo Endpoint to encode the claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.).
- userinfo_encryption_enc_values_supported
- A JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) supported by the UserInfo Endpoint to encode the claims in a JWT [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.).
- id_token_signing_alg_values_supported
- A 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,” December 2012.).
- id_token_encryption_alg_values_supported
- A 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,” December 2012.).
- id_token_encryption_enc_values_supported
- A 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,” December 2012.).
- request_object_signing_alg_values_supported
- A JSON array containing a list of the JWS signing algorithms (alg values) supported by the Authorization Server for the OpenID Request Object (OpenID Request Object). Servers SHOULD support none and RS256.
- request_object_encryption_alg_values_supported
- A JSON array containing a list of the JWE encryption algorithms (alg values) supported by the Authorization Server for the OpenID Request Object (OpenID Request Object).
- request_object_encryption_enc_values_supported
- A JSON array containing a list of the JWE encryption algorithms (enc values) supported by the Authorization Server for the OpenID Request Object (OpenID Request Object).
- token_endpoint_auth_signing_alg_values_supported
- A 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,” December 2012.). Servers SHOULD support RS256.
The Client registers its required algorithms for Signing and Encryption using the following Registration parameters:
- request_object_signing_alg
- OPTIONAL. The JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for OpenID Request Objects by the Authorization Server. All OpenID Request Objects from this client_id MUST be rejected if not signed by this algorithm. Servers SHOULD support RS256.
- userinfo_signed_response_alg
- OPTIONAL. The JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for UserInfo responses. If this is specified the response will be JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] serialized.
- userinfo_encrypted_response_alg
- OPTIONAL. The JWE alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for UserInfo responses. If this is requested in combination with signing, the response MUST be signed first then encrypted (Signing and Encryption order). If this is specified, the response will be JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] serialized.
- userinfo_encrypted_response_enc
- OPTIONAL. The JWE enc algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) 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. The JWS signature algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) 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 document from the jwk_url element or the x509_url element from discovery.
- id_token_encrypted_response_alg
- OPTIONAL. The JWE alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) 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. The JWE enc algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) 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 Server advertises its supported signing and encryption algorithms in its discovery document. The related elements are:
The Provider provides its public Keys during Discovery in the following elements:
- jwk_url
- URL of the OP's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document that contains the Server's signing key(s) that are used for signing the JWT. It MAY also be used by the Client to encrypt the JWT to the Server if x509_encryption_url or jwk_encryption_url is not specified, but this is discouraged. A separate encryption key SHOULD be used.
- jwk_encryption_url
- URL of the OP's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document that contains the Server's encryption key(s) that are used by the Client to encrypt the JWT to the Server. If it is not present, its value is the same as the URL provided by jwk_url.
- x509_url
- URL of the OP's X.509 certificates in PEM format that are used by the Server for Signing the JWT. It MAY also be used by the Client to JWE Encrypt the JWT to the Server if x509_encryption_url is not specified. The certificate referenced SHOULD be valid for its intended use as specified by RFC 2459 (Housley, R., Ford, W., Polk, T., and D. Solo, “Internet X.509 Public Key Infrastructure Certificate and CRL Profile,” January 1999.) [RFC2459]
- x509_encryption_url
- URL of the OP's X.509 certificates in PEM format that contains the Server's encryption key that is used by the Client to encrypt the JWT to the Server. If it is not present, the URL provided by the x509_url is used instead. The certificate referenced SHOULD be valid for its intended use as specified by RFC 2459 (Housley, R., Ford, W., Polk, T., and D. Solo, “Internet X.509 Public Key Infrastructure Certificate and CRL Profile,” January 1999.) [RFC2459]
The Client provides its public Keys during Registration, in the following elements:
- jwk_url
- OPTIONAL. URL for the Client's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document containing key(s) that are used for signing the Request Objects. If jwk_encryption_url is not provided, it is also used by the Server to encrypt the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] to the Client.
- jwk_encryption_url
- OPTIONAL. URL for the Client's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document containing key(s) used by the Server to encrypt the response objects to the Client.
- x509_url
- OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain. It is used by the Client for signing the Request Objects. If x509_encryption_url is not present, it is also used to encrypt the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] to the Client. The certificate referenced SHOULD be valid for its intended use as specified by RFC 2459 (Housley, R., Ford, W., Polk, T., and D. Solo, “Internet X.509 Public Key Infrastructure Certificate and CRL Profile,” January 1999.) [RFC2459].
- x509_encryption_url
- OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain, used to encrypt the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.) [JWT] to the Client. The certificate referenced SHOULD be valid for its intended use as specified by RFC 2459 (Housley, R., Ford, W., Polk, T., and D. Solo, “Internet X.509 Public Key Infrastructure Certificate and CRL Profile,” January 1999.) [RFC2459]
If keys are specified in both X.509 and JWK formats, they MUST be the same keys.
Algorithms like Elliptic Curve signing and key agreement require separate keys for signing and encryption for security. For RSA, a single key MAY be used for both, but it is good practice to separate them.
TOC |
The signing party MUST select a signature algorithm based on the supported algorithms of the recipient in Section 4.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),” December 2012.) [JWA]. The private key MUST be the one associated with the Public Signing Key provided in Section 4.2 (Keys). If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWS header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. The key usage of the respective keys MUST support signature.
- Symmetric Signatures
- When using HMAC 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),” December 2012.) [JWA]. The client and server MUST establish a shared secret out of band.
TOC |
The encrypting party MUST select an encryption algorithm based on the supported algorithms of the recipient in Section 4.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 4.2 (Keys) to retrieve the relevant key. The jwk_encryption_url or x509_encryption_url link MUST be used if provided. If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWE header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. Use the supported RSA KeyWrap algorithm to KeyWrap 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 4.2 (Keys) to retrieve the relevant key. The jwk_encryption_url or x509_encryption_url link MUST be used if provided. If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWE header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. Use the ECDH-ES algorithm to KeyWrap 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
- Use a left truncated SHA-256 hash of client_secret to KeyWrap a random Content Master Key to be used for encrypting the signed JWT. The SHA-256 MUST be left truncated to the appropriate bit length for the AES KeyWrap algorithm used.
TOC |
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 an OpenID Request Object 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,” December 2012.) [JWS] or JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] encoded objects, for which nested encryption and signing may have been performed in the manner described in [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” December 2012.).
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 JSON Web Encryption (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] specification. The result MAY be either OpenID Request Object or a JWS Signed JWT. In the latter case, the signature validation MUST be performed as defined in Signed Request Object (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,” December 2012.) [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,” December 2012.) [JWS] specification.
The Authorization Server MUST return the error authorization response if there is a signature validation error.
TOC |
The Authorization Server MUST construct the Authorization Request Message from the OpenID Request Object and the OAuth 2.0 Authorization Request parameters. If the same parameter exists both in the OpenID Request Object and the OAuth Authorization Request parameters, the parameter values MUST exactly match. 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 with an ID Token in the implicit flow, the client SHOULD do the following:
TOC |
To validate a code issued with an ID Token in the implicit flow, 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 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 |
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 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., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2012.) [OAuth.Threat] provides an extensive list of threats and controls that applies to this standard as well. ITU-T X.1254 | ISO/IEC 29115 (International Telecommunication Union and International Organization for Standardization, “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” November 2011.) [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 threat.
In addition to what is stated in Section 5.1.1 of [OAuth.Threat] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2012.), 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 works 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 [OAuth.Threat] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2012.), 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 request to a wrong party, a Client that was authenticated using only a bearer token can repudiate any transaction.
To mitigate this threat, the Sever MAY require that the request to 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 been used once with the intended Resource.
To mitigate this threat, the token SHOULD include a timestamp and a short lifetime of validity. The Relying Party 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 4.4.1.1 of OAuth SC, it can be captured in the User-Agent where the TLS session is terminated if the User-Agent is infested by malware.
However, capturing it is not useful as long as the profile uses either Client authentication or the Response encryption.
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 is 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 is an attack that 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 instance of the finding 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,” December 2012.) [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.
It is RECOMMENDED that only a single issuer per host be used. Simple Web Discovery treats the path component of any URI as part of the user identifier.
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.
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 User Info 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 MUST provide a mechanism for the user to revoke Refresh Tokens granted to a Client.
TOC |
The UserInfo response typically contains Personally Identifiable Information. 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 |
This document makes no requests of IANA.
TOC |
TOC |
[E.164] | International Telecommunication Union, “E.164: The international public telecommunication numbering plan,” 2010. |
[ISO29115] | International Telecommunication Union and International Organization for Standardization, “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” ISO/IEC 29115, November 2011. |
[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. |
[JWA] | Jones, M., “JSON Web Algorithms (JWA),” draft-ietf-jose-json-web-algorithms (work in progress), December 2012 (HTML). |
[JWE] | Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” draft-ietf-jose-json-web-encryption (work in progress), December 2012 (HTML). |
[JWK] | Jones, M., “JSON Web Key (JWK),” draft-ietf-jose-json-web-key (work in progress), December 2012 (HTML). |
[JWS] | Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature,” draft-ietf-jose-json-web-signature (work in progress), December 2012 (HTML). |
[JWT] | Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token,” draft-ietf-oauth-json-web-token (work in progress), December 2012 (HTML). |
[OAuth.Assertions] | Mortimore, C., Ed., Campbell, B., Jones, M., and Y. Goland, “OAuth 2.0 Assertion Profile,” draft-ietf-oauth-assertions (work in progress), December 2012 (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), December 2012 (HTML). |
[OAuth.Responses] | de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” November 2012. |
[OAuth.Threat] | Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” draft-ietf-oauth-v2-threatmodel (work in progress), October 2012 (HTML). |
[OpenID.Basic] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” December 2012. |
[OpenID.Discovery] | Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” December 2012. |
[OpenID.Implicit] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Implicit Client Profile 1.0,” December 2012. |
[OpenID.Registration] | Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2012. |
[OpenID.Session] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” December 2012. |
[OpenID.Standard] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” December 2012. |
[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). |
[RFC2459] | Housley, R., Ford, W., Polk, T., and D. Solo, “Internet X.509 Public Key Infrastructure Certificate and CRL Profile,” RFC 2459, January 1999 (TXT). |
[RFC3339] | Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML). |
[RFC4627] | Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT). |
[RFC5246] | Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT). |
[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). |
[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] | specs@openid.net, “OpenID Authentication 2.0,” December 2007 (TXT, HTML). |
[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). |
TOC |
As a successor version of OpenID, this specification heavily relies on OpenID Authentication 2.0 (specs@openid.net, “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.
This specification is largely compliant with OAuth 2.0 draft 20. Please refer to the OAuth 2.0 specification for the list of contributors.
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.
Anthony Nadalin (tonynad@microsoft.com), Microsoft
Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET
Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom
Casper Biering (cb@peercraft.com), Peercraft
Breno de Medeiros (breno@gmail.com), Google
Chuck Mortimore (cmortimore@salesforce.com), Salesforce
David Recordon (dr@fb.com), Facebook
Edmund Jay (ejay@mgi1.com), Illumila
George Fletcher (george.fletcher@corp.aol.com), AOL
Hideki Nara (hideki.nara@gmail.com), Takt Communications
Johnny Bufu (jbufu@janrain.com), Janrain
John Bradley (ve7jtb@ve7jtb.com), Ping Identity
Justin Richer (jricher@mitre.org), Mitre
Luke Shepard (lshepard@fb.com), Facebook
Michael B. Jones (mbj@microsoft.com), Microsoft
Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.
Nov Matake (nov@matake.jp), Independent
Pamela Dingle (pdingle@pingidentity.com), Ping Identity
Paul Tarjan (pt@fb.com), Facebook
Roland Hedberg (roland.hedberg@adm.umu.se), Independent
Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.
Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom
TOC |
Copyright (c) 2012 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 ]]
-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 |