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.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
2.  Protocol Flows
    2.1.  OpenID Connect Scope Values
    2.2.  Implicit Flow
        2.2.1.  Client Prepares Authorization Request
        2.2.2.  Client Sends Request to Authorization Server
        2.2.3.  Authorization Server Authenticates End-User
        2.2.4.  Authorization Server Obtains End-User Consent/Authorization
        2.2.5.  Authorization Server Sends End-User Back to Client
            2.2.5.1.  End-User Grants Authorization
            2.2.5.2.  End-User Denies Authorization or Invalid Request
            2.2.5.3.  Example Redirect URI response
    2.3.  ID Token
        2.3.1.  ID Token Validation
        2.3.2.  Access Token Validation
    2.4.  UserInfo Endpoint
        2.4.1.  UserInfo Request
        2.4.2.  UserInfo Response
            2.4.2.1.  Address Claim
            2.4.2.2.  Claim Stability and Uniqueness
        2.4.3.  UserInfo Error Response
3.  Self-Issued OpenID Provider
    3.1.  Self-Issued OpenID Provider Discovery
    3.2.  Client Registration to Self-Issued OpenID Provider
    3.3.  Self-Issued OpenID Provider Request
    3.4.  Self-Issued OpenID Provider Response
    3.5.  Self-Issued ID Token Validation
4.  Serializations
    4.1.  Query String Serialization
    4.2.  Form Serialization
5.  String Operations
6.  Implementation Considerations
    6.1.  Discovery and Registration
7.  Security Considerations
8.  Privacy Considerations
9.  IANA Considerations
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

OpenID Connect Implicit Client Profile 1.0 is a profile of the OpenID Connect Standard 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” January 2013.) [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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” January 2013.) [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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [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

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) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [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

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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” January 2013.) [OpenID.Standard] specification.

2.1.  OpenID Connect Scope Values

OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [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 (Reserved Member Definitions) at the UserInfo Endpoint be granted by the issued Access Token. These Claims are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_time.

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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Profile 1.0,” January 2013.) [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.

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 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616].

If using the HTTP GET method, the parameters are serialized using Query String Serialization (Query String Serialization). 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] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.).

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.

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.

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

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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] and OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” November 2012.) [OAuth.Responses].

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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [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 (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [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.

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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [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.

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

  <script type="text/javascript">

  // First, parse the query string
  var params = {}, postBody = location.hash.substring(1),
      regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(postBody)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }

  // And send the token over to the server
  var req = new XMLHttpRequest();
  // using POST so query isn't logged
  req.open('POST', 'https://' + window.location.host +
                   '/catch_response', true);
  req.setRequestHeader('Content-Type',
                       'application/x-www-form-urlencoded');

  req.onreadystatechange = function (e) {
    if (req.readyState == 4) {
      if (req.status == 200) {
  // If the response from the POST is 200 OK, redirect the user
        window.location = 'https://'
          + window.location.host + '/redirect_after_login'
      }
  // if the OAuth response is invalid, generate an error message
      else if (req.status == 400) {
        alert('There was an error processing the token')
      } else {
        alert('Something other than 200 was returned')
      }
    }
  };
  req.send(postBody);

2.3.  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) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [JWT].

The ID Token is used to manage the authentication event and user identifier and is scoped to a particular Client via the aud (audience) and nonce Claims.

The following Claims are REQUIRED within the ID Token:

iss

REQUIRED. Issuer Identifier for the Issuer of the response.

sub

REQUIRED. Subject identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client. e.g. 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length.

aud

REQUIRED. Audience that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Client.

azp

OPTIONAL. Authorized Party. This member identifies an OAuth 2.0 client authorized to use this ID Token as an OAuth access token, if different than the Client that requested the ID Token. It MUST contain the client_id of the authorized party.

exp

REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.

iat

REQUIRED. Time at which the JWT was issued. The value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.

auth_time

OPTIONAL. Time when the End-User authentication occurred, specified as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC.

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 from the Authorization Request to the ID Token. The client MUST verify that the nonce Claim value is equal to the value of the nonce parameter sent in the Authorization Request. If present in the Authorization Request, Authorization Servers MUST include a nonce Claim in the ID Token (ID Token) with the Claim value being the nonce value sent in the Authorization Request. Use of the nonce is REQUIRED when using the implicit flow and OPTIONAL when using the code flow.

at_hash

OPTIONAL. Access Token hash value. If the ID Token is issued with an access_token in an implicit flow, this is REQUIRED. The value is produced by base64url encoding the left-most half of the hash created by hashing the access_token with the hash algorithm specified in JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA] for the alg parameter in the JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] header. For instance, if the alg is RS256, hash access_token with SHA-256, then take the left-most 128 bits and base64url encode them.

sub_jwk

OPTIONAL. Public key value used to check the signature of an ID Token issued by a self-issued OpenID Provider, as specified in Section 3 (Self-Issued OpenID Provider). The key is in JWK format. 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 JWT MAY contain other Claims that are understood by all parties using it.

ID Tokens MUST be signed using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] and OPTIONALLY both signed and encrypted using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality.

Clients MUST directly validate the ID Token per ID Token Validation (ID Token Validation).

The following is a non-normative example of a base64url decoded ID Token (with line wraps for display purposes only):

  {
   "iss": "https://server.example.com",
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "at_hash": "MTIzNDU2Nzg5MDEyMzQ1Ng"
  }

2.3.1.  ID Token Validation

To validate the ID Token in the Authorization Response, the Client MUST do the following:

1. 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 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.
2. The Client MUST validate the signature of the ID Token according to JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] using the algorithm specified in the alg parameter of the JWT header.
3. The alg value SHOULD be RS256. Validation of tokens using other signing algorithms is described in the OpenID Connect Messages (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [OpenID.Messages] specification.
4. 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.
5. The current time MUST be less than the value of the exp Claim (possibly allowing for some small leeway to account for clock skew).
6. 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 must be stored to prevent attacks. The acceptable range is Client specific.
7. The value of the nonce Claim MUST be 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.
8. 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.
9. If the auth_time Claim was requested, the Client SHOULD check the value and request re-authentication if it determines too much time has elapsed since the last user authentication.

2.3.2.  Access Token Validation

To validate an Access Token issued with an ID Token in the implicit flow, the client SHOULD do the following:

1. Hash the access_token with the hash algorithm specified in JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA] for the alg parameter in the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] header.
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.

2.4.  UserInfo Endpoint

To obtain the additional attributes and tokens, the Client makes a GET or POST request to the UserInfo Endpoint.

UserInfo Endpoint Servers MUST require the use of a transport-layer security mechanism. The UserInfo Endpoint Server MUST support TLS 1.2 RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and/or TLS 1.0 [RFC2246] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) and MAY support other transport-layer mechanisms with equivalent security.

NOTE: The UserInfo Endpoint response is not guaranteed to be about the Interactive user identified by the sub (subject) element of the ID Token. The sub Claim in the UserInfo Endpoint response MUST exactly match the sub Claim in the ID Token, before using additional UserInfo Endpoint Claims.

2.4.1.  UserInfo Request

Clients MAY send requests with the following parameters to the UserInfo Endpoint to obtain further information about the End-User. The UserInfo Endpoint is an OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] Protected Resource that complies with the OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification. As such, the Access Token SHOULD be specified via the HTTP Authorization header.

access_token

REQUIRED. Access Token obtained from an OpenID Connect Authorization Request. This parameter MUST only be sent using one method through either the HTTP Authorization header or a form-encoded HTTP POST body parameter.

schema

REQUIRED. Schema in which the data is to be returned. The only defined schema value is openid.

id

This identifier is reserved. It MUST be ignored by the endpoint when the openid schema is used.

The following is a non-normative example:

  GET /userinfo?schema=openid HTTP/1.1
  Host: server.example.com
  Authorization: Bearer SlAV32hkKG

2.4.2.  UserInfo Response

If the requested schema is openid, the UserInfo Claims MUST be returned as the members of a JSON object. The response body SHOULD be encoded using UTF-8. The Claims defined below can be returned, as can additional Claims (not specified below).

If a Claim is not returned, that Claim Name SHOULD be omitted from the JSON object representing the Claims; it SHOULD NOT be present with a null or empty string value.

The members MAY be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags MUST be added to each member names delimited by a #, e.g., family_name#ja-Kana-JP for expressing Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same represented as family_name#ja-Hani-JP.

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"
  }

The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during registration [OpenID.Registration] (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” January 2013.). The UserInfo Endpoint MUST return a content-type header to indicate which format is being returned. The following are accepted content types:

2.4.2.1.  Address Claim

The components of a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information.

Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields SHOULD be combined.

formatted

Full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

street_address

Full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.

locality

City or locality component.

region

State, province, prefecture or region component.

postal_code

Zip code or postal code component.

country

Country name component.

2.4.2.2.  Claim Stability and Uniqueness

The sub (subject) claim is the only claim that a client can rely upon to be stable, since the sub claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2.3 (ID Token).

Therefore, the only guaranteed unique identifier for a given End-User is a combination of the Issuer's identifier and the sub claim; other fields such as preferred_username and email MUST NOT be used as unique identifiers for a given End-User.

All other claims carry no such guarantees across different issuers in terms of stability over time or uniqueness across users, and Issuers are permitted to apply local restrictions and policies. For instance, an Issuer MAY re-use a given preferred_username or email address claim across different End-Users at different points in time, and the claimed preferred_username or email address for a given End-User MAY change over time.

2.4.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 (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750].

In addition to the error codes defined in Section 3.1 of OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750], this specification defines the following error codes:

invalid_schema

The requested schema is invalid or unsupported.

3.  Self-Issued OpenID Provider

There is a special issuer "https://self-issued.me" that indicates a user is using a personal OP that issues self-signed ID Tokens.

3.1.  Self-Issued OpenID Provider Discovery

If the input identifier contains the domain self-issued.me, dynamic discovery is not performed. 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.

3.2.  Client Registration to Self-Issued OpenID Provider

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 of the Client.

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.

3.3.  Self-Issued OpenID Provider Request

The Client sends the Authorization Request to the Authorization Endpoint with the following REQUIRED parameters.

response_type

REQUIRED. Constant string value id_token.

client_id

REQUIRED. redirect_uri of the client. Note that since it is same as the redirect_uri, redirect_uri is not required to be sent in the request.

scope

REQUIRED. scope parameter value, as defined in Section 2.1 (OpenID Connect Scope Values).

policy_url

REQUIRED. URL of a page that the Client provides to the End-User to read describing the how the attributes received will be used. The OP SHOULD display this URL to the End-User. Unlike the standard OP case, a self-issued OP cannot receive this value at the registration time, so it has to be provided as a part of the authorization request.

request

OPTIONAL. OpenID Request Object value, as defined in Section 2.1.1.1 of OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [OpenID.Messages]. The OpenID Request Object may be encrypted in a JWE by the client. The sub (subject) of the ID Token MUST be sent as the kid (Key ID) of the JWE.

id_token_hint

OPTIONAL. ID Token (ID Token) passed to the Authorization Server as a hint about the user's current or past authenticated session with the Client. This SHOULD be present if prompt=none is sent. The value is a JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] encoded ID Token as signed by the Issuer, the JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] may be JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] encrypted by the public key of the Issuer for additional confidentiality. If the ID Token received by the RP was encrypted, the Client MUST decrypt the signed ID Token. The Client MAY re-encrypt using the key that the server is capable of decrypting. For a self-issued ID Token, the sub (subject) of the ID Token MUST be sent as the kid (Key ID) of the JWE.

Other parameters MAY be sent. Note that all claims are returned in the ID Token.

The entire URL MUST NOT exceed 2048 bytes.

Following is a non-normative example (with line wraps 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
    &policy_url=https%3A%2F%2Fclient.example.org%2Fusage%2F
    &state=af0ifjsldkj&nonce=n-0S6_WzA2Mj

3.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 a fragment.

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 bytes 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.

3.5.  Self-Issued ID Token Validation

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 2.3.1 (ID Token Validation).
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 (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] using the algorithm specified in the alg parameter of the JWT header [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.), using the key in the sub_jwk claim; the key is in JWK format.
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 bytes 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 must 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 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"
    }
  }

4.  Serializations

A request message MAY be serialized using one of the following methods:

1. Query String Serialization
2. Form Serialization

4.1.  Query String Serialization

In order to serialize the parameters using the query string serialization, the Client constructs the string by adding the parameters and values to the query component using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.). Query string serialization is typically used in HTTP GET requests.

Following is a non-normative example of such serialization:

  GET /authorize?scope=openid&response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
  Host: server.example.com

4.2.  Form Serialization

Parameters and their values are form serialized by adding the parameter names and values to the entity body of the HTTP request using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224] (Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.). Form serialization is typically used in HTTP POST requests.

Following is a non-normative example of such serialization:

  POST /authorize HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded

  scope=openid&response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

5.  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 (Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” 09 2009.) [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.

6.  Implementation Considerations

This specification defines features used by Relying Parties using the OAuth implicit grant type. All of these Relying Parties MUST implement the features that are listed in this specification as being "REQUIRED" or are described with a "MUST".

6.1.  Discovery and Registration

Some OpenID Connect installations can use a pre-configured set of OpenID Providers and/or Relying Parties. In those cases, it may not be necessary to support dynamic discovery of information about identities or services or dynamic registration of Clients.

However, if installations choose to support unanticipated interactions between Relying Parties and OpenID Providers that do not have pre-configured relationships, they SHOULD accomplish this by implementing the facilities defined in the OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” January 2013.) [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” January 2013.) [OpenID.Registration] specifications.

7.  Security Considerations

For security considerations, refer to the OpenID Connect Standard 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” January 2013.) [OpenID.Standard] specification.

8.  Privacy Considerations

The UserInfo response typically contains Personally Identifiable Information. As such, End-User consent for the release of the information for the specified purpose SHOULD be obtained at or prior to the authorization time in accordance with relevant regulations. The purpose of use is typically registered in association with the redirect_uri.

Only necessary UserInfo data SHOULD be stored at the Client and the Client SHOULD associate the received data with the purpose of use statement.

The Resource Server SHOULD make the UserInfo access log available to the End-User so that the End-User can monitor who accessed his data.

To protect the End-User from a possible correlation among Clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the sub (subject) SHOULD be considered.

9.  IANA Considerations

This document makes no requests of IANA.

10.  References

10.1. Normative References

10.2. Informative References

Appendix A.  Acknowledgements

The OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.

Andreas Akre Solberg (andreas.solberg@uninett.no), UNINET

Anthony Nadalin (tonynad@microsoft.com), Microsoft

Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom

Breno de Medeiros (breno@gmail.com), Google

Casper Biering (cb@peercraft.com), Peercraft

Chuck Mortimore (cmortimore@salesforce.com), Salesforce

David Recordon (dr@fb.com), Facebook

Edmund Jay (ejay@mgi1.com), Illumila

George Fletcher (george.fletcher@corp.aol.com), AOL

Hideki Nara (hideki.nara@gmail.com), Takt Communications

John Bradley (ve7jtb@ve7jtb.com), Ping Identity

Johnny Bufu (jbufu@janrain.com), Janrain

Justin Richer (jricher@mitre.org), Mitre

Luke Shepard (lshepard@fb.com), Facebook

Michael B. Jones (mbj@microsoft.com), Microsoft

Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd.

Nov Matake (nov@matake.jp), Independent

Pamela Dingle (pdingle@pingidentity.com), Ping Identity

Paul Tarjan (pt@fb.com), Facebook

Roland Hedberg (roland.hedberg@adm.umu.se), Independent

Ryo Ito (ryo.ito@mixi.co.jp), mixi, Inc.

Torsten Lodderstedt (t.lodderstedt@telekom.de), Deutsche Telekom

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.

Appendix C.  Document History

[[ To be removed from the final specification ]]

-06

• Fixed #637 removed requirement for hash of at_token and code to be SHA2 in Section 2.1.2.1 and Section 5.2.
• Added Section 2.5 Access Token Validation.
• Fixed #620 - Update Section 2.2.5.1 to allow for other token types, but make bearer mandatory to support for implicit clients.
• Fixed #657 - Update Section 3.3 to say that the sub is sent as the kid if the id_token is encrypted in the request.
• Added Implementation Considerations section.
• Fixed #698 - Inconsistent use of articles.
• Updated Scopes description.
• Added auth_time definition to ID Token schema.
• Fixed #655 - Specify UTF-8 as encoding scheme whenever necessary.
• Renamed the user_jwk Claim to sub_jwk, paralleling the change from user_id to sub.
• Defined the sub_jwk claim.
• Clarified that the offline_access scope value MAY NOT be used with the Implicit Client Profile.
• To remove ambiguity in the self-issued sub computation, changed the text "the concatenation of the key values" to "the concatenation of the bytes of the UTF-8 representations of the base64url encoded key values".
• Tracked JWK parameter name changes alg -> kty, mod -> n, exp -> e.

-05

• 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.
• Fixed #689 - Track JWT change that allows JWTs to have multiple audiences.
• Fixed #660 - Clarified that returning the sub value from the UserInfo endpoint is mandatory.
• Fixed #636 - ID Token authorized party claim.
• Fixed #689 - Add caution about multiple audiences.
• Fixed #694 - Add login_hint

-04

• Make it clear that nonce is REQUIRED for implicit
• RE #607 add example decoded id_token for non self-issued.
• 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_endpoint}_encryption_{alg,enc}_values_supported.
• Fixed #666 - JWS signature validation vs. verification.
• Fixed #682 - Change remaining uses of "birthday" to "birthdate".
• Referenced OAuth 2.0 RFCs -- RFC 6749 and RFC 6750.

-03

• Defined means of using a self-issued OP

-02

• Added preferred_username claim under profile scope
• Added ID Token section to describe required claims
• Added section on claim stability

-01

• Removed claims_in_id_token scope value, per decision on June 15, 2012 special working group call

-00

• Initial version, based upon Basic Client specification version -17
• Renamed from Basic Client to Implicit Client, per issue #567
• Changed verified to email_verified, per issue #564
• Removed Check ID Endpoint and added ID token signature verification text, per issue #570
• Changed client.example.com to client.example.org, per issue #251
• Added claims_in_id_token scope definition to Basic and Implicit, per issue #594
• Use standards track version of JSON Web Token spec (draft-ietf-oauth-json-web-token)

Authors' Addresses