Draft N. Sakimura NRI J. Bradley Ping Identity M. Jones Microsoft B. de Medeiros Google C. Mortimore Salesforce E. Jay Illumila May 30, 2013 OpenID Connect Implicit Client Profile 1.0 - draft 10 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. OpenID Connect Implicit Client Profile 1.0 is a profile of the OpenID Connect Messages 1.0 and OpenID Connect Standard 1.0 specifications that is designed to be easy to read and implement for basic Web-based Relying Parties using the OAuth implicit grant type. This specification intentionally duplicates content from the Messages and Standard specifications to provide a self-contained implementation profile for basic Web-based Relying Parties using the OAuth implicit grant type. OpenID Providers and non-Web-based applications should instead consult the Messages and Standard specifications. Sakimura, et al. [Page 1] OpenID Connect Implicit Client Profile 1.0 May 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Notation and Conventions . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. Protocol Elements . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Implicit Flow . . . . . . . . . . . . . . . . . . . . . . 6 2.1.1. Client Prepares Authorization Request . . . . . . . . 6 2.1.1.1. Request Parameters . . . . . . . . . . . . . . . . 7 2.1.2. Client Sends Request to Authorization Server . . . . . 10 2.1.3. Authorization Server Authenticates End-User . . . . . 10 2.1.4. Authorization Server Obtains End-User Consent/Authorization . . . . . . . . . . . . . . . . 10 2.1.5. Authorization Server Sends End-User Back to Client . . 11 2.1.5.1. End-User Grants Authorization . . . . . . . . . . 11 2.1.5.2. End-User Denies Authorization or Invalid Request . . . . . . . . . . . . . . . . . . . . . 12 2.1.5.3. Example Redirect URI Response . . . . . . . . . . 12 2.2. ID Token . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1. ID Token Validation . . . . . . . . . . . . . . . . . 16 2.2.2. Access Token Validation . . . . . . . . . . . . . . . 17 2.3. UserInfo Endpoint . . . . . . . . . . . . . . . . . . . . 18 2.3.1. UserInfo Request . . . . . . . . . . . . . . . . . . . 18 2.3.2. UserInfo Response . . . . . . . . . . . . . . . . . . 18 2.3.3. UserInfo Error Response . . . . . . . . . . . . . . . 19 2.4. Scope Values . . . . . . . . . . . . . . . . . . . . . . . 19 2.5. Standard Claims . . . . . . . . . . . . . . . . . . . . . 20 2.5.1. Address Claim . . . . . . . . . . . . . . . . . . . . 26 2.5.2. Claims Languages and Scripts . . . . . . . . . . . . . 27 2.5.3. Claim Stability and Uniqueness . . . . . . . . . . . . 28 3. Self-Issued OpenID Provider . . . . . . . . . . . . . . . . . 29 3.1. Self-Issued OpenID Provider Discovery . . . . . . . . . . 29 3.2. Self-Issued OpenID Provider Registration . . . . . . . . . 29 3.2.1. Providing Additional Registration Information . . . . 30 3.3. Self-Issued OpenID Provider Request . . . . . . . . . . . 30 3.4. Self-Issued OpenID Provider Response . . . . . . . . . . . 31 3.5. Self-Issued ID Token Validation . . . . . . . . . . . . . 31 4. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 34 4.1. Query String Serialization . . . . . . . . . . . . . . . . 34 4.2. Form Serialization . . . . . . . . . . . . . . . . . . . . 34 5. String Operations . . . . . . . . . . . . . . . . . . . . . . 35 6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . . . 36 7. Implementation Considerations . . . . . . . . . . . . . . . . 37 7.1. Discovery and Registration . . . . . . . . . . . . . . . . 37 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38 8.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 38 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 39 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 Sakimura, et al. [Page 2] OpenID Connect Implicit Client Profile 1.0 May 2013 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 11.1. Normative References . . . . . . . . . . . . . . . . . . . 41 11.2. Informative References . . . . . . . . . . . . . . . . . . 43 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 44 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 46 Appendix C. Document History . . . . . . . . . . . . . . . . . . 47 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 Sakimura, et al. [Page 3] OpenID Connect Implicit Client Profile 1.0 May 2013 1. Introduction OpenID Connect Implicit Client Profile 1.0 is a profile of the OpenID Connect Messages 1.0 [OpenID.Messages] and OpenID Connect Standard 1.0 [OpenID.Standard] specifications that is designed to be easy to read and implement for basic Web-based Relying Parties using the OAuth implicit grant type. This specification intentionally duplicates content from the Messages and Standard specifications to provide a self-contained implementation profile for basic Web-based Relying Parties using the OAuth implicit grant type. See the OpenID Connect Basic Client Profile 1.0 [OpenID.Basic] specification for a related profile for basic Web-based Relying Parties using the OAuth "authorization_code" grant type. OpenID Providers and non-Web-based applications should instead consult the Messages and Standard specifications. This profile omits implementation and security considerations for OpenID Providers and non-Web-based applications. 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 [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] data structures in this specification utilize the JWS Compact Serialization; the JWS JSON Serialization is not used. When the RFC 2119 language applies to the behavior of OpenID Providers, it is in this specification for explanatory value to help Client implementers understand the expected behavior of OpenID Providers. 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]. This specification also defines the following terms: Sakimura, et al. [Page 4] OpenID Connect Implicit Client Profile 1.0 May 2013 Relying Party (RP) Application requiring Claims from an OpenID Provider. OpenID Provider (OP) Service capable of providing Claims to a Relying Party. Claim Piece of information about an Entity that a Claims Provider asserts about that Entity. Claims Provider Server that can return Claims about an Entity. End-User Human Resource Owner. Entity Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity. 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. 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. ID Token JSON Web Token (JWT) [JWT] that contains Claims about the authentication event. Issuer Entity that issues a set of Claims. Issuer Identifier URL using the "https" scheme that acts as a verifiable identifier for an Issuer. 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. Voluntary Claim Claim specified by the Client as being useful but not essential for the specific task requested by the End-User. Sakimura, et al. [Page 5] OpenID Connect Implicit Client Profile 1.0 May 2013 2. Protocol Elements Authorization Requests can follow one of two paths; the Implicit Flow or the Authorization Code Flow. The Authorization Code Flow is suitable for Clients that can securely maintain a Client Secret between themselves and the Authorization Server whereas, the Implicit Flow is suitable for Clients that cannot. This specification only provides information that is sufficient for basic Clients using the Implicit Flow. 2.1. Implicit Flow The Implicit Flow consists of the following steps: 1. Client prepares an Authorization Request containing the desired request parameters. 2. Client sends a request to the Authorization Server. 3. Authorization Server authenticates the End-User. 4. Authorization Server obtains the End-User Consent/Authorization. 5. Authorization Server sends the End-User back to the Client with an Access Token and ID Token. 2.1.1. Client Prepares Authorization Request When the Client wishes to access a Protected Resource and the End- User Authorization has not yet been obtained, the Client prepares an Authorization Request to the Authorization Endpoint. Communication with the Authorization Endpoint MUST utilize TLS. See Section 8.1 for more information on using TLS. Clients MAY construct the request using the HTTP "GET" or the HTTP "POST" method as defined in RFC 2616 [RFC2616]. If using the HTTP "GET" method, the parameters are serialized using the Query String Serialization, per Section 4.1. If using the HTTP "POST" method, the request parameters are added to the HTTP request entity-body using the "application/x-www-form-urlencoded" format as defined by [W3C.REC-html401-19991224]. Sakimura, et al. [Page 6] OpenID Connect Implicit Client Profile 1.0 May 2013 The following is a non-normative example of an Authorization Request URL (with line wraps for display purposes only): https://server.example.com/authorize? response_type=token%20id_token &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj 2.1.1.1. Request Parameters This profile of OpenID Connect uses the following OAuth 2.0 request parameters: response_type REQUIRED. This value MUST include "token" and "id_token", as a space delimited list. This requests that both an Access Token and an ID Token be returned in the URL fragment of the response, as specified in OAuth 2.0 Multiple Response Type Encoding Practices [OAuth.Responses]. 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. 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. state RECOMMENDED. Opaque value used to maintain state between the request and the callback; serves as a protection against XSRF attacks. This specification also defines the following request parameters: Sakimura, et al. [Page 7] OpenID Connect Implicit Client Profile 1.0 May 2013 nonce REQUIRED. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified 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 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. 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. This can be used as a method to check for existing authentication and/or consent. login The Authorization Server MUST prompt the End-User for reauthentication. Sakimura, et al. [Page 8] OpenID Connect Implicit Client Profile 1.0 May 2013 consent The Authorization Server MUST prompt the End-User for consent before returning information to the Client. select_account The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for. 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 that the End-User must be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. 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. login_hint OPTIONAL. Hint to the Authorization Server about the login identifier the End-User may use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass Sakimura, et al. [Page 9] OpenID Connect Implicit Client Profile 1.0 May 2013 that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the "phone_number" Claim. The use of this parameter is left to the OP's discretion. acr_values OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the "acr" values that the Authorization Server MUST use for processing requests from this Client. The Authentication Context Class satisfied by the authentication performed is returned as the "acr" Claim Value, as specified in Section 2.2. 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 3.2.1. The "registration" parameter SHOULD NOT be used when the OP is not a Self-Issued OP. 2.1.2. Client Sends Request to Authorization Server Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint using HTTPS. Following is a non-normative example using HTTP redirect (with line wraps for display purposes only): HTTP/1.1 302 Found Location: https://server.example.com/authorize? response_type=token%20id_token &client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &scope=openid%20profile &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj 2.1.3. Authorization Server Authenticates End-User The Authorization Server authenticates the resource owner to make sure that consent is obtained from the right party. If interaction with the End-User occurs over an HTTP channel, it MUST use TLS, as per Section 8.1. The exact authentication methods used are out of scope for this specification. 2.1.4. Authorization Server Obtains End-User Consent/Authorization The Authorization Server obtains an authorization decision for the requested Claims. This can done by presenting the End-User with a Sakimura, et al. [Page 10] OpenID Connect Implicit Client Profile 1.0 May 2013 dialogue that allows the End-User to recognize what he is consenting to and obtain his consent or by establishing consent via other means (for example, via previous administrative consent). The "openid" scope value declares that this OAuth 2.0 request is an OpenID Connect request. Use of all other scope values is OPTIONAL. 2.1.5. Authorization Server Sends End-User Back to Client Once the authorization is determined, the Authorization Server returns a successful response or an error response. 2.1.5.1. End-User Grants Authorization If the Resource Owner grants the access request, the Authorization Server issues an Access Token and delivers it to the Client by adding the following parameters to the fragment component of the redirection URI using the "application/x-www-form-urlencoded" format as defined in Section 4.2.2 of OAuth 2.0 [RFC6749] and OAuth 2.0 Multiple Response Type Encoding Practices [OAuth.Responses]. In the Implicit Flow, the entire response is returned in the fragment component of the redirect URI, as defined in 4.2.2 of OAuth 2.0 [RFC6749]. access_token REQUIRED. Access Token for the UserInfo Endpoint. token_type REQUIRED. OAuth 2.0 Token Type value. The value MUST be "Bearer" or another "token_type" value that the Client has negotiated with the Authorization Server. Clients implementing this profile MUST support the OAuth 2.0 Bearer Token Usage [RFC6750] specification. This profile only describes the use of bearer tokens. id_token REQUIRED. ID Token. state OAuth 2.0 state value. REQUIRED if the "state" parameter is present in the Client Authorization Request. Clients MUST verify that the "state" value is equal to the exact value of "state" parameter in the Authorization Request. expires_in OPTIONAL. Expiration time of the Access Token in seconds since the response was generated. The Client can then use the Access Token to access protected resources at Resource Servers. Sakimura, et al. [Page 11] OpenID Connect Implicit Client Profile 1.0 May 2013 The following is a non-normative example (with line wraps for the display purposes only): HTTP/1.1 302 Found Location: https://client.example.org/cb# access_token=SlAV32hkKG &token_type=bearer &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso &expires_in=3600 &state=af0ifjsldkj 2.1.5.2. End-User Denies Authorization or Invalid Request If the End-User denies the authorization or the End-User authentication fails, the Authorization Server MUST return the error Authorization Response as defined in 4.2.2.1 of OAuth 2.0 [RFC6749]. No other parameters SHOULD be returned. 2.1.5.3. Example Redirect URI Response The Client must provide a way for the User-Agent to parse the fragment encoded response and post it to the Web Server Client for validation. The following is an example of a JavaScript file that a Client might host at its "redirect_uri". This is loaded by the redirect from the Authorization Server. The fragment is parsed and then sent by "POST" to a URI that will validate the information received. Sakimura, et al. [Page 12] OpenID Connect Implicit Client Profile 1.0 May 2013 Following is a non-normative example of a Redirect URI response: GET /cb HTTP/1.1 Host: client.example.org HTTP/1.1 200 OK Content-Type: text/html