Draft N. Sakimura NRI J. Bradley Ping Identity M. Jones Microsoft B. de Medeiros Google C. Mortimore Salesforce E. Jay Illumila July 5, 2013 OpenID Connect Messages 1.0 - draft 20 Abstract OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. This specification only defines the endpoints, associated messages, and message exchange sequences. These are used in protocol bindings such as OpenID Connect Standard 1.0, which is a binding of these messages to OAuth 2.0. Actual use requires also using a companion protocol binding specification, such as OpenID Connect Standard 1.0. Sakimura, et al. [Page 1] OpenID Connect Messages 1.0 July 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Requirements Notation and Conventions . . . . . . . . . . 5 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 9 2.1.1. Authorization Request . . . . . . . . . . . . . . . . 9 2.1.1.1. Request Parameters . . . . . . . . . . . . . . . 9 2.1.2. Authorization Response . . . . . . . . . . . . . . . 15 2.1.2.1. ID Token . . . . . . . . . . . . . . . . . . . . 15 2.1.3. Authorization Error Response . . . . . . . . . . . . 19 2.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 2.2.1. Client Authentication . . . . . . . . . . . . . . . . 20 2.2.2. Access Token Request . . . . . . . . . . . . . . . . 23 2.2.3. Access Token Response . . . . . . . . . . . . . . . . 23 2.2.4. Access Token Error Response . . . . . . . . . . . . . 25 2.3. UserInfo Endpoint . . . . . . . . . . . . . . . . . . . . 25 2.3.1. UserInfo Request . . . . . . . . . . . . . . . . . . 25 2.3.2. UserInfo Response . . . . . . . . . . . . . . . . . . 25 2.3.3. UserInfo Error Response . . . . . . . . . . . . . . . 25 2.4. Scope Values . . . . . . . . . . . . . . . . . . . . . . 26 2.5. Standard Claims . . . . . . . . . . . . . . . . . . . . . 27 2.5.1. Address Claim . . . . . . . . . . . . . . . . . . . . 33 2.5.2. Claims Languages and Scripts . . . . . . . . . . . . 34 2.5.3. Claim Stability and Uniqueness . . . . . . . . . . . 35 2.5.4. Additional Claims . . . . . . . . . . . . . . . . . . 35 2.6. Claims Request . . . . . . . . . . . . . . . . . . . . . 35 2.6.1. Individual Claims Requests . . . . . . . . . . . . . 37 2.6.2. Languages and Scripts for Individual Claims . . . . . 39 2.7. Claim Types . . . . . . . . . . . . . . . . . . . . . . . 40 2.7.1. Normal Claims . . . . . . . . . . . . . . . . . . . . 40 2.7.2. Aggregated and Distributed Claims . . . . . . . . . . 40 2.7.2.1. Example of Aggregated Claims . . . . . . . . . . 42 2.7.2.2. Example of Distributed Claims . . . . . . . . . . 42 2.8. Subject Identifier Types . . . . . . . . . . . . . . . . 44 2.8.1. Pairwise Identifier Algorithm . . . . . . . . . . . . 44 2.9. Request Object . . . . . . . . . . . . . . . . . . . . . 45 2.10. Using the "request_uri" Parameter . . . . . . . . . . . . 47 2.10.1. "request_uri" Rationale . . . . . . . . . . . . . . . 47 3. Signatures and Encryption . . . . . . . . . . . . . . . . . . 49 3.1. Supported Algorithms . . . . . . . . . . . . . . . . . . 49 3.2. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 51 3.3. Signing . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.3.1. Rotation of Asymmetric Signing Keys . . . . . . . . . 52 3.4. Encryption . . . . . . . . . . . . . . . . . . . . . . . 52 3.4.1. Rotation of Asymmetric Encryption Keys . . . . . . . 53 Sakimura, et al. [Page 2] OpenID Connect Messages 1.0 July 2013 4. Validation . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.1. Authorization Request Validation . . . . . . . . . . . . 55 4.1.1. Encrypted Request Object . . . . . . . . . . . . . . 55 4.1.2. Signed Request Object . . . . . . . . . . . . . . . . 55 4.1.3. Parameter Validation . . . . . . . . . . . . . . . . 56 4.2. ID Token Validation . . . . . . . . . . . . . . . . . . . 57 4.3. UserInfo Response Validation . . . . . . . . . . . . . . 58 4.4. Access Token Validation . . . . . . . . . . . . . . . . . 58 4.5. Code Validation . . . . . . . . . . . . . . . . . . . . . 59 5. Offline Access . . . . . . . . . . . . . . . . . . . . . . . 60 6. Self-Issued OpenID Provider . . . . . . . . . . . . . . . . . 61 6.1. Self-Issued OpenID Provider Discovery . . . . . . . . . . 61 6.2. Self-Issued OpenID Provider Registration . . . . . . . . 61 6.2.1. Providing Additional Registration Information . . . . 62 6.3. Self-Issued OpenID Provider Request . . . . . . . . . . . 62 6.4. Self-Issued OpenID Provider Response . . . . . . . . . . 64 6.5. Self-Issued ID Token Validation . . . . . . . . . . . . . 64 7. String Operations . . . . . . . . . . . . . . . . . . . . . . 67 8. Implementation Considerations . . . . . . . . . . . . . . . . 68 8.1. Mandatory to Implement Features for All OpenID Providers . . . . . . . . . . . . . . . . . . . . . . . . 68 8.2. Mandatory to Implement Features for Dynamic OpenID Providers . . . . . . . . . . . . . . . . . . . . . . . . 69 8.3. Related Specifications . . . . . . . . . . . . . . . . . 69 9. Security Considerations . . . . . . . . . . . . . . . . . . . 71 9.1. Request Disclosure . . . . . . . . . . . . . . . . . . . 71 9.2. Server Masquerading . . . . . . . . . . . . . . . . . . . 71 9.3. Token Manufacture/Modification . . . . . . . . . . . . . 71 9.4. Server Response Disclosure . . . . . . . . . . . . . . . 72 9.5. Server Response Repudiation . . . . . . . . . . . . . . . 72 9.6. Request Repudiation . . . . . . . . . . . . . . . . . . . 72 9.7. Access Token Redirect . . . . . . . . . . . . . . . . . . 73 9.8. Token Reuse . . . . . . . . . . . . . . . . . . . . . . . 73 9.9. Eavesdropping or Leaking Authorization Codes (Secondary Authenticator Capture) . . . . . . . . . . . . 73 9.10. Token Substitution . . . . . . . . . . . . . . . . . . . 73 9.11. Timing Attack . . . . . . . . . . . . . . . . . . . . . . 74 9.12. Other Crypto Related Attacks . . . . . . . . . . . . . . 74 9.13. Signing and Encryption Order . . . . . . . . . . . . . . 75 9.14. Issuer Identifier . . . . . . . . . . . . . . . . . . . . 75 9.15. TLS Requirements . . . . . . . . . . . . . . . . . . . . 75 9.16. Lifetimes of Access Tokens and Refresh Tokens . . . . . . 75 9.17. Symmetric Key Entropy . . . . . . . . . . . . . . . . . . 76 9.18. Need for Signed Requests . . . . . . . . . . . . . . . . 76 9.19. Need for Encrypted Requests . . . . . . . . . . . . . . . 76 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 77 10.1. Personally Identifiable Information . . . . . . . . . . . 77 10.2. Data Access Monitoring . . . . . . . . . . . . . . . . . 77 Sakimura, et al. [Page 3] OpenID Connect Messages 1.0 July 2013 10.3. Correlation . . . . . . . . . . . . . . . . . . . . . . . 77 10.4. Offline Access . . . . . . . . . . . . . . . . . . . . . 77 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 11.1. JSON Web Token Claims Registry . . . . . . . . . . . . . 79 11.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 79 11.2. OAuth Parameters Registry . . . . . . . . . . . . . . . . 82 11.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 82 11.3. OAuth Extensions Error Registry . . . . . . . . . . . . . 84 11.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 84 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 86 12.1. Normative References . . . . . . . . . . . . . . . . . . 86 12.2. Informative References . . . . . . . . . . . . . . . . . 88 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 90 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . 92 Appendix C. Document History . . . . . . . . . . . . . . . . . . 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 109 Sakimura, et al. [Page 4] OpenID Connect Messages 1.0 July 2013 1. Introduction The OpenID Connect Messages 1.0 specification defines endpoints, associated messages, and message sequences that can be used to build an actual OpenID Connect identity protocol. OpenID Connect Standard 1.0 [OpenID.Standard] is such a protocol. It binds the OAuth 2.0 code and implicit flows to the elements defined by this specification to define an interoperable identity protocol over HTTPS. Similarly, one could use this specification to write bindings to other protocols such as IMAP or XMPP. 1.1. Requirements Notation and Conventions 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 [RFC2119]. Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) [JWE] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used. 1.2. Terminology 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 [RFC6749], and the terms "Claim Names" and "Claim Values" defined by JSON Web Token (JWT) [JWT]. This specification also defines the following terms: Authentication Process of verifying that an Entity is the owner of an Identity. Typically this involves the verification of the current or past possession of particular credentials, including what the entity knows, possesses, has as physical features, or behaviors, or combinations of these utilizing heuristics. The entity is often an End-User or a Client. Sakimura, et al. [Page 5] OpenID Connect Messages 1.0 July 2013 Authentication Context Information that the Relying Party can require before it makes an entitlement decision with respect to an authentication response. Such context can include, but is not limited to, the actual authentication method used or level of assurance such as ISO/IEC 29115 [ISO29115] entity authentication assurance level. Authentication Context Class Set of authentication methods or procedures that are considered to be equivalent to each other in a particular context. Authentication Context Class Reference Identifier for an Authentication Context Class. Claim Piece of information asserted about an Entity. Claim Type Syntax used for representing a Claim Value. This specification defines Normal, Aggregated, and Distributed Claim Types. Claims Provider Server that can return Claims about an Entity. Credential Data presented as evidence of the right to use an identity or other resources. End-User Human Resource Owner. Entity Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity. Essential Claim Claim specified by the Client as being necessary to ensure a smooth authorization experience for the specific task requested by the End-User. ID Token JSON Web Token (JWT) [JWT] that contains Claims about the authentication event. It MAY contain other Claims. Identifier Value that uniquely characterizes an Entity in a specific context. Identity Set of attributes related to an Entity. Issuer Entity that issues a set of Claims. Sakimura, et al. [Page 6] OpenID Connect Messages 1.0 July 2013 Issuer Identifier Verifiable Identifier for an Issuer. An Issuer Identifier is a case sensitive URL using the "https" scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components. Message Request or a response between an OpenID Relying Party and an OpenID Provider. OpenID Provider (OP) OAuth 2.0 Authorization Server that is capable of providing Claims to a Relying Party about the authentication event and the End-User in an ID Token and/or a UserInfo Endpoint response. OP Endpoints Authorization Endpoint, Token Endpoint, and UserInfo Endpoint. Request Object JWT that contains a set of request parameters as its Claims. Pairwise Pseudonymous Identifier (PPID) Identifier that identifies the Entity to a Relying Party that cannot be correlated with the Entity's PPID at another Relying Party. Personally Identifiable Information (PII) 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. Relying Party (RP) OAuth 2.0 Client application requiring Claims from an OpenID Provider. Self-Issued OpenID Provider Personal OpenID Provider that issues self-signed ID Tokens. UserInfo Endpoint Protected resource that, when presented with an Access Token by the Client, returns authorized information about the End-User represented by the corresponding Authorization Grant. Validation Process intended to establish the soundness or correctness of a construct. Verification Process intended to test or prove the truth or accuracy of a fact or value. Voluntary Claim Claim specified by the Client as being useful but not Essential for the specific task requested by the End-User. IMPORTANT NOTE TO READERS: The terminology definitions in this Sakimura, et al. [Page 7] OpenID Connect Messages 1.0 July 2013 section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as "Issuer Identifier", reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed. For more background on some of the terminology used, see Internet Security Glossary, Version 2 [RFC4949], ISO/IEC 29115 Entity Authentication Assurance [ISO29115], and ITU-T X.1252 [X.1252]. 1.3. Overview The OpenID Connect protocol, in abstract, follows the following steps. 1. The RP (Client) sends a request to the OP's (Authorization Server's) End-User Authorization Endpoint. 2. The OP authenticates the End-User and obtains appropriate authorization. 3. The OP responds with an Access Token, an Id Token, and a few other variables. 4. The RP sends a request with the Access Token to the UserInfo Endpoint, per Section 2.3. 5. The UserInfo Endpoint returns the additional End-User information supported by the Resource Server. This specification only defines the abstract message flow and message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Standard 1.0 [OpenID.Standard], OpenID Connect Basic Client Profile 1.0 [OpenID.Basic], or OpenID Connect Implicit Client Profile 1.0 [OpenID.Implicit]. Sakimura, et al. [Page 8] OpenID Connect Messages 1.0 July 2013 2. Messages In OpenID Connect, the RP interacts with these endpoints at the OP: 1. Authorization Endpoint: The RP sends a request to the OP at the Authorization Endpoint. The OP then authenticates the End-User. Then, after potential authorization actions by the End-User, the Authorization Server returns an Authorization Response, which can include an Authorization Code value. For some Clients, the Implicit Grant will be used to obtain an ID Token and Access Token without using an Authorization Code; the "response_type" parameter value "id_token token" does this. For some Clients, the Implicit Grant will be used to obtain only an ID Token; the "response_type" parameter value "id_token" does this. 2. Token Endpoint: Clients using an Authorization Code send an Access Token Request containing the Authorization Code to the Token Endpoint to obtain an Access Token Response that includes an Access Token and an ID Token. The Client can also send a Refresh Token to it to obtain a new Access Token. 3. UserInfo Endpoint: Clients using an Access Token send the Access Token to the UserInfo Endpoint to obtain Claims about the End- User. 2.1. Authorization Endpoint The RP sends an Authorization Request to the Authorization Endpoint of the OP to obtain an Authorization Response, which MAY contain an ID Token, Code, and Access Token, depending on the "response_type" value used. 2.1.1. Authorization Request An Authorization Request is a message sent from an RP to the OP's Authorization Endpoint. It is an extended OAuth 2.0 [RFC6749] Authorization Request. Section 4.1.1 and 4.2.1 of OAuth 2.0 [RFC6749] define the OAuth 2.0 Authorization Request parameters. 2.1.1.1. Request Parameters OpenID Connect uses the following OAuth 2.0 request parameters: response_type REQUIRED. Value that controls the parameters returned in the response from the Authorization Endpoint. Sakimura, et al. [Page 9] OpenID Connect Messages 1.0 July 2013 The OAuth 2.0 specification defines two response types: code When supplied as the value for the "response_type" parameter, a successful response MUST include an Authorization Code as defined in OAuth 2.0. Both successful and error responses MUST be added as parameters to the query component of the response. All tokens are returned from the Token Endpoint. When used by OpenID Connect, an ID Token is also returned from the Token Endpoint. OpenID Providers that are not Self-Issued OPs MUST support this "response_type". token When supplied as the value for the "response_type" parameter, a successful response MUST include an Access Token as defined in OAuth 2.0. Both successful and error responses MUST be fragment-encoded. No ID Token is provided to the Client; therefore, this "response_type" is not used by OpenID Connect. OpenID Connect supports these additional response types [OAuth.Responses], which have been registered with IANA: id_token When supplied as the value for the "response_type" parameter, a successful response MUST include an ID Token. Both successful and error responses SHOULD be fragment-encoded. OpenID Providers MUST support this "response_type". id_token token When supplied as the value for the "response_type" parameter, a successful response MUST include both an Access Token and an ID Token. Both successful and error responses SHOULD be fragment-encoded. OpenID Providers MUST support this "response_type". code token When supplied as the value for the "response_type" parameter, a successful response MUST include both an Access Token and an Authorization Code as defined in OAuth 2.0. When used by OpenID Connect, an ID Token is also returned from the Token Endpoint. Both successful and error responses SHOULD be fragment-encoded. code id_token When supplied as the value for the "response_type" parameter, a successful response MUST include both an Authorization Code and an ID Token. Both successful and error responses SHOULD be fragment-encoded. Sakimura, et al. [Page 10] OpenID Connect Messages 1.0 July 2013 code id_token token When supplied as the value for the "response_type" parameter, a successful response MUST include an Authorization Code, an ID Token, and an Access Token. Both successful and error responses SHOULD be fragment-encoded. All OpenID Providers MUST support the "id_token" response type and all OpenID Providers that are not Self-Issued OPs MUST also support the "id_token token" and "code" response types. The Client can use any OAuth 2.0 registered response type supported by the OpenID Provider other than "token" (which provides no ID Token). client_id REQUIRED. OAuth 2.0 Client Identifier. scope REQUIRED. Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. OpenID Connect requests MUST contain the "openid" scope value. OPTIONAL scope values of "profile", "email", "address", "phone", and "offline_access" are also defined. See Section 2.4 for more about the scope values defined by this specification. redirect_uri REQUIRED. Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider. This URI MUST exactly match one of the "redirect_uris" registered for the Client, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison). If the Client uses the OAuth implicit grant type, the redirection URI MUST NOT use the "http" scheme unless the Client is a native application, in which case it MAY use the "http:" scheme with "localhost" as the hostname. If the Client only uses the OAuth "authorization_code" grant type, the redirection URI MAY use the "http" scheme, provided that the Client Type is "confidential", as defined in Section 2.1 of OAuth 2.0. state RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with the browser cookie. This specification also defines the following request parameters: nonce REQUIRED or OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. Sufficient entropy MUST be present in the "nonce" values used to prevent attackers from guessing values. One method to achieve this is to store a random value as a signed Sakimura, et al. [Page 11] OpenID Connect Messages 1.0 July 2013 session cookie, and pass the value in the "nonce" parameter. In that case, the "nonce" in the returned ID Token can be compared to the signed session cookie to detect ID Token replay by third parties. Use of the nonce is REQUIRED for all requests where an ID Token is returned directly from the Authorization Endpoint. It is OPTIONAL when the ID Token is returned from the Token Endpoint. display OPTIONAL. ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The defined values are: page The Authorization Server SHOULD display authentication and consent UI consistent with a full User-Agent page view. If the display parameter is not specified this is the default display mode. popup The Authorization Server SHOULD display authentication and consent UI consistent with a popup User-Agent window. The popup User-Agent window SHOULD be 450 pixels wide and 500 pixels tall. touch The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface. The Authorization Server MAY attempt to detect the touch device and further customize the interface. wap The Authorization Server SHOULD display authentication and consent UI consistent with a "feature phone" type display. prompt OPTIONAL. Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: none The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing. This can be used as a method to check for existing authentication and/or consent. login The Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot prompt the End-User, it MUST return an error. Sakimura, et al. [Page 12] OpenID Connect Messages 1.0 July 2013 consent The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. select_account The Authorization Server SHOULD prompt the End- User to select a user account. This allows an End-User who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they might have current sessions for. If it cannot prompt the End-User, it MUST return an error. 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. max_age OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. (The "max_age" request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] "max_auth_age" request parameter.) When "max_age" is used, the ID Token returned MUST include an "auth_time" Claim Value. ui_locales OPTIONAL. End-User's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider. claims_locales OPTIONAL. End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider. id_token_hint OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. This SHOULD be present when "prompt=none" is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response. The Authorization Server need not be listed as an audience of the ID Token when it is used as an "id_token_hint" value. Sakimura, et al. [Page 13] OpenID Connect Messages 1.0 July 2013 If the ID Token received by the RP is encrypted, the Client MUST decrypt the signed ID Token contained within the encrypted ID Token. The Client MAY re-encrypt the signed ID token to the Authentication Server using a key that enables the server to decrypt the ID Token. For a Self-Issued ID Token, the "sub" (subject) of the signed ID Token MUST be sent as the "kid" (Key ID) of the JWE. login_hint OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the "phone_number" Claim. The use of this parameter is left to the OP's discretion. acr_values OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the "acr" values that the Authorization Server is being requested to use for processing this authentication request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the "acr" Claim Value, as specified in Section 2.1.2.1. The "acr" Claim is requested as a Voluntary Claim by this parameter. claims OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object, as specified in Section 2.6. registration OPTIONAL. This parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration, as specified in Section 6.2.1. The "registration" parameter SHOULD NOT be used when the OP is not a Self-Issued OP. request OPTIONAL. This parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. The parameter value is a Request Object value, as specified in Section 2.9. It represents the request as a JWT whose Claims are the request parameters above. When the "request" parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. Even if a "scope" parameter is present in the Request Object value, a "scope" parameter MUST Sakimura, et al. [Page 14] OpenID Connect Messages 1.0 July 2013 always be passed using the OAuth 2.0 request syntax containing the "openid" scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request. request_uri OPTIONAL. This parameter enables OpenID Connect requests to be passed by reference, rather than by value. The "request_uri" value is a URL using the "https" scheme referencing a resource containing a Request Object value, which is a JWT containing the request parameters. This parameter is used identically to the "request" parameter, other than that the Request Object value is retrieved from the specified URL, rather than passed by value. See Section 2.10 for more information on using the "request_uri" parameter. 2.1.2. Authorization Response An Authorization Response is a message returned from the OP's Authorization Endpoint in response to the Authorization Request by the RP. This specification only describes OAuth 2.0 Bearer Token Usage [RFC6750]. The OAuth 2.0 response parameter "token_type" MUST be set to "Bearer" unless another Token Type has been negotiated with the Client. When the "response_type" in the request is "code", the Authorization Response MUST return the parameters defined in Section 4.1.2 of OAuth 2.0 [RFC6749]. When the "response_type" includes other values, they MUST be returned as defined by their registration. The "id_token", "code id_token", "id_token token", "code token", and "code id_token token" response types are defined in OAuth 2.0 Multiple Response Type Encoding Practices [OAuth.Responses]. 2.1.2.1. ID Token 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) [JWT]. The ID Token is used to manage the authentication event and user identifier and is scoped to a particular Client via the "aud" (audience) and "nonce" Claims. The following Claims are used within the ID Token: Sakimura, et al. [Page 15] OpenID Connect Messages 1.0 July 2013 iss REQUIRED. Issuer Identifier for the Issuer of the response. The "iss" value is a case sensitive URL using the "https" scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components. 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. The "sub" value is a case sensitive string. aud REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 "client_id" of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the "aud" value is an array of case sensitive strings. In the special case when there is one audience, the "aud" value MAY be a single case sensitive string. exp REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular. The "exp" value is a number. iat REQUIRED. Time at which the JWT was issued. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. The "iat" value is a number. auth_time OPTIONAL or REQUIRED. Time when the End-User authentication occurred. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/ time. When a "max_age" request is made or when "auth_time" is requested as an Essential Claim, then this Claim is REQUIRED. (The "auth_time" Claim semantically corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] "auth_time" response parameter.) The "auth_time" value is a number. nonce OPTIONAL or REQUIRED. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. If present in the ID Token, Clients MUST verify that the "nonce" Claim Value is equal to the value of the "nonce" parameter sent in the Authorization Request. If present in the Sakimura, et al. [Page 16] OpenID Connect Messages 1.0 July 2013 Authorization Request, Authorization Servers MUST include a "nonce" Claim in the ID Token with the Claim Value being the nonce value sent in the Authorization Request. Authorization Servers SHOULD perform no other processing on "nonce" values used. Use of the nonce is REQUIRED for all requests where an ID Token is returned directly from the Authorization Endpoint. It is OPTIONAL when the ID Token is returned from the Token Endpoint. The "nonce" value is a case sensitive string. at_hash OPTIONAL or REQUIRED. Access Token hash value. If the ID Token is issued from the Authorization Endpoint with an "access_token", this is REQUIRED. This is OPTIONAL when the ID Token is issued from the Token Endpoint. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the "access_token" value, where the hash algorithm used is the hash algorithm used in the "alg" parameter of the ID Token's JWS [JWS] header. For instance, if the "alg" is "RS256", hash the "access_token" value with SHA-256, then take the left-most 128 bits and base64url encode them. The "at_hash" value is a case sensitive string. c_hash Sometimes REQUIRED. Code hash value. If the ID Token is issued from the Authorization Endpoint with a "code", this is REQUIRED. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the "code" value, where the hash algorithm used is the hash algorithm used in the "alg" parameter of the ID Token's JWS [JWS] header. For instance, if the "alg" is "HS512", hash the "code" value with SHA-512, then take the left-most 256 bits and base64url encode them. The "c_hash" value is a case sensitive string. acr OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 [ISO29115] level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of "level 0" is appropriate. Authentications with level 0 SHOULD never be used to authorize access to any resource of any monetary value. (This corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] "nist_auth_level" 0.) An absolute URI or a registered name [RFC6711] SHOULD be used as the "acr" value; registered names MUST NOT be used with a different meaning than that which is registered. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The "acr" value is a case sensitive string. Sakimura, et al. [Page 17] OpenID Connect Messages 1.0 July 2013 amr OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the "amr" Claim is beyond the scope of this specification. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The "amr" value is an array of case sensitive strings. azp OPTIONAL or REQUIRED. Authorized Party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 "client_id" of the party that will be using it. This Claim is only REQUIRED when the party requesting the ID Token is not the same as the sole audience of the ID Token. It MAY be included even when the Authorized Party is the same as the sole audience. The "azp" value is a case sensitive string containing a StringOrURI value. sub_jwk NOT RECOMMENDED or REQUIRED. Public key value used to check the signature of an ID Token issued by a Self-Issued OpenID Provider, as specified in Section 6. The key is a bare key in JWK [JWK] format (not an X.509 certificate value). Use of the "sub_jwk" Claim is REQUIRED when the OP is a Self-Issued OP and is NOT RECOMMENDED when the OP is not Self-Issued. The "iss" value is a JSON object. ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored. ID Tokens MUST be signed using JWS [JWS] and OPTIONALLY both signed and then encrypted using JWS [JWS] and JWE [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality, per Section 9.13. ID Tokens MUST NOT use "none" as the "alg" value. ID Tokens SHOULD NOT use the JWS or JWE "x5u", "x5c", "jku", or "jwk" header parameter fields. Instead, key values and key references used for ID Tokens are communicated in advance using Discovery and Registration parameters. Clients MUST validate the ID Token per Section 4.2. Sakimura, et al. [Page 18] OpenID Connect Messages 1.0 July 2013 The following is a non-normative example of a base64url decoded ID Token: { "iss": "https://server.example.com", "sub": "24400320", "aud": "s6BhdRkqt3", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "auth_time": 1311280969, "acr": "urn:mace:incommon:iap:silver", "at_hash": "MTIzNDU2Nzg5MDEyMzQ1Ng" } 2.1.3. Authorization Error Response If the End-User denies the access request or if the request fails, the OP (Authorization Server) informs the RP (Client) by using the Error Response parameters defined in Sections 4.1.2.1 or 4.2.2.1 of OAuth 2.0 [RFC6749], according to the "response_type" used. In addition to the error codes defined in Sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0, this specification also defines the following error codes: interaction_required The Authorization Server requires End-User interaction of some form to proceed. This error MAY be returned when the "prompt" parameter in the Authorization Request is set to "none" to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End- User interaction. login_required The Authorization Server requires End-User authentication. This error MAY be returned when the "prompt" parameter in the Authorization Request is set to "none" to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for user authentication. session_selection_required The End-User is REQUIRED to select a session at the Authorization Server. The End-User MAY be authenticated at the Authorization Server with different associated accounts, but the End-User did not select a session. This error MAY be returned when the "prompt" parameter in the Authorization Request is set to "none" to request that the Sakimura, et al. [Page 19] OpenID Connect Messages 1.0 July 2013 Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface to prompt for a session to use. consent_required The Authorization Server requires End-User consent. This error MAY be returned when the "prompt" parameter in the Authorization Request is set to "none" to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End-User consent. invalid_request_uri The "request_uri" in the Authorization Request returns an error or contains invalid data. invalid_request_object The "request" parameter contains an invalid Request Object. registration_not_supported The OP does not support use of the "registration" parameter. request_not_supported The OP does not support use of the "request" parameter. request_uri_not_supported The OP does not support use of the "request_uri" parameter. 2.2. Token Endpoint The RP (Client) sends an Access Token Request to the Token Endpoint to obtain an Access Token Response, which MAY include an Access Token, a Refresh Token, an ID Token, and other results. 2.2.1. Client Authentication 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 [RFC6749] using HTTP Basic authentication scheme. Sakimura, et al. [Page 20] OpenID Connect Messages 1.0 July 2013 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 [RFC6749] by including the Client Credentials in the request body. client_secret_jwt Clients that have received a "client_secret" value from the Authorization Server create a JWT using an HMAC SHA algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of the UTF-8 representation of the "client_secret" as the shared key. The Client authenticates in accordance with Section 2.2 of OAuth JWT Bearer Token Profiles [OAuth.JWT] and OAuth 2.0 Assertion Profile [OAuth.Assertions]. The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values: iss REQUIRED. Issuer. This MUST contain the "client_id" of the OAuth Client. sub REQUIRED. Subject. This MUST contain the "client_id" of the OAuth Client. aud REQUIRED. Audience. The "aud" (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint. jti REQUIRED. JWT ID. A unique identifier for the token. The JWT ID MAY be used by implementations requiring message de- duplication for one-time use assertions. exp REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. iat OPTIONAL. Time at which the JWT was issued. ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored. The authentication token MUST be sent as the value of the [OAuth.Assertions] "client_assertion" parameter. Sakimura, et al. [Page 21] OpenID Connect Messages 1.0 July 2013 The value of the [OAuth.Assertions] "client_assertion_type" parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", per [OAuth.JWT]. private_key_jwt Clients that have registered a public key sign a JWT using that key. The Client authenticates in accordance with Section 2.2 of OAuth JWT Bearer Token Profiles [OAuth.JWT] and OAuth 2.0 Assertion Profile [OAuth.Assertions]. The JWT MUST contain the following REQUIRED Claim Values and MAY contain the following OPTIONAL Claim Values: iss REQUIRED. Issuer. This MUST contain the "client_id" of the OAuth Client. sub REQUIRED. Subject. This MUST contain the "client_id" of the OAuth Client. aud REQUIRED. Audience. The "aud" (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint. jti REQUIRED. JWT ID. A unique identifier for the token. The JWT ID MAY be used by implementations requiring message de- duplication for one-time use assertions. exp REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. iat OPTIONAL. Time at which the JWT was issued. The JWT MAY contain other Claims. Any Claims used that are not understood MUST be ignored. The authentication token MUST be sent as the value of the [OAuth.Assertions] "client_assertion" parameter. The value of the [OAuth.Assertions] "client_assertion_type" parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", per [OAuth.JWT]. Sakimura, et al. [Page 22] OpenID Connect Messages 1.0 July 2013 For example (with line wraps within values for display purposes only): POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=i1WsRn1uB1& client_id=s6BhdRkqt3& client_assertion_type= urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT 2.2.2. Access Token Request The Client obtains an Access Token by authenticating with the Authorization Server and presenting its Authorization Grant (in the form of an Authorization Code or Refresh Token). In addition to the Client authentication parameters, if this is a Refresh Token Request, the Client MUST send the additional parameters specified in Section 6 of OAuth 2.0 [RFC6749]. Otherwise, the Client MUST send the request parameters as specified in Section 4.1.3 of OAuth 2.0 [RFC6749]. 2.2.3. Access Token Response 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 [RFC6749]. This specification only describes OAuth 2.0 Bearer Token Usage [RFC6750]. The OAuth 2.0 response parameter "token_type" MUST be set to "Bearer" unless another Token Type has been negotiated with the Client. Servers SHOULD support OAuth 2.0 Bearer Token Usage [RFC6750] for interoperability. For security reasons Servers MAY only allow Clients to register specific "token_type". Clients MUST support OAuth 2.0 Bearer Token Usage [RFC6750] and MAY support other "token_type". In addition to the OAuth 2.0 response parameters, the following parameters MUST be included in the response if the "grant_type" value is "authorization_code" and the Authorization Request "scope" Sakimura, et al. [Page 23] OpenID Connect Messages 1.0 July 2013 parameter contained "openid": id_token ID Token value associated with the authenticated session. An "id_token" MUST be returned when the "grant_type" value is "authorization_code" and MAY be returned when other grant types are used. Following is a non-normative example: { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso" } As in the OAuth 2.0 [RFC6749], Clients SHOULD ignore unrecognized response parameters. If an ID Token is returned as a result of a token refresh request, the following requirements apply: o its "iss" Claim value MUST be the same as in the ID Token issued when the original authentication occurred, o its "sub" Claim value MUST be the same as in the ID Token issued when the original authentication occurred, o its "iat" Claim MUST represent the time that the new ID Token is issued, o its "aud" Claim value MUST be the same as in the ID Token issued when the original authentication occurred, o if the ID Token contains an "auth_time" Claim, its value MUST represent the time of the original authentication - not the time that the new ID token is issued, o its "azp" Claim value MUST be the same as in the ID Token issued when the original authentication occurred; if no "azp" Claim was present in the original ID Token, one MUST NOT be present in the new ID Token, and o otherwise, the same rules apply as apply when issuing an ID Token at the time of the original authentication. Sakimura, et al. [Page 24] OpenID Connect Messages 1.0 July 2013 2.2.4. Access Token Error Response 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 [RFC6749]. 2.3. UserInfo Endpoint The UserInfo Endpoint is a Protected Resource that returns Claims about the authenticated End-User. These Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims. 2.3.1. UserInfo Request Clients send requests with the following parameters to the UserInfo Endpoint to obtain Claims about the End-User: access_token REQUIRED. Access Token obtained from an OpenID Connect Authorization Request. 2.3.2. UserInfo Response The UserInfo Claims MUST be returned as the members of a JSON object unless a signed or encrypted response was requested during Client Registration. The Claims defined in Section 2.5 can be returned, as can additional Claims not specified there. If a Claim is not returned, that Claim Name SHOULD be omitted from the JSON object representing the Claims; it SHOULD NOT be present with a null or empty string value. The "sub" (subject) Claim MUST always be returned in the UserInfo Response. NOTE: The UserInfo Endpoint response is not guaranteed to be about the End-User identified by the "sub" (subject) element of the ID Token. The "sub" Claim in the UserInfo Endpoint response MUST be verified to exactly match the "sub" Claim in the ID Token before using additional UserInfo Endpoint Claims. 2.3.3. UserInfo Error Response When an error condition occurs, the UserInfo Endpoint returns an Error Response as defined in Section 3 of OAuth 2.0 Bearer Token Usage [RFC6750]. Sakimura, et al. [Page 25] OpenID Connect Messages 1.0 July 2013 2.4. Scope Values OpenID Connect Clients use "scope" values as defined in 3.3 of OAuth 2.0 [RFC6749] to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. This specification describes only the scope values used by OpenID Connect. OpenID Connect allows additional scope values to be defined and used. Scope values used that are not understood by an implementation SHOULD be ignored. Claims requested by the following scopes are treated by Authorization Servers as Voluntary Claims. OpenID Connect defines the following "scope" values: openid REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the "openid" scope value is not present, the behavior is entirely unspecified. profile OPTIONAL. This scope value requests access to the End- User's default profile Claims, which are: "name", "family_name", "given_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", and "updated_at". email OPTIONAL. This scope value requests access to the "email" and "email_verified" Claims. address OPTIONAL. This scope value requests access to the "address" Claim. phone OPTIONAL. This scope value requests access to the "phone_number" and "phone_number_verified" Claims. offline_access OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End-User is not present (not logged in). Multiple scope values MAY be used by creating a space delimited, case sensitive list of ASCII scope values. The Claims requested by the "profile", "email", "address", and Sakimura, et al. [Page 26] OpenID Connect Messages 1.0 July 2013 "phone" scope values are returned from the UserInfo Endpoint, as described in Section 2.3.2, when a "response_type" value is used that results in an Access Token being issued. However, when the "response_type" value used is "id_token" (which issues no Access Token), the resulting Claims are returned in the ID Token. In some cases, the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by Clients. To minimize the amount of information that the End-User is being asked to disclose, a Client can elect to only request a subset of the information available from the UserInfo Endpoint. The following is a non-normative example of a "scope" Request. scope=openid profile email phone 2.5. Standard Claims This specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response or in the ID Token. Sakimura, et al. [Page 27] OpenID Connect Messages 1.0 July 2013 +-----------------------+---------+---------------------------------+ | Member | Type | Description | +-----------------------+---------+---------------------------------+ | sub | string | Subject - Identifier for the | | | | End-User at the Issuer. | | | | | | name | string | End-User's full name in | | | | displayable form including all | | | | name parts, possibly including | | | | titles and suffixes, ordered | | | | according to the End-User's | | | | locale and preferences. | | | | | | given_name | string | Given name(s) or first name(s) | | | | of the End-User. Note that in | | | | some cultures, people can have | | | | multiple given names; all can | | | | be present, with the names | | | | being separated by space | | | | characters. | | | | | | family_name | string | Surname(s) or last name(s) of | | | | the End-User. Note that in | | | | some cultures, people can have | | | | multiple family names or no | | | | family name; all can be | | | | present, with the names being | | | | separated by space characters. | | | | | | middle_name | string | Middle name(s) of the End-User. | | | | Note that in some cultures, | | | | people can have multiple middle | | | | names; all can be present, with | | | | the names being separated by | | | | space characters. Also note | | | | that in some cultures, middle | | | | names are not used. | | | | | | nickname | string | Casual name of the End-User | | | | that may or may not be the same | | | | as the "given_name". For | | | | instance, a "nickname" value of | | | | "Mike" might be returned | | | | alongside a "given_name" value | | | | of "Michael". | | | | | Sakimura, et al. [Page 28] OpenID Connect Messages 1.0 July 2013 | preferred_username | string | Shorthand name that the | | | | End-User wishes to be referred | | | | to at the RP, such as "janedoe" | | | | or "j.doe". This value MAY be | | | | any valid JSON string including | | | | special characters such as "@", | | | | "/", or whitespace. This value | | | | MUST NOT be relied upon to be | | | | unique by the RP. (See | | | | Section 2.5.3.) | | | | | | profile | string | URL of the End-User's profile | | | | page. The contents of this Web | | | | page SHOULD be about the | | | | End-User. | | | | | | picture | string | URL of the End-User's profile | | | | picture. This URL MUST refer | | | | to an image file (for example, | | | | a PNG, JPEG, or GIF image | | | | file), rather than to a Web | | | | page containing an image. Note | | | | that this URL SHOULD | | | | specifically reference a | | | | profile photo of the End-User | | | | suitable for displaying when | | | | describing the End-User, rather | | | | than an arbitrary photo taken | | | | by the End-User. | | | | | | website | string | URL of the End-User's Web page | | | | or blog. This Web page SHOULD | | | | contain information published | | | | by the End-User or an | | | | organization that the End-User | | | | is affiliated with. | | | | | | email | string | End-User's preferred e-mail | | | | address. Its value MUST | | | | conform to the RFC 5322 | | | | [RFC5322] addr-spec syntax. | | | | This value MUST NOT be relied | | | | upon to be unique by the RP, as | | | | discussed in Section 2.5.3. | | | | | Sakimura, et al. [Page 29] OpenID Connect Messages 1.0 July 2013 | email_verified | boolean | True if the End-User's e-mail | | | | address has been verified; | | | | otherwise false. When this | | | | Claim Value is "true", this | | | | means that the OP took | | | | affirmative steps to ensure | | | | that this e-mail address was | | | | controlled by the End-User at | | | | the time the verification was | | | | performed. The means by which | | | | an e-mail address is verified | | | | is context-specific, and | | | | dependent upon the trust | | | | framework or contractual | | | | agreements within which the | | | | parties are operating. | | | | | | gender | string | End-User's gender. Values | | | | defined by this specification | | | | are "female" and "male". Other | | | | values MAY be used when neither | | | | of the defined values are | | | | applicable. | | | | | | birthdate | string | End-User's birthday, | | | | represented as an ISO 8601:2004 | | | | [ISO8601-2004] "YYYY-MM-DD" | | | | format. The year MAY be | | | | "0000", indicating that it is | | | | omitted. To represent only the | | | | year, "YYYY" format is allowed. | | | | Note that depending on the | | | | underlying platform's date | | | | related function, providing | | | | just year can result in varying | | | | month and day, so the | | | | implementers need to take this | | | | factor into account to | | | | correctly process the dates. | | | | | | zoneinfo | string | String from zoneinfo [zoneinfo] | | | | time zone database representing | | | | the End-User's time zone. For | | | | example, "Europe/Paris" or | | | | "America/Los_Angeles". | | | | | Sakimura, et al. [Page 30] OpenID Connect Messages 1.0 July 2013 | locale | string | End-User's locale, represented | | | | as a BCP47 [RFC5646] language | | | | tag. This is typically an ISO | | | | 639-1 Alpha-2 [ISO639-1] | | | | language code in lowercase and | | | | an ISO 3166-1 Alpha-2 | | | | [ISO3166-1] country code in | | | | uppercase, separated by a dash. | | | | For example, "en-US" or | | | | "fr-CA". As a compatibility | | | | note, some implementations have | | | | used an underscore as the | | | | separator rather than a dash, | | | | for example, "en_US"; | | | | Implementations MAY choose to | | | | accept this locale syntax as | | | | well. | | | | | | phone_number | string | End-User's preferred telephone | | | | number. E.164 [E.164] is | | | | RECOMMENDED as the format of | | | | this Claim, for example, "+1 | | | | (425) 555-1212" or "+56 (2) 687 | | | | 2400". If the phone number | | | | contains an extension, it is | | | | RECOMMENDED that the extension | | | | be represented using the RFC | | | | 3966 [RFC3966] extension | | | | syntax, for example, "+1 (604) | | | | 555-1234;ext=5678". | | | | | Sakimura, et al. [Page 31] OpenID Connect Messages 1.0 July 2013 | phone_number_verified | boolean | True if the End-User's phone | | | | number has been verified; | | | | otherwise false. When this | | | | Claim Value is "true", this | | | | means that the OP took | | | | affirmative steps to ensure | | | | that this phone number was | | | | controlled by the End-User at | | | | the time the verification was | | | | performed. The means by which | | | | a phone number is verified is | | | | context-specific, and dependent | | | | upon the trust framework or | | | | contractual agreements within | | | | which the parties are | | | | operating. When true, the | | | | "phone_number" Claim MUST be in | | | | E.164 format and any extensions | | | | MUST be represented in RFC 3966 | | | | format. | | | | | | address | JSON | End-User's preferred address. | | | object | The value of the "address" | | | | member is a JSON [RFC4627] | | | | structure containing some or | | | | all of the members defined in | | | | Section 2.5.1. | | | | | | updated_at | number | Time the End-User's information | | | | was last updated. The time is | | | | represented as the number of | | | | seconds from 1970-01-01T0:0:0Z | | | | as measured in UTC until the | | | | date/time. | +-----------------------+---------+---------------------------------+ Table 1: Reserved Member Definitions For privacy reasons, OpenID Providers MAY elect to not return values for some requested Claims. The "sub" (subject) Claim in the UserInfo Endpoint response MUST exactly match the "sub" Claim in the ID Token, before using additional UserInfo Endpoint Claims. The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during Registration [OpenID.Registration]. The UserInfo Endpoint MAY return Claims in Sakimura, et al. [Page 32] OpenID Connect Messages 1.0 July 2013 JWT format, which can be signed and/or encrypted. The UserInfo Endpoint MUST return a content-type header to indicate which format 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" } 2.5.1. Address Claim The Address Claim represents 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 are combined. formatted Full mailing address, formatted for display or use on a mailing label. This field MAY contain multiple lines, separated by newline characters. street_address Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field MAY contain multiple lines, separated by newline characters. Sakimura, et al. [Page 33] OpenID Connect Messages 1.0 July 2013 locality City or locality component. region State, province, prefecture or region component. postal_code Zip code or postal code component. country Country name component. 2.5.2. Claims Languages and Scripts Human-readable Claim Values and Claim Values that reference human- readable values MAY be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 [RFC5646] language tags are added to member names, delimited by a "#" character. For example, "family_name#ja-Kana-JP" expresses the Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same represented as "family_name#ja-Hani-JP". As another example, both "website" and "website#de" Claim Values might be returned, referencing a Web site in an unspecified language and a Web site in German. Since Claim Names are case sensitive, it is strongly RECOMMENDED that language tag values used in Claim Names be spelled using the character case with which they are registered in the IANA Language Subtag Registry [IANA.Language]. In particular, normally language names are spelled with lowercase characters, region names are spelled with uppercase characters, and scripts are spelled with mixed case characters. However, since BCP47 language tag values are case insensitive, implementations SHOULD interpret the language tag values supplied in a case insensitive manner. Per the recommendations in BCP47, language tag values for Claims SHOULD only be as specific as necessary. For instance, using "fr" might be sufficient in many contexts, rather than "fr-CA" or "fr-FR". Where possible, OPs SHOULD try to match requested Claim locales with Claims it has. For instance, if the Client asks for a Claim with a "de" (German) language tag and the OP has a value tagged with "de-CH" (Swiss German) and no generic German value, it would be appropriate for the OP to return the Swiss German value to the Client. (This intentionally moves as much of the complexity of language tag matching to the OP as possible, to simplify Clients.) A "claims_locales" request can be used to specify the preferred languages and scripts to use for the returned Claims. Section 2.6.2 describes how to request that specific Claims use particular languages and scripts. When the OP determines, either through the "claims_locales" Sakimura, et al. [Page 34] OpenID Connect Messages 1.0 July 2013 parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags. 2.5.3. Claim Stability and Uniqueness The "sub" (subject) and "iss" (issuer) Claims are the only Claims that a Client can rely upon as a stable identifier for the End-User, since the "sub" Claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2.1.2.1. Therefore, the only guaranteed unique identifier for a given End-User is the combination of the "iss" Claim and the "sub" Claim. All other Claims carry no such guarantees across different issuers in terms of stability over time or uniqueness across users, and Issuers are permitted to apply local restrictions and policies. For instance, an Issuer MAY re-use an "email" Claim value across different End-Users at different points in time, and the claimed "email" address for a given End-User MAY change over time. Therefore, other Claims such as "email", "phone_number", and "preferred_username" and MUST NOT be used as unique identifiers for the End-User. 2.5.4. Additional Claims While this specification defines only small set of Claims as standard Claims, other Claims MAY be used in conjunction with the standard Claims. When using such Claims, it is RECOMMENDED that collision resistant names be used for the Claim Names, as described in Section 4.2 (Public Claim Names) of the JSON Web Token (JWT) [JWT] specification. Alternatively, Private Claim Names can be safely used when naming conflicts are unlikely to arise, as described in 4.3 of the JWT specification. Or, if specific additional Claims will have broad and general applicability, they can be registered with Reserved Claim Names, per Sections 4.1 and 9.1 of the JWT specification. 2.6. Claims Request The "claims" parameter requests that specific Claims be returned from the UserInfo Endpoint and/or in the ID Token. It is represented as a JSON object containing lists of Claims being requested from these locations. Properties of the Claims being requested MAY also be specified. Sakimura, et al. [Page 35] OpenID Connect Messages 1.0 July 2013 Support for the "claims" parameter is OPTIONAL. Should an OP not support this parameter and an RP uses it, the OP SHOULD return a set of Claims to the RP that it believes would be useful to the RP and the End-User using whatever heuristics it believes are appropriate. The "claims_parameter_supported" Discovery result indicates whether the OP supports this parameter. The "claims" parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON (which ends up being form-urlencoded when passed as an OAuth parameter). When used in a Request Object value, per Section 2.9, the JSON is used as the value of the "claims" member. The top-level members of the Claims request JSON object are: userinfo OPTIONAL. Requests that the listed individual Claims be returned from the UserInfo Endpoint. If present, the listed Claims are being requested to be added to any Claims that are being requested using "scope" values. If not present, the Claims being requested from the UserInfo Endpoint are only those requested using "scope" values. When the "userinfo" member is used, the request MUST also use a "response_type" value that results in an Access Token being issued to use at the UserInfo Endpoint. id_token OPTIONAL. Requests that the listed individual Claims be returned in the ID Token. If present, the listed Claims are being requested to be added to the default Claims in the ID Token. If not present, the default ID Token Claims are requested. Other members MAY be present. Any members used that are not understood MUST be ignored. Sakimura, et al. [Page 36] OpenID Connect Messages 1.0 July 2013 An example Claims request is as follows: { "userinfo": { "given_name": {"essential": true}, "nickname": null, "email": {"essential": true}, "email_verified": {"essential": true}, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": {"essential": true}, "acr": {"values": ["urn:mace:incommon:iap:silver"] } } } Note that a Claim that is not in the standard set defined in Section 2.5, the (example) "http://example.info/claims/groups" Claim, is being requested. Using the "claims" parameter is the only way to request Claims outside the standard set. It is also the only way to request specific combinations of the standard Claims that cannot be specified using scope values. 2.6.1. Individual Claims Requests The "userinfo" and "id_token" members of the "claims" request both are JSON objects with the names of the individual Claims being requested as the member names. The member values MUST be one of the following: null Indicates that this Claim is being requested in the default manner. In particular, this is a Voluntary Claim. For instance, the Claim request: "given_name": null requests the "given_name" Claim in the default manner. JSON Object Used to provide additional information about the Claim being requested. This specification defines the following members: Sakimura, et al. [Page 37] OpenID Connect Messages 1.0 July 2013 essential OPTIONAL. Indicates whether the Claim being requested is an Essential Claim. If the value is "true", this indicates that the Claim is an Essential Claim. For instance, the Claim request: "auth_time": {"essential": true} can be used to specify that it is Essential to return an "auth_time" Claim Value. If the value is "false", it indicates that it is a Voluntary Claim. The default is "false". By requesting Claims as Essential Claims the Client indicates to the End-User that releasing these Claims will ensure a smooth authorization for the specific task requested by the End-User. Note that even if the Claims are not available because the End-User did not authorize their release or they are not present, the Authorization Server MUST NOT generate an error when Claims are not returned, whether they are Essential or Voluntary. value OPTIONAL. Requests that the Claim be returned with a particular value. For instance the Claim request: "sub": {"value": "248289761001"} can be used to specify that the request apply to the End-User with subject identifier "248289761001". The value of the "value" member MUST be a valid value for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the "value" qualifier is to be used when requesting that Claim. values OPTIONAL. Requests that the Claim be returned with one of a set of values, with the values appearing in order of preference. For instance the Claim request: "acr": {"essential": true, "values": ["urn:mace:incommon:iap:silver", "urn:mace:incommon:iap:bronze"]} specifies that it is Essential that the "acr" Claim be returned with either the value "urn:mace:incommon:iap:silver" or "urn:mace:incommon:iap:bronze". Sakimura, et al. [Page 38] OpenID Connect Messages 1.0 July 2013 The values in the "values" member array MUST be valid values for the Claim being requested. Definitions of individual Claims can include requirements on how and whether the "values" qualifier is to be used when requesting that Claim. Other members MAY be defined to provide additional information about the requested Claims. Any members used that are not understood MUST be ignored. Note that when the "claims" request parameter is supported, the scope values that request Claims, as defined in Section 2.4, are effectively shorthand methods for requesting sets of individual Claims. For example, using the scope value "openid email" and a "response_type" that returns an Access Token is equivalent to using the scope value "openid" and the following request for individual Claims. Equivalent of using the "email" scope value: { "userinfo": { "email": null, "email_verified": null } } 2.6.2. Languages and Scripts for Individual Claims As described in Section 2.5.2, human-readable Claims values and Claim Values that reference human-readable values MAY be represented in multiple languages and scripts. Within a request for individual Claims, requested languages and scripts for particular Claims MAY be requested by including Claim Names that contain "#"-separated BCP47 [RFC5646] language tags in the Claims request, using the Claim Name syntax specified in Section 2.5.2. For example, a Family Name in Katakana in Japanese can be requested using the Claim Name "family_name#ja-Kana-JP" and a Kanji representation of the Family Name in Japanese can be requested using the Claim Name "family_name#ja-Hani-JP". A German-language Web site can be requested with the Claim Name "website#de". If an OP receives a request for human-readable Claims in a language and script that it doesn't have, any versions of those Claims returned that don't use the requested language and script SHOULD use a language tag in the Claim Name. Sakimura, et al. [Page 39] OpenID Connect Messages 1.0 July 2013 2.7. Claim Types 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. 2.7.1. Normal Claims Normal Claims are represented as members in a JSON object. The Claim Name is the member name and the Claim Value is the member value. The following is a non-normative response containing Normal Claims: { "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "email": "janedoe@example.com", "picture": "http://example.com/janedoe/me.jpg" } 2.7.2. Aggregated and Distributed Claims Aggregated and distributed Claims are represented by using special "_claim_names" and "_claim_sources" members of the JSON object containing the Claims. _claim_names JSON object whose member names are the Claim Names for the Aggregated and Distributed Claims. The member values are references to the member names in the "_claim_sources" member from which the actual Claim Values can be retrieved. Sakimura, et al. [Page 40] OpenID Connect Messages 1.0 July 2013 _claim_sources JSON object whose member names are referenced by the member values of the "_claim_names" member. The member values contain sets of Aggregated Claims or reference locations for Distributed Claims. The member values can have one of the following formats depending on whether it is providing Aggregated or Distributed Claims: Aggregated Claims JSON object that MUST contain the "JWT" member whose value is a JWT [JWT] that MUST contain all the Claims in the "_claim_names" object that references the corresponding "_claim_sources" member. Other members MAY be present. Any members used that are not understood MUST be ignored. JWT REQUIRED. JWT containing Claim Values. The JWT SHOULD NOT contain a "sub" (subject) Claim unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a "sub" Claim SHOULD NOT be provided. Distributed Claims JSON object that contains the following members and values: endpoint REQUIRED. OAuth 2.0 resource endpoint from which the associated Claim can be retrieved. The endpoint URL MUST return the Claim as a JWT. access_token OPTIONAL. Access Token enabling retrieval of the Claims from the endpoint URL by using the OAuth 2.0 Bearer Token Usage [RFC6750] protocol. Claims SHOULD be requested using the Authorization Request header field and Claims Providers MUST support this method. If the Access Token is not available, Clients MAY need to retrieve the Access Token out of band or use an a priori Access Token that was negotiated between the Claims Provider and Client, or the Claims Provider MAY reauthenticate the End-User and/or reauthorize the Client. A "sub" (subject) Claim SHOULD NOT be returned from the Claims Provider unless its value is an identifier for the End-User at the Claims Provider (and not for the OpenID Provider or another party); this typically means that a "sub" Claim SHOULD NOT be provided. Sakimura, et al. [Page 41] OpenID Connect Messages 1.0 July 2013 2.7.2.1. Example of Aggregated Claims In this non-normative example, Claims from Claims Provider A are combined with other Claims held by the OpenID provider, with the Claims from Claims Provider A being returned as Aggregated Claims. In this example, these Claims about Jane Doe have been issued by Claims Provider A: { "address": { "street_address": "1234 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US"}, "phone_number": "+1 (310) 123-4567" } Claims Provider A signs the JSON Claims, representing them in a signed JWT: jwt_header.jwt_part2.jwt_part3. It is this JWT that is used by the OpenID Provider. In this example, this JWT containing Jane Doe's Aggregated Claims from Claims Provider A is combined with other Normal Claims, and returned as the following set of Claims: { "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "birthdate": "0000-03-22", "eye_color": "blue", "email": "janedoe@example.com", "_claim_names": { "address": "src1", "phone_number": "src1" }, "_claim_sources": { "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"} } } 2.7.2.2. Example of Distributed Claims In this non-normative example, the OpenID Provider combines Normal Claims that it holds with references to Claims held by two different Claims Providers, B and C, incorporating references to some of the Sakimura, et al. [Page 42] OpenID Connect Messages 1.0 July 2013 Claims held by B and C as Distributed Claims. In this example, these Claims about Jane Doe are held by Claims Provider B (Jane Doe's bank): { "shipping_address": { "street_address": "1234 Hollywood Blvd.", "locality": "Los Angeles", "region": "CA", "postal_code": "90210", "country": "US"}, "payment_info": "Some_Card 1234 5678 9012 3456", "phone_number": "+1 (310) 123-4567" } Also in this example, this Claim about Jane Doe is held by Claims Provider C (a credit agency): { "credit_score": 650 } The OpenID Provider returns Jane Doe's Claims along with references to the Distributed Claims from Claims Provider B and Claims Provider C by sending the Access Tokens and URLs of locations from which the Distributed Claims can be retrieved: { "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "email": "janedoe@example.com", "birthdate": "0000-03-22", "eye_color": "blue", "_claim_names": { "payment_info": "src1", "shipping_address": "src1", "credit_score": "src2" }, "_claim_sources": { "src1": {"endpoint": "https://bank.example.com/claim_source"}, "src2": {"endpoint": "https://creditagency.example.com/claims_here", "access_token": "ksj3n283dke"} } } Sakimura, et al. [Page 43] OpenID Connect Messages 1.0 July 2013 2.8. Subject Identifier Types The OpenID Provider's Discovery document SHOULD list its supported identifier types in the "subject_types_supported" element. If there is more than one type listed in the array, the Client MAY elect to provide its preferred identifier type using the "subject_type" parameter during Registration. The types supported by this specification are: public This provides the same "sub" (subject) value to all Clients. It is the default if the provider has no "subject_types_supported" element in its discovery document. pairwise This provides a different "sub" value to each Client, to prevent correlation of the End-User's activities by Clients without his permission. 2.8.1. Pairwise Identifier Algorithm The OpenID Provider MUST calculate a unique "sub" (subject) value for each Sector Identifier. The subject value MUST NOT be reversible by any party other than the OpenID Provider. Providers who use pairwise "sub" values SHOULD support the "sector_identifier_uri" in Dynamic Client Registration [OpenID.Registration]. It provides a way for a group of websites under common administrative control to have consistent pairwise "sub" values independent of the individual domain names. It also provides a way for Clients to change "redirect_uri" domains without having to reregister all of their users. If the Client has not provided a value for "sector_identifier_uri" in Dynamic Client Registration [OpenID.Registration], the Sector Identifier used for pairwise identifier calculation is the host component of the registered "redirect_uri". If there are multiple hostnames in the registered "redirect_uris", the Client MUST register a "sector_identifier_uri". When a "sector_identifier_uri" is provided, the host component of that URL is used as the Sector Identifier for the pairwise identifier calculation. The value of the "sector_identifier_uri" MUST be a URL using the "https" scheme that points to a JSON file containing an array of "redirect_uri" values. The values of the registered "redirect_uris" MUST be included in the elements of the array, or the registration MUST fail. A number of algorithms can be used by OpenID Providers to calculate pairwise identifiers. Three example methods are: Sakimura, et al. [Page 44] OpenID Connect Messages 1.0 July 2013 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 using 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 using an appropriate algorithm. Calculate "sub" = AES-128 ( sector_identifier | local_account_id | salt ). 3. The Issuer creates a Globally Unique Identifier (GUID) for the pair of Sector Identifier and local account ID and stores this value. 2.9. Request Object The "request" parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be signed and optionally encrypted. It represents the request as a JWT whose Claims are the request parameters specified in Section 2.1.1.1. This JWT is called a Request Object. Support for the "request" parameter is OPTIONAL. The "request_parameter_supported" Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the "request_not_supported" error. When the "request" parameter is used, the OpenID Connect request parameter values contained in the JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a Request Object is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that can vary with each request, such as "state" and "nonce", are passed as OAuth 2.0 parameters. Even if a "scope" parameter is present in the Request Object value, a "scope" parameter MUST always be passed using the OAuth 2.0 request Sakimura, et al. [Page 45] OpenID Connect Messages 1.0 July 2013 syntax containing the "openid" scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request. The Request Object MAY be signed or unsigned (plaintext). When it is plaintext, this is indicated by use of the "none" algorithm [JWA] in the JWS header. If signed, the Request Object SHOULD contain the Claims "iss" (issuer) and "aud" (audience) as members, with their semantics being as defined in the JWT [JWT] specification. The Request Object MAY also be encrypted using JWE [JWE], with nested signing and encryption performed as described in the JWT [JWT] specification. "request" and "request_uri" parameters MUST NOT be included in Request Objects. An example set of Request Object Claims before base64url encoding and JWS signing is as follows: { "response_type": "code id_token", "client_id": "s6BhdRkqt3", "redirect_uri": "https://client.example.org/cb", "scope": "openid", "state": "af0ifjsldkj", "login_hint": "janedoe@example.org", "max_age": 86400, "claims": { "userinfo": { "given_name": {"essential": true}, "nickname": null, "email": {"essential": true}, "email_verified": {"essential": true}, "picture": null }, "id_token": { "auth_time": {"essential": true}, "acr": { "values":["urn:mace:incommon:iap:silver"] } } } } Sakimura, et al. [Page 46] OpenID Connect Messages 1.0 July 2013 2.10. Using the "request_uri" Parameter The "request_uri" parameter enables OpenID Connect requests to be passed by reference, rather than by value. This parameter is used identically to the "request" parameter, other than that the Request Object value is retrieved from the resource at the specified URL, rather than passed by value. The "request_uri_parameter_supported" Discovery result indicates whether the OP supports this parameter. Should an OP not support this parameter and an RP uses it, the OP MUST return the "request_uri_not_supported" error. When the "request_uri" parameter is used, the OpenID Connect request parameter values contained in the referenced JWT supersede those passed using the OAuth 2.0 request syntax. However, some parameters MAY be passed using the OAuth 2.0 request syntax even when a "request_uri" is used; this would typically be done to enable a cached, pre-signed (and possibly pre-encrypted) Request Object value to be used containing the fixed request parameters, while parameters that can vary with each request, such as "state" and "nonce", are passed as OAuth 2.0 parameters. Even if a "scope" parameter is present in the referenced Request Object, a "scope" parameter MUST always be passed using the OAuth 2.0 request syntax containing the "openid" scope value to indicate to the underlying OAuth 2.0 logic that this is an OpenID Connect request. Servers MAY cache the contents of the resources referenced by request URIs. If the contents of the referenced resource could ever change, the URI SHOULD include the base64url encoded SHA-256 hash of the referenced resource contents as the fragment component of the URI. If the fragment value used for a URI changes, that signals the server that any cached value for that URI with the old fragment value is no longer valid. Note that Clients MAY pre-register "request_uri" values using the "request_uris" parameter defined in Section 2 of the OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] specification. 2.10.1. "request_uri" Rationale There are several reasons that one might choose to use the "request_uri" parameter: 1. The set of request parameters can become large, and can exceed browser URI size limitations. Passing the request parameters by reference can solve this problem. Sakimura, et al. [Page 47] OpenID Connect Messages 1.0 July 2013 2. Passing a "request_uri" value, rather than a complete request by value, can reduce request latency. 3. Most requests for Claims from an RP are constant. The "request_uri" is a way of creating and sometimes also signing and encrypting a constant set of request parameters in advance. (The "request_uri" value becomes an "artifact" representing a particular fixed set of request parameters.) 4. Pre-registering a fixed set of request parameters at registration time enables OPs to cache and pre-validate the request parameters at registration time, meaning they need not be retrieved at request time. 5. Pre-registering a fixed set of request parameters at registration time enables OPs to vet the contents of the request from consumer protection and other points of views, either itself or by utilizing a third party. Sakimura, et al. [Page 48] OpenID Connect Messages 1.0 July 2013 3. Signatures and Encryption Depending on the transport through which the messages are sent, the integrity of the message might not be guaranteed and the originator of the message might not be authenticated. To mitigate these risks, Request Object, Token Request, ID Token, and UserInfo Response values MAY utilize JSON Web Signature (JWS) [JWS] to sign the contents. To achieve message confidentiality, Request Object, Token Request, ID Token, and UserInfo Response values MAY use JSON Web Encryption (JWE) [JWE] to encrypt the content. When the message is both signed and encrypted, it MUST be signed first and then encrypted, per Section 9.13, with nesting performed in the same manner as specified for JWTs [JWT]. Note that all JWE encryption methods perform integrity checking. 3.1. Supported Algorithms The server advertises its supported signing and encryption algorithms in its discovery document. The algorithm identifiers are specified in JWA [JWA]. The related elements are: userinfo_signing_alg_values_supported JSON array containing a list of the JWS [JWS] signing algorithms ("alg" values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT]. userinfo_encryption_alg_values_supported JSON array containing a list of the JWE [JWE] encryption algorithms ("alg" values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT]. userinfo_encryption_enc_values_supported JSON array containing a list of the JWE encryption algorithms ("enc" values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT [JWT]. id_token_signing_alg_values_supported JSON array containing a list of the JWS signing algorithms ("alg" values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT]. id_token_encryption_alg_values_supported JSON array containing a list of the JWE encryption algorithms ("alg" values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT]. Sakimura, et al. [Page 49] OpenID Connect Messages 1.0 July 2013 id_token_encryption_enc_values_supported JSON array containing a list of the JWE encryption algorithms ("enc" values) supported by the Authorization Server for the ID Token to encode the Claims in a JWT [JWT]. request_object_signing_alg_values_supported JSON array containing a list of the JWS signing algorithms ("alg" values) supported by the Authorization Server for Request Object values. Servers SHOULD support "none" and "RS256". request_object_encryption_alg_values_supported JSON array containing a list of the JWE encryption algorithms ("alg" values) supported by the Authorization Server for Request Object values. request_object_encryption_enc_values_supported JSON array containing a list of the JWE encryption algorithms ("enc" values) supported by the Authorization Server for Request Object values. token_endpoint_auth_signing_alg_values_supported JSON array containing a list of the JWS signing algorithms ("alg" values) supported by the Token Endpoint for the "private_key_jwt" and "client_secret_jwt" methods to encode the JWT [JWT]. Servers SHOULD support "RS256". The Client registers its REQUIRED algorithms for Signing and Encryption using the following Registration parameters: request_object_signing_alg OPTIONAL. JWS signature algorithm [JWA] REQUIRED for Request Objects by the Authorization Server. All Request Objects from this "client_id" MUST be rejected if not signed by this algorithm. Servers SHOULD support "RS256". userinfo_signed_response_alg OPTIONAL. JWS signature algorithm [JWA] REQUIRED for UserInfo Responses. If this is specified the response will be JWT [JWT] serialized. userinfo_encrypted_response_alg OPTIONAL. JWE "alg" algorithm [JWA] REQUIRED for UserInfo Responses. If this is requested in combination with signing, the response MUST be signed first then encrypted, per Section 9.13. If this is specified, the response will be JWT [JWT] serialized. userinfo_encrypted_response_enc OPTIONAL. JWE "enc" algorithm [JWA] REQUIRED for UserInfo Responses. If "userinfo_encrypted_response_alg" is specified the default for this value is "A128CBC-HS256". Sakimura, et al. [Page 50] OpenID Connect Messages 1.0 July 2013 id_token_signed_response_alg OPTIONAL. JWS signature algorithm [JWA] REQUIRED for ID Tokens issued to this "client_id". The default if not specified is "RS256". The public key for validating the signature is provided by retrieving the JWK Set referenced by the "jwks_uri" element from Discovery. id_token_encrypted_response_alg OPTIONAL. JWE "alg" algorithm [JWA] REQUIRED for ID Tokens issued to this "client_id". If this is requested, the response MUST be signed then encrypted. The default if not specified is no encryption. id_token_encrypted_response_enc OPTIONAL. JWE "enc" algorithm [JWA] 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". 3.2. Keys The OpenID Provider provides its public keys during Discovery using the following element: jwks_uri REQUIRED. URL of the OP's JSON Web Key Set [JWK] document. This contains the signing key(s) the Client uses to validate signatures from the OP. The JWK Set MAY also contain the Server's encryption key(s), which are used by Clients to encrypt requests to the Server. When both signing and encryption keys are made available, a "use" (Key Use) parameter value is REQUIRED for all keys in the document to indicate each key's intended usage. Likewise, the Client can provide its public keys during Registration using the following element: jwks_uri OPTIONAL. URL for the Client's JSON Web Key Set [JWK] document. If the Client signs requests to the Server, it contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain the Client's encryption keys(s), which are used by the Server to encrypt responses to the Client. When both signing and encryption keys are made available, a "use" (Key Use) parameter value is REQUIRED for all keys in the document to indicate each key's intended usage. When both signing and encryption keys are made available, the "use" (Key Use) parameter value is REQUIRED for all keys in the JWK Set at the "jwks_uri" to indicate each key's intended usage. Although some algorithms allow the same key pair to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. In both cases, the JWK "x5c" parameter MAY be used to provide X.509 Sakimura, et al. [Page 51] OpenID Connect Messages 1.0 July 2013 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate. 3.3. Signing The signing party MUST select a signature algorithm based on the supported algorithms of the recipient in Section 3.1. 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 [JWA]. The private key MUST be the one associated with the Public Signing Key provided in Section 3.2. If there are multiple keys in the referenced JWK document, a "kid" value MUST be provided in the JWS header. The key usage of the respective keys MUST support signature. Symmetric Signatures When using MAC-based signatures, the "alg" Claim of the JWS header MUST be set to a MAC algorithm, as defined in JSON Web Algorithms [JWA]. The MAC key used is the octets of the UTF-8 representation of the "client_secret" value. See Section 9.17 for a discussion of entropy requirements for "client_secret" values. Symmetric signatures MUST never be used by public (non-confidential) Clients because of their inability to keep secrets. See Section 9.18 for Security Considerations about the need for signed requests. 3.3.1. Rotation of Asymmetric Signing Keys Rotation of signing keys can be accomplished with the following approach. The signer publishes its keys in a JWK Set at the "jwks_uri" location and includes the "kid" of the signing key in the JWS header of each message to indicate to the verifier which key is to be used to validate the signature. Keys can be rolled over by periodically adding new keys to the JWK Set at "jwks_uri". The signer can begin using a new key at its discretion and signals the change to the verifier using the "kid" value. The verifier knows to go back to the "jwks_uri" to re-retrieve the keys when it sees an unfamiliar "kid" value. The JWK Set document at the "jwks_uri" SHOULD retain recently decommissioned signing keys for a reasonable period of time to facilitate a smooth transition. 3.4. Encryption The encrypting party MUST select an encryption algorithm based on the supported algorithms of the recipient in Section 3.1. All JWTs MUST be signed before encryption to enable verification of the Issuer. Sakimura, et al. [Page 52] OpenID Connect Messages 1.0 July 2013 Asymmetric Encryption: RSA Use the link registered/discovered in Section 3.2 to retrieve the relevant key. If there are multiple keys in the referenced JWK document, a "kid" value MUST be provided in the JWE header. Use the supported RSA key wrapping algorithm to wrap a random "Content Master Key" to be used for encrypting the signed JWT. The key usage of the respective keys MUST include encryption. Asymmetric Encryption: Elliptic Curve Create an ephemeral Elliptic Curve public key for the "epk" element of the JWE header. Use the link registered/discovered in Section 3.2 to retrieve the relevant key. If there are multiple keys in the referenced JWK document, a "kid" value MUST be provided in the JWE header. Use the ECDH-ES algorithm to wrap a random "Content Master Key" to be used for encrypting the signed JWT. The key usage of the respective keys MUST support encryption. Symmetric Encryption The symmetric encryption key is derived from the "client_secret" value by using a left truncated SHA-256 hash of the octets of the UTF-8 representation of the "client_secret". The SHA-256 value MUST be left truncated to the appropriate bit length for the AES key wrapping algorithm used, for instance, to 128 bits for "A128KW". If a key wrapping key with greater than 256 bits is needed, a different method of deriving the key from the "client_secret" would have to be defined by an extension. Symmetric encryption MUST never be used by public (non- confidential) Clients because of their inability to keep secrets. See Section 9.19 for Security Considerations about the need for encrypted requests. 3.4.1. Rotation of Asymmetric Encryption Keys Rotating encryption keys is necessarily a different process than for signing keys because the encrypting party starts the process and thus cannot rely on a change in kid as a signal to know that keys need to change. The encrypting party still uses the kid header in the JWE to tell the decrypting party which private key to use to decrypt, however, the encrypting party needs to first select the most appropriate key from those provided in the JWK Set at "jwks_uri". To rotate keys, the decrypting party can publish new keys at "jwks_uri" and remove from the JWK Set those that are being decommissioned. The "jwks_uri" SHOULD include a "Cache-Control" header in the response that contains a "max-age" directive, as defined in RFC 2616 [RFC2616], which allows the encrypting party to safely cache the JWK Set and not have to re-retrieve the document for every encryption event. The decrypting party SHOULD remove decommissioned keys from the JWK Set at "jwks_uri" but retain them internally for some Sakimura, et al. [Page 53] OpenID Connect Messages 1.0 July 2013 reasonable period of time, coordinated with the cache duration, to facilitate a smooth transition between keys by allowing the encrypting party some time to obtain the new keys. The cache duration SHOULD also be coordinated with the issuance of new signing keys as described in Section 3.3.1. Sakimura, et al. [Page 54] OpenID Connect Messages 1.0 July 2013 4. Validation If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. 4.1. Authorization Request Validation Authorization Request Validation consists of two main steps: (1) decryption and signature validation of the value of "request" or the content of "request_uri", and (2) parameter validation. If a Request Object value was sent in the "request" parameter or by reference in the "request_uri" parameter, the Request Object MUST validate as JWS [JWS] or JWE [JWE] encoded objects, for which nested encryption and signing can be utilized in the manner described in the JWT [JWT] specification. 4.1.1. Encrypted Request Object If the Authorization Server has advertised JWE encryption algorithms in the "request_object_encryption_alg_values_supported" and "request_object_encryption_enc_values_supported" elements of its Discovery Document, these are used by the Client to encrypt the JWT. The Authorization Server MUST decode the JWT in accordance with the JSON Web Encryption [JWE] specification. The result MAY be either a signed or unsigned (plaintext) Request Object. In the former case, signature validation MUST be performed as defined in Section 4.1.2. The Authorization Server MUST return the error if there is a decryption error. 4.1.2. Signed Request Object 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 [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 [JWS] specification. The Authorization Server MUST return the Authorization Error Response if there is a signature validation error. Sakimura, et al. [Page 55] OpenID Connect Messages 1.0 July 2013 4.1.3. Parameter Validation The Authorization Server MUST construct the Authorization Request Message from the Request Object value and the OAuth 2.0 Authorization Request parameters. If the same parameter exists both in the Request Object and the OAuth Authorization Request parameters, the parameter in the Request Object is used. Using this Authorization Request Message, the Authorization Server performs the following steps of the request validation: 1. The Authorization Server MUST validate all the OAuth 2.0 parameters according to the OAuth 2.0 specification. 2. The Authorization Server MUST verify that all the REQUIRED parameters are present. 3. If the "sub" (subject) Claim as a member of "id_token" element is requested with a specific value, the Authorization Server MUST only send a positive response if that user has an active session with the Authorization Server. The Authorization Server MUST NOT reply with an ID Token or Access Token for a different user, even if they have an active session with the Authorization Server. 4. If the "acr" Claim is requested as an Essential Claim for the ID Token with a "values" parameter requesting specific Authentication Context Class Reference values, then the Authorization Server MUST return an "acr" Claim Value that matches one of the requested values. The Authorization Server MAY ask the End-User to re-authenticate with additional factors to meet this requirement. If this is an Essential Claim and the requirement cannot be met, then the Authorization Server MUST treat that outcome as a failed authentication attempt. 5. The Client MAY request this Claim as a Voluntary Claim by using the "acr_values" request parameter or by not including "essential": true in the individual "acr" Claim request. If the Claim is not Essential and the requested value cannot be provided, the Authorization Server SHOULD return the session's current "acr" as the value of the "acr" Claim. If the Claim is not Essential, the Authorization Server is not required to provide this Claim in its response. If the Authorization Server encounters any error, it MUST return the error response. Sakimura, et al. [Page 56] OpenID Connect Messages 1.0 July 2013 4.2. ID Token Validation To validate the ID Token in the Authorization or Token Endpoint Response, the Client MUST do the following: 1. If the Client has provided an "id_token_encrypted_response_alg" parameter during Registration, decrypt the ID Token using the key pair specified during Registration. 2. The Client MUST validate that the "aud" (audience) Claim contains its "client_id" value registered at the Issuer identified by the "iss" (issuer) Claim as an audience. The "aud" (audience) Claim MAY contain an array with more than one element. The ID Token MUST be rejected if the ID Token does not list the Client as a valid audience, or if it contains additional audiences not trusted by the Client. 3. If the ID Token contains multiple audiences, the Client SHOULD verify that an "azp" Claim is present. 4. If an "azp" (authorized party) Claim is present, the Client SHOULD verify and that its "client_id" is the Claim value. 5. If the "id_token" is received via direct communication between the Client and the Token Endpoint, the TLS server validation MAY be used to validate the issuer in place of checking the token signature. The Client MUST validate the signature of all other ID Tokens according to JWS [JWS] using the algorithm specified in the "alg" parameter of the JWT header. 6. The "alg" value SHOULD be the default of "RS256" or the algorithm sent by the Client in the "id_token_signed_response_alg" parameter during Registration. 7. If the "alg" parameter of the JWT header is a MAC based algorithm such as "HS256", "HS384", or "HS512", the octets of the UTF-8 representation of the "client_secret" corresponding to the "client_id" contained in the "aud" (audience) Claim are used as the key to validate the signature. Multiple audiences are not supported for MAC based algorithms. 8. For other Signing algorithms, the Client MUST use the signing key provided in Discovery by the Issuer. The issuer MUST exactly match the value of the "iss" (issuer) Claim. 9. The current time MUST be less than the value of the "exp" Claim. Sakimura, et al. [Page 57] OpenID Connect Messages 1.0 July 2013 10. The "iat" Claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is Client specific. 11. If a nonce value was sent in the Authorization Request, a "nonce" Claim MUST be present and its value checked to verify that it is the same value as the one that was sent in the Authorization Request. The Client SHOULD check the "nonce" value for replay attacks. The precise method for detecting replay attacks is Client specific. 12. If the "acr" Claim was requested, the Client SHOULD check that the asserted Claim Value is appropriate. The meaning and processing of "acr" Claim Values is out of scope for this specification. 13. If the "auth_time" Claim was requested, either through a specific request for this Claim or by using the "max_age" parameter, the Client SHOULD check the "auth_time" Claim value and request re-authentication if it determines too much time has elapsed since the last End-User authentication. 4.3. UserInfo Response Validation To validate the UserInfo Response, the Client MUST do the following: 1. If the Client has provided a "userinfo_encrypted_response_alg" parameter during Registration, decrypt the UserInfo Response using the key pair specified during Registration. 2. If the response was signed, the Client SHOULD validate the signature according to JWS [JWS]. 3. Check that the OP that responded was the intended OP through a TLS server certificate check, per RFC 6125 [RFC6125]. 4.4. Access Token Validation To validate an Access Token issued from the Authorization Endpoint with an ID Token in response to a request containing a "response_type" of "id_token token" or "code id_token token", the Client SHOULD do the following: 1. Hash the octets of the ASCII representation of the "access_token" with the hash algorithm specified in JWS [JWA] for the "alg" parameter in the ID Token's JWS [JWS] header. Sakimura, et al. [Page 58] OpenID Connect Messages 1.0 July 2013 2. Take the left-most half of the hash and base64url encode it. 3. The value of "at_hash" in the ID Token MUST match the value produced in the previous step if "at_hash" is present in the ID Token. 4.5. Code Validation To validate a "code" issued from the Authorization Endpoint with an ID Token in response to a request containing a "response_type" of "code id_token" or "code id_token token", the Client SHOULD do the following: 1. Hash the octets of the ASCII representation of the "code" with the hash algorithm specified in JWS [JWA] for the "alg" parameter in the ID Token's JWS [JWS] header. 2. Take the left-most half of the hash and base64url encode it. 3. The value of "c_hash" in the ID Token MUST match the value produced in the previous step if "c_hash" is present in the ID Token. Sakimura, et al. [Page 59] OpenID Connect Messages 1.0 July 2013 5. Offline Access The "offline_access" scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User's UserInfo Endpoint even when the End- User is not present (not logged in). When offline access is requested, a "prompt" parameter value of "consent" MUST be used unless other conditions for processing permitting offline access to the requested resources are in place. The OP MUST always obtain consent to returning a Refresh Token that enables offline access to the requested resources. A previously saved user consent is not always sufficient to grant offline access. Upon receipt of a scope parameter containing the "offline_access" value, the Authorization Server: o MUST ensure that the prompt parameter contains "consent" unless other conditions for processing permitting offline access to the requested resources are in place; unless one or both of these conditions are fulfilled, then it MUST ignore the "offline_access" request, o MUST ignore the "offline_access" request unless the Client is using a "response_type" value that would result in an Authorization Code being returned, o MUST explicitly receive or have consent for all Clients when the registered "application_type" is "web", o SHOULD explicitly receive or have consent for all Clients when the registered "application_type" is "native". 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. Sakimura, et al. [Page 60] OpenID Connect Messages 1.0 July 2013 6. Self-Issued OpenID Provider OpenID Connect supports Self-Issued OpenID Providers - personal OPs that issue self-signed ID Tokens. Self-Issued OPs use the special Issuer Identifier "https://self-issued.me". 6.1. Self-Issued OpenID Provider Discovery If the input identifier for the discovery process contains the domain self-issued.me, dynamic discovery is not performed. Instead, then the following static configuration values are used: { "authorization_endpoint": "openid:", "issuer": "https://self-issued.me", "scopes_supported": ["openid", "profile", "email", "address", "phone"], "response_types_supported": ["id_token"], "subject_types_supported": ["pairwise"], "id_token_signing_alg_values_supported": ["RS256"], "request_object_signing_alg_values_supported": ["none", "RS256"] } Note: The OpenID Foundation may consider hosting a site https://self-issued.me/ that returns the above static configuration file so that the Client would not need any special treatment for discovery of the Self-Issued OP. 6.2. Self-Issued OpenID Provider Registration When using a Self-Issued OP, the Client is deemed to have registered with the OP and obtained following Client Registration Response. client_id "redirect_uri" value of the Client. client_secret_expires_at 0 Note: The OpenID Foundation may consider hosting the (stateless) endpoint "https://self-issued.me/registration/1.0/" that returns the response above so that the Client would not need to perform any special processing for registration of a Self-Issued OP. Sakimura, et al. [Page 61] OpenID Connect Messages 1.0 July 2013 6.2.1. Providing Additional Registration Information The "registration" request parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration. The value is a JSON object containing name/value pairs defined in Section 2.1 of the OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] specification. None of this information is REQUIRED by Self-Issued OPs, so the use of this parameter is OPTIONAL. The "registration" parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON (which ends up being form-urlencoded when passed as an OAuth parameter). When used in a Request Object value, per Section 2.9, the JSON is used as the value of the "registration" member. The Registration parameters that would typically be used in requests to Self-Issued OPs are "policy_uri", "tos_uri", and "logo_uri". If the Client uses more than one redirection URI, the "redirect_uris" parameter would be used to register them. Finally, if the Client is requesting encrypted responses, it would use the "jwks_uri", "id_token_encrypted_response_alg" and "id_token_encrypted_response_enc" parameters. 6.3. Self-Issued OpenID Provider Request The Client sends the Authorization Request to the Authorization Endpoint with the following parameters: response_type REQUIRED. Constant string value "id_token". client_id REQUIRED. Client ID value for the Client, which in this case contains the "redirect_uri" value of the Client. Since the Client's "redirect_uri" URI value is communicated as the Client ID, a "redirect_uri" parameter is NOT REQUIRED to also be included in the request. scope REQUIRED. "scope" parameter value, as specified in Section 2.4. id_token_hint OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. This SHOULD be present when "prompt=none" is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response. Sakimura, et al. [Page 62] OpenID Connect Messages 1.0 July 2013 If the ID Token received by the RP is encrypted, the Client MUST decrypt the signed ID Token contained within the encrypted ID Token. The Client MAY re-encrypt the signed ID token to the Authentication Server using a key that enables the server to decrypt the ID Token. In this case, the "sub" (subject) of the signed ID Token MUST be sent as the "kid" (Key ID) of the JWE. Encrypting content to Self-Issued OPs is currently only supported when the OP's JWK key type is "RSA" and the encryption algorithm used is "RSA1_5". claims OPTIONAL. This parameter is used to request that specific Claims be returned. The value is a JSON object, as specified in Section 2.6. registration OPTIONAL. This parameter is used by the Client to provide information about itself to a Self-Issued OP that would normally be provided to an OP during Dynamic Client Registration, as specified in Section 6.2.1. request OPTIONAL. Request Object value, as specified in Section 2.9. The Request Object MAY be encrypted in a JWE by the Client. In this case, the "sub" (subject) of a previously issued ID Token for this Client MUST be sent as the "kid" (Key ID) of the JWE. Encrypting content to Self-Issued OPs is currently only supported when the OP's JWK key type is "RSA" and the encryption algorithm used is "RSA1_5". Other parameters MAY be sent. Note that all Claims are returned in the ID Token. The entire URL MUST NOT exceed 2048 ASCII characters. Following is a non-normative example (with line wraps within values for display purposes only): HTTP/1.1 302 Found Location: openid:// ?response_type=id_token &client_id=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj registration=&%7B%22logo_uri%22%3A%22https%3A%2F%2F client.example.org%2Flogo.png%22%7D Sakimura, et al. [Page 63] OpenID Connect Messages 1.0 July 2013 6.4. Self-Issued OpenID Provider Response The Self-Issued OpenID Provider response is the same as the normal implicit flow response with the following refinements. Since it is an implicit flow response, the response parameters will be returned in the URL fragment component. 1. The "iss" (issuer) Claim Value is "https://self-issued.me". 2. A "sub_jwk" Claim is present, with its value being the public key value used to check the signature of the ID Token. 3. The "sub" (subject) Claim value is the base64url encoded SHA-256 hash of the concatenation of the octets of the UTF-8 representations of the base64url encoded key values in the "sub_jwk" Claim. When the "kty" value is "RSA", the key values "n" and "e" are concatenated in that order. When the "kty" value is "EC", the key values "crv", "x", and "y" are concatenated in that order. 4. No Access Token is returned for accessing a UserInfo Endpoint, so all Claims returned MUST be in the ID Token. 6.5. Self-Issued ID Token Validation If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. To validate the ID Token in the Authorization or Token Endpoint Response, the Client MUST do the following: 1. The Client MUST validate that the value of the "iss" (issuer) Claim is "https://self-isued.me". If "iss" contains a different value, the ID Token is not Self-Issued, and instead it MUST be validated according to Section 4.2. 2. The Client MUST validate that the "aud" (audience) Claim contains the value of the "redirect_uri" that the Client sent in the authentication request as an audience. 3. The Client MUST validate the signature of the ID Token according to JWS [JWS] using the algorithm specified in the "alg" parameter of the JWT header [JWT], using the key in the "sub_jwk" Claim; the key is a bare key in JWK format (not an X.509 certificate value). Sakimura, et al. [Page 64] OpenID Connect Messages 1.0 July 2013 4. The "alg" value SHOULD be the default of "RS256". It MAY also be "ES256". 5. The Client MUST validate that the "sub" (subject) Claim value is the base64url encoded SHA-256 hash of the concatenation of the octets of the UTF-8 representations of the base64url encoded key values in the "sub_jwk" Claim. When the "kty" value is "RSA", the key values "n" and "e" are concatenated in that order. When the "kty" value is "EC", the key values "crv", "x", and "y" are concatenated in that order. 6. The current time MUST be less than the value of the "exp" Claim (possibly allowing for some small leeway to account for clock skew). 7. The "iat" Claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is Client specific. 8. If a nonce value was sent in the Authorization Request, a "nonce" Claim MUST be present and its value of the checked to verify that it is the same value as the one that was sent in the Authorization Request. The Client SHOULD check the "nonce" value for replay attacks. The precise method for detecting replay attacks is Client specific. The following is a non-normative example of a base64url decoded Self- Issued ID Token (with line wraps within values for display purposes only): { "iss": "https://self-issued.me", "sub": "wBy8QvHbPzUnL0x63h13QqvUYcOur1X0cbQpPVRqX5k", "aud": "https://client.example.org/cb", "nonce": "n-0S6_WzA2Mj", "exp": 1311281970, "iat": 1311280970, "sub_jwk": { "kty":"RSA", "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", "e":"AQAB" } Sakimura, et al. [Page 65] OpenID Connect Messages 1.0 July 2013 } Sakimura, et al. [Page 66] OpenID Connect Messages 1.0 July 2013 7. String Operations 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: 1. Remove any JSON applied escaping to produce an array of Unicode code points. 2. Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or to the string it is to be compared against. 3. Comparisons between the two strings MUST be performed as a Unicode code point to code point equality comparison. 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. Sakimura, et al. [Page 67] OpenID Connect Messages 1.0 July 2013 8. Implementation Considerations This specification defines features used by both Relying Parties and OpenID Providers. Features that are mandatory to implement for Relying Parties are already described in the OpenID Connect Basic Client Profile 1.0 [OpenID.Basic] and OpenID Connect Implicit Client Profile 1.0 [OpenID.Implicit] specifications, and so are not discussed again here. It is expected that some OpenID Providers will require static, out- of-band configuration of RPs using them, whereas others will support dynamic usage by RPs without a pre-established relationship between them. For that reason, the mandatory-to-implement features for OPs are listed below in two groups: the first for all OPs and the second for "Dynamic" OpenID Providers. 8.1. Mandatory to Implement Features for All OpenID Providers All OpenID Providers MUST implement the following features defined in this specification. This list augments the set of features that are already listed elsewhere as being "REQUIRED" or are described with a "MUST", and so is not, by itself, a comprehensive set of implementation requirements for OPs. Signing ID Tokens with RSA SHA-256 OPs MUST support signing ID Tokens with the RSA SHA-256 algorithm (an "alg" value of "RS256"). Prompt Parameter OPs MUST support the "prompt" parameter, as defined in Section 2.1.1.1, including the specified user interface behaviors such as "none" and "login". Display Parameter OPs MUST support the "display" parameter, as defined in Section 2.1.1.1. (Note that the minimum level of support required for this parameter is simply to have its use not result in an error.) Preferred Locales OPs MUST support requests for preferred languages and scripts for the user interface and for Claims via the "ui_locales" and "claims_locales" request parameters, as defined in Section 2.1.1.1. (Note that the minimum level of support required for these parameters is simply to have their use not result in errors.) Authentication Time OPs MUST support returning the time at which the End-User authenticated via the "auth_time" Claim, as defined in Section 2.1.2.1. Sakimura, et al. [Page 68] OpenID Connect Messages 1.0 July 2013 Maximum Authentication Age OPs MUST support enforcing a maximum authentication age via the "max_age" parameter, as defined in Section 2.1.1.1. Authentication Context Class Reference OPs MUST support requests for specific Authentication Context Class Reference values via the "acr_values" parameter, as defined in Section 2.1.1.1. (Note that the minimum level of support required for this parameter is simply to have its use not result in an error.) 8.2. Mandatory to Implement Features for Dynamic OpenID Providers In addition to the features listed above, OpenID Providers supporting dynamic establishment of relationships with RPs that they do not have a pre-configured relationship with MUST also implement the following features defined in this and related specifications. Discovery These OPs MUST support Discovery, as defined in OpenID Connect Discovery 1.0 [OpenID.Discovery]. Dynamic Registration These OPs MUST support Dynamic Client Registration, as defined in OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. UserInfo Endpoint All dynamic OPs that issue Access Tokens MUST support the UserInfo Endpoint, as defined in Section 2.3. (Self- Issued OPs do not issue Access Tokens.) Public Keys Published as Bare Keys These OPs MUST publish their public keys as bare keys, rather than in X.509 format. Request URI These OPs MUST support requests made using a Request Object value that is retrieved from a Request URI that is provided with the "request_uri" parameter, as defined in Section 2.1.1.1. 8.3. Related Specifications 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: o OpenID Connect Standard 1.0 [OpenID.Standard] - Protocol binding for the full set of OpenID Connect messages These related OpenID Connect specifications MAY OPTIONALLY be used in combination with this specification to provide additional functionality: Sakimura, et al. [Page 69] OpenID Connect Messages 1.0 July 2013 o OpenID Connect Discovery 1.0 [OpenID.Discovery] - Dynamic discovery for user and Authorization Server endpoints and information o OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] - Dynamic registration of OpenID Connect Clients with OpenID Providers o OpenID Connect Basic Client Profile 1.0 [OpenID.Basic] - Protocol binding for a subset of the OpenID Connect Messages that is intended for use by basic Web-based Relying Parties using the OAuth "authorization_code" grant type. o OpenID Connect Implicit Client Profile 1.0 [OpenID.Implicit] - Protocol binding for a subset of the OpenID Connect Messages that is intended for use by basic Web-based Relying Parties using the OAuth implicit grant type. o OpenID Connect Session Management 1.0 [OpenID.Session] - Session management for OpenID Connect sessions Sakimura, et al. [Page 70] OpenID Connect Messages 1.0 July 2013 9. Security Considerations OAuth 2.0 Threat Model and Security Considerations [RFC6819] provides an extensive list of threats and controls that applies to this standard as well. ISO/IEC 29115 [ISO29115] also provides threats and controls that implementers need to take into account. In addition, this standard provides additional control measures listed below. 9.1. Request Disclosure If appropriate measures are not taken, a request might be disclosed to an attacker, posing security and privacy threats. In addition to what is stated in Section 5.1.1 of [RFC6819], this standard provides a way to provide the confidentiality of the request end to end through the use of "request" or "request_uri" parameters, where the content of the "request" is an encrypted JWT with the appropriate key and cipher. This protects even against a compromised User-Agent in the case of indirect request. 9.2. Server Masquerading A malicious Server might masquerade as the legitimate server using various means. To detect such an attack, the Client needs to authenticate the server. In addition to what is stated in Section 5.1.2 of [RFC6819], this standard provides a way to authenticate the Server through either the use of Signed or Encrypted JWTs with an appropriate key and cipher. 9.3. Token Manufacture/Modification An Attacker might 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 might modify the parseable token to extend the validity period; a Client might 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: 1. The token can be digitally signed by the OP. The Relying Party SHOULD validate the digital signature to verify that it was issued by a legitimate OP. 2. The token can be sent over a protected channel such as TLS. See Section 9.15 for more information on using TLS. In this specification, the token is always sent over a TLS protected Sakimura, et al. [Page 71] OpenID Connect Messages 1.0 July 2013 channel. Note however, that this measure is only a defense against third party attackers and is not applicable to the case where the Client is the attacker. 9.4. Server Response Disclosure The server response might 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: 1. Using the "code" response type. The response is sent over a TLS protected channel, where the Client is authenticated by the "client_id" and "client_secret". 2. For other response types, the signed response can be encrypted with the Client's public key or a shared secret as an encrypted JWT with an appropriate key and cipher. 9.5. Server Response Repudiation A response might 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. 9.6. Request Repudiation Since it is possible for a compromised or malicious Client to send a request to the wrong party, a Client that was authenticated using only a bearer token can repudiate any transaction. To mitigate this threat, the Server MAY require that the request be digitally signed by the Client using a key that supports non- repudiation. The Server SHOULD validate the digital signature to verify that it was issued by a legitimate Client and the integrity is intact. Sakimura, et al. [Page 72] OpenID Connect Messages 1.0 July 2013 9.7. Access Token Redirect 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. 9.8. Token Reuse An Attacker attempts to use a one-time use token such as an Authorization Code that has already been used once with the intended Resource. To mitigate this threat, the token SHOULD include a timestamp and a short validity lifetime. The Relying Party then checks the timestamp and lifetime values to ensure that the token is currently valid. Alternatively, the server MAY record the state of the use of the token and check the status for each request. 9.9. Eavesdropping or Leaking Authorization Codes (Secondary Authenticator Capture) In addition to the attack patterns described in Section 4.4.1.1 of [RFC6819], an Authorization Code can be captured in the User-Agent where the TLS session is terminated if the User-Agent is infected by malware. However, capturing it is not useful as long as the profile uses either Client authentication or an encrypted response. 9.10. Token Substitution Token Substitution is a class of attacks in which a malicious user swaps various tokens, including swapping an Authorization Code for a legitimate user with another token that the attacker has. One means of accomplishing this is for the attacker to copy a token out one session and use it in an HTTP message for a different session, which is easy to do when the token is available to the browser; this is known as the "cut and paste" attack. The implicit flow of OAuth 2.0 [RFC6749] is not designed to mitigate this risk. In Section 10.16, it normatively requires that any use of the authorization process as a form of delegated End-User authentication to the Client MUST NOT use the implicit flow without employing additional security mechanisms that enable the Client to determine whether the Access Token was issued for its use. Sakimura, et al. [Page 73] OpenID Connect Messages 1.0 July 2013 In OpenID Connect, this is mitigated through mechanisms provided through the ID Token. The ID Token is a signed security token that provides Claims such as "iss" (issuer), "sub" (subject), "aud" (audience), "azp" (authorized party), "at_hash" (access token hash), and "c_hash" (code hash). Using the ID Token, the Client is capable of detecting the Token Substitution Attack. The "c_hash" in the ID Token enables Clients to prevent "code" substitution. Also, a malicious user may attempt to impersonate a more privileged user by subverting the communication channel between the Authorization Endpoint and Client, or the Token Endpoint and Client, for example by swapping the "code" or reordering the messages, to convince the Token Endpoint that the attacker's authorization grant corresponds to a grant sent on behalf of a more privileged user. For HTTP bindings such as OpenID Connect Standard 1.0, the responses to Token Requests are bound to the corresponding requests by message order in HTTP, as both the response containing the token and requests are protected by TLS, which will detect and prevent packet reordering. When designing another binding of OpenID Connect Messages to a protocol incapable of strongly binding Token Endpoint requests to responses, additional mechanisms to address this issue MUST be utilized. One such mechanism could be to include an ID Token with a "c_hash" Claim in the token request and response. 9.11. Timing Attack A timing attack allows the attacker to obtain an unnecessary large amount of information through the elapsed time differences in the code paths taken by successful and unsuccessful decryption operations or successful and unsuccessful signature validation of a message. It can be used to reduce the effective key length of the cipher used. Implementations SHOULD NOT terminate the validation process at the instant of the finding an error but SHOULD continue running until all the octets have been processed to avoid this attack. 9.12. Other Crypto Related Attacks There are various crypto related attacks possible depending on the method used for encryption and signature / integrity checking. Implementers need to consult the Security Considerations for the JWT [JWT] specification and specifications that it references to avoid the vulnerabilities identified in these specifications. Sakimura, et al. [Page 74] OpenID Connect Messages 1.0 July 2013 9.13. Signing and Encryption Order 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. 9.14. Issuer Identifier OpenID Connect supports multiple issuers per Host and Port combination. The issuer returned by discovery MUST exactly match the value of "iss" in the ID Token. OpenID Connect treats the path component of any URI as part of the user identifier. For instance, the subject "1234" with an issuer of "https://example.com" is not equivalent to the subject "1234" with an issuer of "https://example.com/sales". It is RECOMMENDED that only a single issuer per host be used. 9.15. TLS Requirements 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] 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] is the most widely deployed version, and will give the broadest interoperability. To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection. Whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125 [RFC6125]. 9.16. Lifetimes of Access Tokens and Refresh Tokens Access Token grants are not revocable by the Authorization Server. Access Token grant lifetimes SHOULD be kept to single use or very short lifetimes. If access to the UserInfo Endpoint or other protected resources is required, a Refresh Token SHOULD be used. The Client MAY then exchange the Refresh Token at the Token Endpoint for a fresh short- lived Access Token that can be used to access the resource. Sakimura, et al. [Page 75] OpenID Connect Messages 1.0 July 2013 The Authorization Server SHOULD clearly identify long-term grants to the User during Authorization. The Authorization Server SHOULD provide a mechanism for the End-User to revoke Refresh Tokens granted to a Client. 9.17. Symmetric Key Entropy In Section 3.3 and Section 3.4, keys are derived from the "client_secret" value. Thus, when used with symmetric signing or encryption operations, "client_secret" values MUST contain sufficient entropy to generate cryptographically strong keys. Also, "client_secret" values MUST also contain at least the minimum of number of octets required for MAC keys for the particular algorithm used. So for instance, for "HS256", the "client_secret" value MUST contain at least 8 octets (and almost certainly SHOULD contain more, since "client_secret" values are likely to use a restricted alphabet. 9.18. Need for Signed Requests In some situations, Clients might need to use signed requests to ensure that the desired request parameters are delivered to the OP without having been tampered with. For instance, the "max_age" and "acr_values" provide more assurance about the nature of the authentication performed when delivered in signed requests. 9.19. Need for Encrypted Requests In some situations, knowing the contents of an OpenID Connect request can, in and of itself, reveal sensitive information about the End- User. For instance, knowing that the Client is requesting a particular Claim or that it is requesting that a particular authentication method be used can reveal sensitive information about the End-User. OpenID Connect enables requests to be encrypted to the OpenID Provider to prevent such potentially sensitive information from being revealed. Sakimura, et al. [Page 76] OpenID Connect Messages 1.0 July 2013 10. Privacy Considerations 10.1. Personally Identifiable Information The UserInfo Response typically contains Personally Identifiable Information (PII). As such, End-User consent for the release of the information for the specified purpose SHOULD be obtained at or prior to the authorization time in accordance with relevant regulations. The purpose of use is typically registered in association with the "redirect_uris". Only necessary UserInfo data should be stored at the Client and the Client SHOULD associate the received data with the purpose of use statement. 10.2. Data Access Monitoring 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. 10.3. Correlation To protect the End-User from a possible correlation among Clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the "sub" (subject) SHOULD be considered. 10.4. Offline Access Offline access enables access to Claims when the user is not present, posing greater privacy risk than the Claims transfer when the user is present. Therefore, it is prudent to obtain explicit consent for offline access to resources. This specification mandates the use of the "prompt" parameter to obtain consent unless it is a priori known that the request complies with the conditions for processing in each jurisdiction. When an Access Token is returned in the front channel, there is a greater risk of it being exposed to an attacker, who could later use it to access the UserInfo endpoint. If the Access Token does not enable offline access and the server can differentiate whether the Client request has been made offline or online, the risk will be substantially reduced. Therefore, this specification mandates ignoring the offline access request when the Access Token is transmitted in the front channel. Note that differentiating between online and offline access from the server can be difficult especially for native clients. The server may well have to rely on heuristics. Also, the risk of exposure for the Access Token delivered in the front channel for the response types of "code token" and "token" is Sakimura, et al. [Page 77] OpenID Connect Messages 1.0 July 2013 the same. Thus, the implementations should be prepared to detect the channel from which the Access Token was issued and deny offline access if the token was issued in the front channel. Note that although these provisions require an explicit consent dialogue through the "prompt" parameter, the mere fact that the user pressed an "accept" button etc., might not constitute a valid consent. Developers should be aware that for the act of consent to be valid, typically, the impact of the terms have to be understood by the End-User, the consent must be freely given and not forced (i.e., other options have to be available), and the terms must fair and equitable. In general, it is advisable for the service to follow the required privacy principles in each jurisdiction and rely on other conditions of processing than simply explicit consent, as online self-service "explicit consent" often does not form a valid consent in some jurisdictions. Sakimura, et al. [Page 78] OpenID Connect Messages 1.0 July 2013 11. IANA Considerations 11.1. JSON Web Token Claims Registry This specification registers the Claims defined in Section 2.5 and Section 2.1.2.1 in the IANA JSON Web Token Claims registry defined in [JWT]. 11.1.1. Registry Contents o Claim Name: "name" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "given_name" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "family_name" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "middle_name" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "nickname" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "preferred_username" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "profile" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "picture" Sakimura, et al. [Page 79] OpenID Connect Messages 1.0 July 2013 o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "website" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "email" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "email_verified" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "gender" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "birthdate" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "zoneinfo" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "locale" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "phone_number" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "address" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Sakimura, et al. [Page 80] OpenID Connect Messages 1.0 July 2013 o Specification Document(s): Section 2.5 of this document o Claim Name: "updated_at" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.5 of this document o Claim Name: "azp" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "nonce" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "auth_time" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "at_hash" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "c_hash" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "acr" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "amr" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document o Claim Name: "sub_jwk" o Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification Document(s): Section 2.1.2.1 of this document Sakimura, et al. [Page 81] OpenID Connect Messages 1.0 July 2013 11.2. OAuth Parameters Registry This specification registers the following parameters in the IANA OAuth Parameters registry defined in RFC 6749 [RFC6749]. 11.2.1. Registry Contents o Parameter name: "nonce" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "display" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "prompt" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "max_age" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "ui_locales" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "claims_locales" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Sakimura, et al. [Page 82] OpenID Connect Messages 1.0 July 2013 o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "id_token_hint" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "login_hint" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "acr_values" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "claims" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "registration" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "request" o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "request_uri" Sakimura, et al. [Page 83] OpenID Connect Messages 1.0 July 2013 o Parameter usage location: Authorization Request o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.1.1 of this document o Related information: None o Parameter name: "id_token" o Parameter usage location: Authorization Response, Access Token Response o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.2.3 of this document o Related information: None 11.3. OAuth Extensions Error Registry This specification registers the following errors in the IANA OAuth Extensions Error registry defined in RFC 6749 [RFC6749]. 11.3.1. Registry Contents o Error name: "interaction_required" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.3 of this document o Error name: "login_required" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.3 of this document o Error name: "session_selection_required" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.3 of this document o Error name: "consent_required" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net Sakimura, et al. [Page 84] OpenID Connect Messages 1.0 July 2013 o Specification document(s): Section 2.1.3 of this document o Error name: "invalid_request_uri" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.3 of this document o Error name: "invalid_request_object" o Error usage location: Authorization Endpoint o Related protocol extension: OpenID Connect o Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net o Specification document(s): Section 2.1.3 of this document Sakimura, et al. [Page 85] OpenID Connect Messages 1.0 July 2013 12. References 12.1. Normative References [E.164] International Telecommunication Union, "E.164: The international public telecommunication numbering plan", 2010. [IANA.Language] Internet Assigned Numbers Authority (IANA), "Language Subtag Registry", 2005. [ISO29115] International Organization for Standardization, "ISO/IEC 29115:2013 -- Information technology - Security techniques - Entity authentication assurance framework", ISO/ IEC 29115, March 2013. [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), May 2013. [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web Encryption (JWE)", draft-ietf-jose-json-web-encryption (work in progress), May 2013. [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-key (work in progress), May 2013. [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", draft-ietf-jose-json-web-signature (work in progress), May 2013. Sakimura, et al. [Page 86] OpenID Connect Messages 1.0 July 2013 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", draft-ietf-oauth-json-web-token (work in progress), May 2013. [OAuth.Assertions] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, "Assertion Framework for OAuth 2.0", draft-ietf-oauth-assertions (work in progress), March 2013. [OAuth.JWT] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0", draft-ietf-oauth-jwt-bearer (work in progress), March 2013. [OAuth.Responses] de Medeiros, B., Ed., Scurtescu, M., and P. Tarjan, "OAuth 2.0 Multiple Response Type Encoding Practices", June 2013. [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", July 2013. [OpenID.Registration] Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0", July 2013. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", RFC 3966, December 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. Sakimura, et al. [Page 87] OpenID Connect Messages 1.0 July 2013 [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, October 2008. [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009. [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. [RFC6711] Johansson, L., "An IANA Registry for Level of Assurance (LoA) Profiles", RFC 6711, August 2012. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, January 2013. [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode Normalization Forms", Unicode Standard Annex 15, 09 2009. [zoneinfo] Public Domain, "The tz database", June 2011. 12.2. Informative References [OpenID.2.0] OpenID Foundation, "OpenID Authentication 2.0", December 2007. [OpenID.Basic] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Basic Client Profile 1.0", July 2013. Sakimura, et al. [Page 88] OpenID Connect Messages 1.0 July 2013 [OpenID.Implicit] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Implicit Client Profile 1.0", July 2013. [OpenID.PAPE] Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, "OpenID Provider Authentication Policy Extension 1.0", December 2008. [OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Session Management 1.0", July 2013. [OpenID.Standard] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Standard 1.0", July 2013. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 4949, August 2007. [X.1252] International Telecommunication Union, "ITU-T Recommendation X.1252 -- Cyberspace security -- Identity management -- Baseline identity management terms and definitions", ITU-T X.1252, November 2010. Sakimura, et al. [Page 89] OpenID Connect Messages 1.0 July 2013 Appendix A. Acknowledgements As a successor version of OpenID, this specification heavily relies on ideas explored in OpenID Authentication 2.0 [OpenID.2.0]. Please refer to Appendix C of OpenID Authentication 2.0 for the full list of the contributors for that specification. In addition, the OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification. Naveen Agarwal (naa@google.com), Google Amanda Anganes (aanganes@mitre.org), Mitre Casper Biering (cb@peercraft.com), Peercraft John Bradley (ve7jtb@ve7jtb.com), Ping Identity Tim Bray (tbray@textuality.com), Google Johnny Bufu (jbufu@janrain.com), Janrain Brian Campbell (bcampbell@pingidentity.com), Ping Identity Breno de Medeiros (breno@gmail.com), Google Pamela Dingle (pdingle@pingidentity.com), Ping Identity Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services George Fletcher (george.fletcher@corp.aol.com), AOL Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc. Edmund Jay (ejay@mgi1.com), Illumila Michael B. Jones (mbj@microsoft.com), Microsoft Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom Nov Matake (nov@matake.jp), Independent Chuck Mortimore (cmortimore@salesforce.com), Salesforce Sakimura, et al. [Page 90] OpenID Connect Messages 1.0 July 2013 Anthony Nadalin (tonynad@microsoft.com), Microsoft Hideki Nara (hdknr@ic-tact.co.jp), Tact Communications Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom David Recordon (dr@fb.com), Facebook Justin Richer (jricher@mitre.org), Mitre Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd. Luke Shepard (lshepard@fb.com), Facebook Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET Paul Tarjan (pt@fb.com), Facebook Sakimura, et al. [Page 91] OpenID Connect Messages 1.0 July 2013 Appendix B. Notices Copyright (c) 2013 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non- infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification. Sakimura, et al. [Page 92] OpenID Connect Messages 1.0 July 2013 Appendix C. Document History [[ To be removed from the final specification ]] -20 o Fixed #847 - Corrected type of "updated_at" to number. o Fixed #840 - Provided a better description of the Token Substitution attack. o Fixed #844 - Provided a better Authentication definition. o Fixed #845 - Added a reference to ITU-T X.1252. o Said that we're using the terms "validate" and "verify" as defined by RFC 4949. o Added Privacy Considerations for Offline Access. o Stated that "redirect_uri" matches must be exact, with matching performed as described in Section 6.2.1 of RFC 3986 (Simple String Comparison). o Fixed #854 - Clarified that the "acr_values" values are in order of preference and that "acr_values" requests the "acr" Claim as a Voluntary Claim. o Fixed #851 - Clarified that "none" is not an acceptable ID Token signature algorithm. o Fixed #858 - Incorporated elements of the Issuer Identifier definition into the "iss" Claim description. o Fixed #859 - Added IMPORTANT NOTE TO READERS about the terminology definitions being a normative part of the specification. -19 o Stated that OPs should perform no other nonce processing than returning "nonce" values received in requests as claims in issued ID Tokens. o Stated that sufficient entropy must be present in "nonce" values to prevent attackers from guessing values. o Required that the "aud" value in an ID Token issued from a Refresh Token must match that in the originally issued ID Token. Sakimura, et al. [Page 93] OpenID Connect Messages 1.0 July 2013 o Stated that the Authorization Server need not be listed as an audience of the ID Token when it is used as an "id_token_hint" value. o Restricted the meaning of the "azp" (authorized party) Claim to simply be the single party to which the ID Token was issued. o Changed the requirement to support the UserInfo endpoint from applying to all OpenID Providers to only applying to dynamic OpenID Providers. o Changed from using the term "byte" to either "octet" or "character". o Fixed #835 - Clarified requirements on using "value" and "values" qualifiers when requesting specific values for individual claims. o Removed definition of the "x5c" JWK key member since it is now defined in the JWK specification. o Stated that the JWS Compact Serialization and the JWE Compact Serialization are always used for JWS and JWE data structures. -18 o Replaced the "PKIX" JWK key type with the "x5c" JWK key member. (This will be removed from this specification once this member is defined in the JWK specification.) o Fixed #820 - Removed assumption that Clients that want encrypted responses also sign requests. o Fixed #821 - Moved definition of JSON Serialization to where it's used. o Fixed #825 - Replaced "updated_time", which used the RFC 3339 textual time format, with "updated_at", using the numeric time format used by "iat", etc. o Fixed #826 - Clarified "response_type" values for which an "offline_access" request must be ignored. o Fixed #827 - Added "request_uri_not_supported" error code. o Fixed #828 - Stated that an extension would be needed if a key wrapping key of greater than 256 bits for symmetric encryption needs to be derived. Sakimura, et al. [Page 94] OpenID Connect Messages 1.0 July 2013 o Fixed #829 - Stated that additional scope values can be defined and used and that scope values that are not understood should be ignored. o Fixed #831 - Stated that JWS and JWE header parameters used to communicate key values and key references should not be used in ID Tokens, since these are communicated in advance using Discovery and Registration parameters. o Fixed #712 and #830 - Clarified the "azp" description and made "azp" multi-valued, like "aud". -17 o Fixed #802 - Clarified recommendations and responsibilities for producing and consuming Claims with and without language tags. o Fixed #797 - Clarified the intended semantics of e-mail verification and that the precise verification rules are context- specific. o Fixed #806 - Added "phone_number_verified" Claim. o Fixed #800 - Specified that phone number extensions are to be represented using RFC 3966 extension syntax. o Fixed #795 - Specified that e-mail addresses must conform to the RFC 5322 addr-spec syntax. o Fixed #808 - Specified that phone numbers may be used as "login_hint" values. o Fixed #801 - Removed "schema" and "id" parameters to UserInfo Endpoint. Also fixed related issue #791 - Removed "invalid_schema" error. o Fixed #793, #796, and #799 - Allow name Claims to contain multiple space-separated names. o Fixed #794 - Required "picture" to refer to an image file that is a picture of the End-User. o Fixed #805 - Placed requirements on use of the "sub" Claim when Aggregated Claims and Distributed Claims are used, to prevent unintended correlations. o Fixed #811 - Specify that language tag components should be spelled using the character cases registered in the IANA Language Sakimura, et al. [Page 95] OpenID Connect Messages 1.0 July 2013 Subtag Registry. o Fixed #812 - Clarified that language tag values used need not be unnecessarily specific. o Fixed #816 - Changed "must understand" language to "MUST be ignored if not understood". o Added section on using Additional Claims. -16 o Fixed #709 - OpenID Request Object - "registration" in non-Self- Issued case. o Fixed #711 - Awkward phrase "The following Claims are REQUIRED and OPTIONAL". o Fixed #712 - "azp" definition clarification. o Fixed #713 - Explicitly require "sub" claim to be returned from UserInfo endpoint. o Fixed #715 - Delete "profile" from request object example. o Fixed #729 - ITU-T X.1254 | ISO/IEC 29115 now separate. o Fixed #722 - Text on "id_token_hint" needs to be clarified. o Fixed #718 - Text on re-encrypting should be clearer. o Fixed #738 - Behavior when "openid" scope is omitted. o Fixed #714 - Clarified text specifying response_type behaviors, including prohibiting the use of the "token" response_type, since it returns no ID Token. o Added statement "whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125 [RFC6125]" to TLS Requirements section in Security Considerations. o State that when any validations fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. o Fixed #742 - Added new "ui_locales" parameter. Sakimura, et al. [Page 96] OpenID Connect Messages 1.0 July 2013 o Fixed #743 - Promoted "preferred_locales" to being a top-level parameter. Also renamed it to "claims_locales" to disambiguate it from the new "ui_locales" parameter. o Fixed #744 - Promoted "max_age" to being a top-level parameter. o Fixed #748 - Promoted "claims" to being a top-level parameter separate from the OpenID Request Object. o Fixed #765 - Created "acr_values" top-level request parameter and changed "default_acr" registration parameter to "default_acr_values". o Fixed #761 - client_secret as the HMAC key and #762 - client_secret to key. We now use the phrase "the bytes of the UTF-8 representation of the "client_secret" value". Also added security considerations about symmetric key entropy. o Fixed #597 - Changed representation of omitted year in "birthdate" from "9999" to "0000". o Fixed #769 - Added Claim Type identifiers and definition. o Fixed #773 - Added "request_uris" registration parameter to pre- register "request_uri" values. Also clarified that the referenced resource contents may be cached. o Fixed #748 - Changed OpenID Request Object processing rules so that the Request Object parameters are combined with those passed as OAuth 2.0 parameters, with the Request Object parameters taking precedence. This enables fixed parameters to be passed in pre- signed, possibly pre-encrypted, and cached Request Objects, with parameters that will vary per request like "state" and "nonce" being passed as OAuth 2.0 parameters. This is particularly important now that "request_uri" values can be pre-registered. o Fixed #765 - Added Security Considerations about the need for signed and encrypted requests. o Fixed #763 - OPs MUST treat the inability to return an Essential requested "acr" Claim Value as a failed authentication attempt. o Fixed #739 - Added values for Self-Issued registration. o Fixed #779 - Parameters missing from IANA Considerations. o Fixed #760 - Added rationale for "request_uri" usage. Sakimura, et al. [Page 97] OpenID Connect Messages 1.0 July 2013 o Fixed #782 - Changed uses of "_url" in identifiers to "_uri". o Fixed #703 - Added the PKIX JWK key type (and example) for X.509 certificates and consolidated the "x509_uri", "x509_encryption_uri", and "jwk_encryption_uri" parameters into a combined "jwk_uri" parameter. Also Fixed #704 - Provided suggested guidance about how to do key rotation of asymmetric keys for both signing and encryption using "jwk_uri". o Made UserInfo Endpoint MTI to support for all OPs that issue Access Tokens. o Fixed #719 - Moved message definitions for Self-Issued OPs to the Messages spec. o Fixed #671 - Specified that an Access Token must be requested when Claims are requested from the UserInfo endpoint. o Fixed #717 - Parameters and values should be distinguished more clearly. o Fixed #786 - Changed the name of "jwk_uri" to "jwks_uri". o Clarified when the "http" scheme can and can not be used in "redirect_uri" values. o Fixed #748 - Defined MTI features for OPs. Also added "request_not_supported" error code. o Fixed #784 - Required publication of public keys as bare keys. o Fixed #785 - Enabled scope values to be used to request Claims when using the "response_type" value "id_token" (for which no Access Token is issued). o Fixed #787 - Don't prohibit returning an ID Token from the Token Endpoint when grant types other than "authorization_code" are used. o Fixed #710 - Gave an example of how requesting Claims with scope values is equivalent to requesting them with the "claims" request parameter. o Stated that the "azp" Claim is only needed when the party requesting the ID Token is different than the audience of the ID Token. Sakimura, et al. [Page 98] OpenID Connect Messages 1.0 July 2013 o Fixed #788 - Renamed "OpenID Request Object" to "Request Object". o Use legal "acr" values in examples. o Fixed #789 - Added "amr" (authentication methods references) Claim. o Fixed #790 - Removed "MUST understand" text about request parameters, since OAuth requires that unrecognized parameters MUST be ignored. o Added requirements for ID Tokens returned as a result of a token refresh request. -15 o Fixed #671 - Section 2.1.1 added test to require client to request an access token for the UserInfo Endpoint if requesting the default scopes. o Fixed #637 - Removed requirement for hash of at_token and code to be SHA2 in Section 2.1.2.1 and Section 5.2. o Fixes #620 - Update Section 2.1.2 and Section 2.2.3 to allow for other token types, but make bearer mandatory to support for clients. o Fixes #684 Removed error response in redirect to client if the redirect_uri is wrong to align with OAuth. o Fixed #695 - Contradictory OPTIONAL MUSTs in JWT Client Authentication. o Fixed #600 - Register Connect Claims in JWT Claims Registry. o Made the OpenID Foundation Artifact Binding Working Group the change controller for the values registered with IANA. o Moved OAuth error registrations from Standard to Messages since the errors are defined in Messages and not in Standard. o Use "OpenID Connect" as the "Related protocol extension" value in OAuth Extensions Error registry entries. o Fixed #657 - Section 2.1.1 Specify the sub is used as the kid if the request object or id_token_hint is encrypted. Sakimura, et al. [Page 99] OpenID Connect Messages 1.0 July 2013 o Added Implementation Considerations section on Mandatory to Implement (MTI) features, per issue #604. o Specified that dynamic OPs must publish their public keys in X.509 format, per issue #633. o Fixed #648 - Specific response types now used in place of "implicit flow" and "code flow". The wording for at_hash and c_hash is now clearer. o Fixed #698 - Inconsistent use of articles. o Fixed #699 - OpenID Provider (OP) definition repetitive. o Fixed #701 - Mention of SWD without a reference. o Fixed #700 - Incomplete specification names. o Fixed #702 - Make scopes a reference to the scopes section. o Fixed #702 - Consent is for claims - not scopes. o Fixed up Scopes section to make it clear that claims requested by the scopes are voluntary. o OAuth Threat Model is now RFC 6819. o Renamed the "user_jwk" Claim to "sub_jwk", paralleling the change from "user_id" to "sub". o Defined and registered the "sub_jwk" claim. -14 o Fixed #687 - Inconsistency between "user_id" and "prn" claims. The fix changed these names: user_id -> sub, user_id_types_supported -> subject_types_supported, user_id_type -> subject_type, and prn -> sub. o Fixed #689 - Track JWT change that allows JWTs to have multiple audiences. o Fixed #660 - Clarified that returning the "sub" value from the UserInfo endpoint is mandatory. o Fixed #636 - ID Token authorized party claim. Sakimura, et al. [Page 100] OpenID Connect Messages 1.0 July 2013 o Fixed #539 - Add scope for offline access. o Fixed #690 - Inconsistent language in requirement of id_token response_type. o Clarified that "jwk_uri" and "jwk_encryption_uri" refer to documents containing JWK Sets - not single JWK keys. o Fixed #689 - Add caution about multiple audiences and azp. o Fixed #692 typos. -13 o Fixed #588 - Messages: Token lifetime not privacy consideration o Fixed #597 - Messages: Changed claim name birthday to birthdate and made the format ISO 8601:2004 o Fixed #606 - Messages - 2.1.1. ID Token - acr missing the type. Type String. o Fixed #617 - Messages - 1.2 Terminology: id_token. Added sentence that it can contain other claims. o Fixed #608 - Messages - Request ID Token and Response ID Token. Moved response ID Token from section 2.1 to the response section. o Fixed #543 - Messages - Security Consideration. Added ref to X.1254 | ISO 29115. o Fixed #611 - Messages - Changed the default test to indicate that the value of auth_time needs to be essential o Fixed #646 - Messages - Add login_hint as an OAuth parameter and put in example in request object o Fixed #607 - Messages - add example decoded id_token. o Fixed #658 - Messages - 2.1.1 "id_token" name crash, id_token renamed to id_token_hint o Fixed #612 - Messages - 4.1 change request_object_algs_supported to be RS256 o Fixed #662 - Messages - changed id_token_signed_response_algs to id_token_signed_response_alg in 5.1 Sakimura, et al. [Page 101] OpenID Connect Messages 1.0 July 2013 o Fixed #678 - Messages - Changed 5.1.3 terminology of acr to reflect essential vs. required and fixed example o Fixed #679 - Messages - update reference to LoA registry from ID to RFC6711. o Fixed #614 - Discovery - 3.2 Distinguishing between signature and integrity parameters for HMAC algorithms. This fix tracks the parameter changes made to the JWE spec in draft-ietf-jose-json-web-encryption-06. It deletes the parameters {userinfo,id_token}_encrypted_response_int. It replaces the parameters {userinfo,id_token,request_object,token_endpoint}_algs_supported with {userinfo,id_token,request_object,token_endpoint}_signing_alg _values_supported and {userinfo,id_token,request_object,token_endp oint}_encryption_{alg,enc}_values_supported. o Fixed #673 - Registration 2.1: Rename require_signed_request_object to request_object_alg. The actual change was to rename require_signed_request_object to request_object_signing_alg, following the naming convention used in the resolution to issue #614. o Fixed #666 - JWS signature validation vs. verification. o Referenced OAuth 2.0 RFCs -- RFC 6749 and RFC 6750. o Fixed #663 Sec 5.2 to allow for non SHA2 HMAC algs -12 o Added "preferred_username" claim under "profile" scope o Added section on claim stability o Changed "request_uri" to "request_uri" in Section 2.1.2.1 -11 o Removed "claims_in_id_token" scope value, per decision on June 15, 2012 special working group call -10 o Changed "verified" to "email_verified", per issue #564 o Added scope value "claims_in_id_token" as a switch to indicate that the UserInfo claims should be returned in the ID Token, per Sakimura, et al. [Page 102] OpenID Connect Messages 1.0 July 2013 issue #561 o Removed "optional" claim request parameter and added "essential" claim request parameter, per issue #577. We changed terminology from "optional" to "voluntary" and "required" to "essential" to better match privacy policy requirements. o Removed Check ID Endpoint, per issue #570 o Added PAPE Reference to the Informative References, per issue #574 o Added "id_token" response type as being MTI for OpenID Providers o Specified that parameters present in both the OpenID Request Object and the OAuth 2.0 Authorization Request MUST exactly match, per issue #575 o Changed OpenID Request Object from being specified as a JWT to being specified as a JWS signed base64url encoded JSON object, per issue #592 o Changed default ID Token signing algorithm to RS256, per issue #571 o Changed default OpenID Request Object signing algorithm to RS256, per issue #571 o Made use of the nonce REQUIRED when using the implicit flow and OPTIONAL when using the code flow, per issue #569 o Changed client.example.com to client.example.org, per issue #251 o Listed author of ISO29115 as "International Telecommunication Union and International Organization for Standardization", per issue #589 o Added method of calculating signing and encryption keys for symmetric algorithms, per issue #578 o Use standards track versions of JSON Web Token (JWT) and OAuth JWT Bearer Token Profiles specs (draft-ietf-oauth-json-web-token and draft-ietf-oauth-oauth-jwt-bearer) -09 o Added error interaction_required and removed user_mismatched, per issue #523 Sakimura, et al. [Page 103] OpenID Connect Messages 1.0 July 2013 o Changed invalid_request_redirect_uri to invalid_redirect_uri, per issue #553 o Removed "embedded" display type, since its semantics were not well defined, per issue #514 o Added optional id_token to authorization request parameters, per issue #535 o Now requested claims add to those requested with scope values, rather than replacing them, per issue #547 o Make changes to allow path in the issuer_identifier, per issue #513 o Make changes to userinfo_encrypted_response_* and id_token_encrypted_response_* to match registration o Add hash and hash check of access_token and code to id_token, per issue #510 o Updated Notices o Updated References -08 o Updated the version number and date o Fixed #551 Sec 2.1.2.1 to clarify the OpenID Request Object MUST NOT include "request" nor "request_uri" o Fixed #540 Sec 2.2.3 id_token MUST NOT be returned for grant_type=refresh o Fixed #542 Sec 2.1.2.1 required fields for request object to match Standard o Fixed Sec 2.2.1 to refer to client_secret value rather than Client Password o Fixed Sec 4.2, 4.3, 4.4 to replace requirement for using x.509 keyuse extension o Added reference to RFC2459 o Fixed Sec 2.1.1.1.1 added rationale for sector_identifier_url from registration Sakimura, et al. [Page 104] OpenID Connect Messages 1.0 July 2013 o Fixed Sec 2.1.1.1.1 added examples of other ways to generate PPID o Added iat as a required claim in ID Tokens o Enumerated claims requested by the "profile" scope value o Fixed Sec 2.1.2 response_type references standard rather than repeating values that are binding specific o Fixed Sec 2.1.2 remove outdated language about openid scope requiring id_token to be returned with token response_type -07 o Removed definition and usage for assertion and claim object o Consistent use of End-User o Removed 'format' from userinfo and id_token object of the OpenID Request Object o email scope allows access to the 'verified' claim o ID Token 'audience' claim MUST be "client_id" o Rename artifact to authorization code o Removed language pertaining to custom userinfo schemas o Check ID Endpoint returns only JSON o Updated Check ID Response verification o Remove 'audience' parameter from Authorization Request o Moved display=none to prompt=none o Added additional display parameter options o Moved IANA considerations to Standard o Added error codes to Authorization Endpoint o Added client authentication section regarding various supported client authentication schemes and their validation. This includes symmetric and asymmetric authentication, JWT Bearer Token Profiles, OAuth 2.0 Assertion Profile Sakimura, et al. [Page 105] OpenID Connect Messages 1.0 July 2013 o Updated Check ID Response verification o Added 'auth_time' to ID Token o Added validation for request object encryption and signature o Added explanation for user_id type and calculating pairwise identifiers o Added steps for signature and validation and encryption and decryption o Added verification of issuer identifier o Redefined 'nonce' in Authorization Request. Changed to REQUIRED parameter. o Changed usage of the word "approval" to "consent" o Use RFC 6125 to verify TLS endpoints o ID Token MUST be JWT o Access Tokens should include an audience claim for the Resource Server o Updated Security Considerations o OpenID Request Object parameters takes precedence over the same parameters in the Authorization Request o Allow other gender strings in UserInfo schema o Changed UserInfo claim 'locale' to 'preferred_locales' and changed it to be a list of values o Changed UserInfo claim 'user_id' to REQUIRED. Added requirement to compare user_id from userinfo endpoint to id_token o RECOMMENDED E.164 format for UserInfo 'phone_number' claim o Changed UserInfo Error Response to augment and return OAuth 2.0 Bearer Token Error Response o Expanded section regarding UserInfo 'address' claim o Added Privacy considerations Sakimura, et al. [Page 106] OpenID Connect Messages 1.0 July 2013 o Added rational for signing then encrypting added to security considerations o Added section about string comparison rules needed o The Authorization Server MUST understand all the request parameters except for any unsupported claims. o Make openid scope provide user_id from userinfo endpoint o Added explanation of select_account o Check ID Endpoint uses ID Token as Access Token according to Bearer Token spec o Clients MUST verify "client_id" in ID Token o Bumped version + date o Update John Bradley email and affiliation for Implementer's Draft o Removed invalid_authorization_code, invalid_id_token error codes o Section 2.3 client MUST NOT send encrypted JWT to the Check ID Endpoint o Section 2.1.2.1.2 Added user_id claim and moved iso29115 to claims element of id_token member o Defined Authentication Context, Authentication Context Class Reference (acr), replaced iso29115 with acr. o Corrected instances of x509_url_encryption to x509_encryption_url and jwk_url_encryption to jwk_encryption_url -06 o Changed section 3.1.4.1 to say the errors are returned as defined by the response type not always as query parameters. per ticket #174. o Bumped version + date. o Fixed section 3.3.3 to refer to errors in Bearer Token. o Fixed 3.1.3 to ref the other response types ticket #173. Sakimura, et al. [Page 107] OpenID Connect Messages 1.0 July 2013 o Included reference to multiple response types. o Fixed 3.1.2.1 to indicate default Claims in id_token. o Fixed section 3.2.2 to reference the access token response from the token endpoint 4.1.4. o Fixed section 3.2.1 to include refresh tokens. o Fixed section 3.1.1 to be clear on JWT being the token format per ticket #171. -05 o Changed check_session to check_id. o schema=openid now required when requesting UserInfo. o Removed issued_to, since not well defined. o Removed display values popup, touch, and mobile, since not well defined. -04 o Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard". o Numerous cleanups, including updating references. -03 o Added secret_type to the Token endpoint. o Minor edits to the samples. -02 o Incorporates feedback from Nat Sakimura. -01 o First Draft that incorporates the merge of the Core and Framework specs. Sakimura, et al. [Page 108] OpenID Connect Messages 1.0 July 2013 Authors' Addresses 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 Email: breno@google.com Chuck Mortimore Salesforce Email: cmortimore@salesforce.com Edmund Jay Illumila Email: ejay@mgi1.com Sakimura, et al. [Page 109]