Draft N. Sakimura NRI J. Bradley Ping Identity M. Jones Microsoft B. de Medeiros Google C. Mortimore Salesforce E. Jay Illumila December 6, 2012 OpenID Connect Implicit Client Profile 1.0 - draft 04 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 RESTful manner. OpenID Connect Implicit Client Profile is a profile of the OpenID Connect Standard 1.0 Specification that is designed to be easy to read and implement for basic web-based Relying Parties using the OAuth implicit grant type. OpenID Providers should consult the Standard specification. This profile omits implementation and security considerations for OpenID Providers. Sakimura, et al. [Page 1] OpenID Connect Implicit Client Profile 1.0 December 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Protocol Flows . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. OpenID Connect Scopes . . . . . . . . . . . . . . . . . . 5 2.2. Implicit Flow . . . . . . . . . . . . . . . . . . . . . . 6 2.2.1. Client Prepares an Authorization Request . . . . . . . 6 2.2.2. Client sends a request to the Authorization Server . . 9 2.2.3. Authorization Server Authenticates the End-User . . . 9 2.2.4. Authorization Server Obtains the End-User Consent/Authorization . . . . . . . . . . . . . . . . 9 2.2.5. Authorization Server Sends the End-User Back to the Client . . . . . . . . . . . . . . . . . . . . . . 10 2.2.5.1. End-User Grants Authorization . . . . . . . . . . 10 2.2.5.2. End-User Denies Authorization or Invalid Request . . . . . . . . . . . . . . . . . . . . . 11 2.2.5.3. Example Redirect URI response . . . . . . . . . . 11 2.3. ID Token . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4. ID Token Validation . . . . . . . . . . . . . . . . . . . 14 2.5. UserInfo Endpoint . . . . . . . . . . . . . . . . . . . . 15 2.5.1. UserInfo Request . . . . . . . . . . . . . . . . . . . 15 2.5.2. UserInfo Response . . . . . . . . . . . . . . . . . . 16 2.5.2.1. Address Claim . . . . . . . . . . . . . . . . . . 20 2.5.2.2. Claim Stability and Uniqueness . . . . . . . . . . 21 2.5.3. UserInfo Error Response . . . . . . . . . . . . . . . 21 3. Self-Issued Identity Provider . . . . . . . . . . . . . . . . 22 3.1. Self-Issued Identity Provider Discovery . . . . . . . . . 22 3.2. Client Registration to Self-Issued Identity Provider . . . 22 3.3. Self-Issued Identity Provider Request . . . . . . . . . . 23 3.4. Self-Issued Identity Provider Response . . . . . . . . . . 23 3.5. Self-Issued Identity ID Token Validation . . . . . . . . . 23 4. Discovery and Registration . . . . . . . . . . . . . . . . . . 26 5. Query String Serialization . . . . . . . . . . . . . . . . . . 27 6. Form Serialization . . . . . . . . . . . . . . . . . . . . . . 28 7. String Operations . . . . . . . . . . . . . . . . . . . . . . 29 8. Security Considerations . . . . . . . . . . . . . . . . . . . 30 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 31 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 11.1. Normative References . . . . . . . . . . . . . . . . . . . 33 11.2. Informative References . . . . . . . . . . . . . . . . . . 35 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 36 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 38 Appendix C. Document History . . . . . . . . . . . . . . . . . . 39 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 41 Sakimura, et al. [Page 2] OpenID Connect Implicit Client Profile 1.0 December 2012 1. Introduction OpenID Connect Implicit Client Profile is a profile of the OpenID Connect Standard 1.0 Specification [OpenID.Standard] that is designed to be easy to read and implement for basic web-based Relying Parties using the OAuth implicit grant type. See the OpenID Connect Basic Client Profile [OpenID.Basic] specification for a related profile for basic web-based Relying Parties using the OAuth code grant type. OpenID Providers and non web-based applications should consult the Standard specification. This profile omits implementation and security considerations for OpenID Providers. 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. 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: 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 Sakimura, et al. [Page 3] OpenID Connect Implicit Client Profile 1.0 December 2012 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 HTTPS URL that acts as a verifiable identifier for an Issuer 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 Sakimura, et al. [Page 4] OpenID Connect Implicit Client Profile 1.0 December 2012 2. Protocol Flows 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. Clients that do not support TLS MUST use the Authorization Code Flow to prevent the interception of Access Tokens. The OpenID Connect Implicit Client Profile only documents Clients using the Implicit Flow. OpenID Providers MUST support both flows. Clients wanting to use the Authorization Code Flow and OpenID Providers should consult the OpenID Connect Standard 1.0 Specification [OpenID.Standard]. 2.1. OpenID Connect Scopes OpenID Connect Clients use "scope" values as defined in 3.3 of OAuth 2.0 [RFC6749] to specify what access privileges are 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 from the UserInfo Endpoint, and to request an ID Token. OAuth 2.0 allows additional scope values to be specified, as extensions. This specification describes only the scope values used by OpenID Connect. 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 request MUST NOT be treated as an OpenID Connect request. This scope value requests access to the "user_id" Claim at the UserInfo Endpoint. profile OPTIONAL. This scope value requests that access to the End- User's default profile Claims (Table 1) at the UserInfo Endpoint be granted by the issued Access Token. These claims are: "name", "family_name", "given_name", "middle_name", "nickname", "preferred_username", "profile", "picture", "website", "gender", "birthdate", "zoneinfo", "locale", and "updated_time". email OPTIONAL. This scope value requests that access to the "email" and "email_verified" Claims at the UserInfo Endpoint be granted by the issued Access Token. Sakimura, et al. [Page 5] OpenID Connect Implicit Client Profile 1.0 December 2012 address OPTIONAL. This scope value requests that access to the "address" Claim at the UserInfo Endpoint be granted by the issued Access Token. phone OPTIONAL. This scope value requests that access to the "phone_number" Claim at the UserInfo Endpoint be granted by the issued Access Token. Multiple scopes MAY be requested by creating a space delimited, case sensitive list of ASCII scope values. 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 increase new account activation, a Client may elect to only request a subset of the information available from the UserInfo Endpoint. The following is a non-normative example of a "scope" Request. scope=openid profile email phone 2.2. 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.2.1. Client Prepares an 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. The scheme used in the Authorization Endpoint URL MUST be HTTPS. Clients MAY construct the request using the HTTP "GET" or the HTTP "POST" method as defined in RFC 2616 [RFC2616]. Sakimura, et al. [Page 6] OpenID Connect Implicit Client Profile 1.0 December 2012 If using the HTTP "GET" method, the parameters are serialized using Query String Serialization (Section 5). 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]. This profile further constrains the following request parameters: response_type It 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. Other REQUIRED parameters in the request include the following: client_id The OAuth 2.0 Client Identifier. scope It MUST include "openid" as one of the space delimited ASCII strings. OPTIONAL "scope" strings of "profile", "email", "address", and "phone" are also supported. redirect_uri A redirection URI where the response will be sent. This MUST be pre-registered with the provider. The request MAY contain the following OPTIONAL and sometimes REQUIRED parameters: nonce REQUIRED. A 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. 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 is compared to the signed session cookie to detect ID Token replay by third parties. state RECOMMENDED. An opaque value used to maintain state between the request and the callback; serves as a protection against XSRF attacks. display An ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The following values are supported: 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. Sakimura, et al. [Page 7] OpenID Connect Implicit Client Profile 1.0 December 2012 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 A space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End- User for reauthentication and consent. The possible values are: none This value informs the Authorization Server that it MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested "scopes". This can be used as a method to check for existing authentication and/or consent. login The Authorization Server MUST prompt the End-User for reauthentication. consent The Authorization Server MUST prompt the End-User for consent before returning information to the Client. select_account The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for. 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. Sakimura, et al. [Page 8] OpenID Connect Implicit Client Profile 1.0 December 2012 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.2.2. Client sends a request to the Authorization Server Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint. This MAY happen via HTTPS redirect, hyperlinking, or any other secure means of directing the User-Agent to the URL. 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.2.3. Authorization Server Authenticates the End-User The authorization server authenticates the resource owner to make sure that the consent is obtained from the right party. The exact method of how the authentication is performed is out of scope of this specification. 2.2.4. Authorization Server Obtains the End-User Consent/Authorization The Authorization Server obtains an authorization decision, for the requested scopes. This can done by presenting the End-User with a 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 grants the RP access to the user identifier of the authenticated End-User of the session. All other scopes are optional. It is up to the OpenID Provider to determine if an error should be returned in the case of the End-User Sakimura, et al. [Page 9] OpenID Connect Implicit Client Profile 1.0 December 2012 declining to authorize scopes other than "openid". 2.2.5. Authorization Server Sends the End-User Back to the Client Once the authorization is determined, the Authorization Server returns a successful response or an error response. 2.2.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 URL, as defined in 4.2.2 of OAuth 2.0 [RFC6749] access_token REQUIRED. The Access Token for the UserInfo Endpoint. token_type REQUIRED. The value MUST be "bearer" id_token REQUIRED. The ID Token. state 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. The expiration time in seconds of the Access Token. The Client can then use the Access Token to access protected resources at Resource Servers. The following is a non-normative example (with line wraps after the second line 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 Sakimura, et al. [Page 10] OpenID Connect Implicit Client Profile 1.0 December 2012 2.2.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.2.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 11] OpenID Connect Implicit Client Profile 1.0 December 2012 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; charset=utf-8