Draft N. Sakimura NRI J. Bradley Ping Identity M. Jones Microsoft B. de Medeiros Google C. Mortimore Salesforce E. Jay Illumila January 22, 2013 OpenID Connect Implicit Client Profile 1.0 - draft 06 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 1.0 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 January 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Notation and Conventions . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. Protocol Flows . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. OpenID Connect Scope Values . . . . . . . . . . . . . . . 6 2.2. Implicit Flow . . . . . . . . . . . . . . . . . . . . . . 7 2.2.1. Client Prepares Authorization Request . . . . . . . . 8 2.2.2. Client Sends Request to Authorization Server . . . . . 10 2.2.3. Authorization Server Authenticates End-User . . . . . 11 2.2.4. Authorization Server Obtains End-User Consent/Authorization . . . . . . . . . . . . . . . . 11 2.2.5. Authorization Server Sends End-User Back to Client . . 11 2.2.5.1. End-User Grants Authorization . . . . . . . . . . 11 2.2.5.2. End-User Denies Authorization or Invalid Request . . . . . . . . . . . . . . . . . . . . . 12 2.2.5.3. Example Redirect URI response . . . . . . . . . . 12 2.3. ID Token . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.3.1. ID Token Validation . . . . . . . . . . . . . . . . . 15 2.3.2. Access Token Validation . . . . . . . . . . . . . . . 16 2.4. UserInfo Endpoint . . . . . . . . . . . . . . . . . . . . 17 2.4.1. UserInfo Request . . . . . . . . . . . . . . . . . . . 17 2.4.2. UserInfo Response . . . . . . . . . . . . . . . . . . 18 2.4.2.1. Address Claim . . . . . . . . . . . . . . . . . . 22 2.4.2.2. Claim Stability and Uniqueness . . . . . . . . . . 23 2.4.3. UserInfo Error Response . . . . . . . . . . . . . . . 23 3. Self-Issued OpenID Provider . . . . . . . . . . . . . . . . . 24 3.1. Self-Issued OpenID Provider Discovery . . . . . . . . . . 24 3.2. Client Registration to Self-Issued OpenID Provider . . . . 24 3.3. Self-Issued OpenID Provider Request . . . . . . . . . . . 25 3.4. Self-Issued OpenID Provider Response . . . . . . . . . . . 26 3.5. Self-Issued ID Token Validation . . . . . . . . . . . . . 26 4. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 29 4.1. Query String Serialization . . . . . . . . . . . . . . . . 29 4.2. Form Serialization . . . . . . . . . . . . . . . . . . . . 29 5. String Operations . . . . . . . . . . . . . . . . . . . . . . 30 6. Implementation Considerations . . . . . . . . . . . . . . . . 31 6.1. Discovery and Registration . . . . . . . . . . . . . . . . 31 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 33 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35 10.1. Normative References . . . . . . . . . . . . . . . . . . . 35 10.2. Informative References . . . . . . . . . . . . . . . . . . 37 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 38 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 40 Appendix C. Document History . . . . . . . . . . . . . . . . . . 41 Sakimura, et al. [Page 2] OpenID Connect Implicit Client Profile 1.0 January 2013 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 Sakimura, et al. [Page 3] OpenID Connect Implicit Client Profile 1.0 January 2013 1. Introduction OpenID Connect Implicit Client Profile 1.0 is a profile of the OpenID Connect Standard 1.0 [OpenID.Standard] specification 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 1.0 [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 4] OpenID Connect Implicit Client Profile 1.0 January 2013 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 5] OpenID Connect Implicit Client Profile 1.0 January 2013 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. This specification 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 [OpenID.Standard] specification. 2.1. OpenID Connect Scope Values 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. OAuth 2.0 allows additional scope values to be specified, as extensions. This specification describes only the scope values used by OpenID Connect. Claims requested by the following scopes are treated by Authorization servers as voluntary. Claims can be requested as essential by using the OpenID Request Object [OpenID.Messages]. 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. 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". Sakimura, et al. [Page 6] OpenID Connect Implicit Client Profile 1.0 January 2013 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. 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. offline_access This scope value MAY NOT be used with the OpenID Connect Implicit Client Profile 1.0. See the OpenID Connect Basic Client Profile 1.0 [OpenID.Basic] for its usage in that profile. Multiple scope values MAY be used 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 minimize the amount of information that the user is being asked to disclose, a Client may elect to only request a subset of the information available from the UserInfo Endpoint. The following is a non-normative example of a "scope" Request. scope=openid profile email phone 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. Sakimura, et al. [Page 7] OpenID Connect Implicit Client Profile 1.0 January 2013 2.2.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. 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]. If using the HTTP "GET" method, the parameters are serialized using Query String Serialization (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]. This profile further constrains the following request parameters: response_type 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. Other REQUIRED parameters in the request include the following: client_id OAuth 2.0 Client Identifier. scope OAuth 2.0 "scope" value. It MUST include "openid" as one of the space delimited ASCII strings. OPTIONAL scope values of "profile", "email", "address", "phone", and "offline_access" are also defined. redirect_uri Redirection URI to which 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. 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. Sakimura, et al. [Page 8] OpenID Connect Implicit Client Profile 1.0 January 2013 state RECOMMENDED. Opaque value used to maintain state between the request and the callback; serves as a protection against XSRF attacks. display 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. 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 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 The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims. This can be used as a method to check for existing authentication and/or consent. login The Authorization Server MUST prompt the End-User for reauthentication. consent The Authorization Server MUST prompt the End-User for consent before returning information to the Client. select_account The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for. Sakimura, et al. [Page 9] OpenID Connect Implicit Client Profile 1.0 January 2013 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. login_hint Hint to the authorization service about the login identifier the user may use to authenticate at the authorization service (if necessary). This hint can be used by an RP if it first asks the user for their email address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is recommended that the hint value match the value used for discovery. The use of this parameter is up to the OP's discretion. 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 Request to 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 Sakimura, et al. [Page 10] OpenID Connect Implicit Client Profile 1.0 January 2013 2.2.3. Authorization Server Authenticates 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 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 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.2.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.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 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" 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. Sakimura, et al. [Page 11] OpenID Connect Implicit Client Profile 1.0 January 2013 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. 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 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.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 12] OpenID Connect Implicit Client Profile 1.0 January 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