OpenID Connect - Part 1: Authentication Core 1.0 draft-01

Abstract

OpenID Connect Authentication 1.0 is an authentication extension to RFC6749. It allows Clients to verify the identity of the End-User based on the authentication performed by an OAuth 2.0 Authorization Server by extending the Authorization and Token Endpoint responses.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
2.  Terms, Concepts, and Requirements to them (Normative)
    2.1.  End User
    2.2.  Entity
    2.3.  Identity
    2.4.  Claim
    2.5.  Authentication
    2.6.  ID Token
    2.7.  Identifier
    2.8.  Issuer
    2.9.  Issuer Identifier
    2.10.  OpenID Provider (OP)
    2.11.  Relying Party (RP)
    2.12.  Validation
3.  Authorization Endpoint
    3.1.  Request Parameters
    3.2.  Server Processings
    3.3.  Authorization Response
4.  Token Endpoint
    4.1.  Access Token Request
    4.2.  Access Token Request Validation
    4.3.  Access Token Response
    4.4.  ID Token
    4.5.  ID Token Validation by the Client
    4.6.  Refresh Token Response
5.  Initiating Login at Client from Third Party
6.  Security Considerations
7.  Privacy Considerations
8.  IANA Considerations
    8.1.  JSON Web Token Claims Registry
    8.2.  OAuth Parameters Registry
    8.3.  OAuth Extensions Error Registry
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Examples
Appendix B.  Acknowledgements
Appendix C.  Notices
§  Authors' Addresses

1.  Introduction

OpenID Connect 1.0 defines how to perfom federated login using OAuth 2.0. It does so by extending Authorization Endoint and Token Endpoint by defining standardized scope and a new token type called ID Token. In perticular, it introduces a standard scope called openid, which asks the server to provide the authentication event information through a new token type called ID Token, which is a JSON Web Token.

As this specification is built on top of OAuth 2.0, it trys to avoid duplicating the normative text of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. As the result, the readers are expected to be familiar witth to read this specification.

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.

All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] data structures in this specification utilize the JWS Compact Serialization; the JWS JSON Serialization is not used.

When the RFC 2119 language applies to the behavior of OpenID Providers, it is in this specification for explanatory value to help Client implementers understand the expected behavior of OpenID Providers.

2.  Terms, Concepts, and Requirements to them (Normative)

This section explains the basic concept and terms that are required to read this specification. This section is a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as "Issuer Identifier", reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed.

In this specification, the term and definitions are organized in the following way.

2.x. Defined Term (Abbreviation)

Definition of the term in once sentence without an article to start and a trailing punctuation so that the term can be replaced with the definition when it is found in the main text

[SOURCE: Reference to the Source document when applicable]

NOTE: Clarification note is written in the NOTE: section as needed. It may have multiple note section.

NOTE: As explained above, the terms defined in this specification can be and should be expanded by the reader when they are encountered in the main text. However, this does not apply to the terms imported from OAuth 2.0, such as "Access Token".

As this specification is an extension to OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], it uses the terms used there: i.e., "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", "Authorization Request", and "Token Endpoint".

This specification also defines the following terms:

2.1.  End User

Human Resource Owner

2.2.  Entity

Something that has a separate and distinct existence and that can be identified in a context

[SOURCE: ITU-T X.1252]

NOTE: An End User (End User) is one example of an Entity.

2.3.  Identity

Set of attributes related to an Entity

[SOURCE: ISO/IEC 24760-1 (International Organization for Standardization, “ISO/IEC 24760-1 -- Information technology - Security techniques - A framework for identity management -- Part 1: Terminology and concepts,” December 2011.) [ISO24760‑1]]

2.4.  Claim

Piece of information asserted about an Entity (Entity)

2.5.  Authentication

Provision of assurance in the identity of an Entity (Entity)

[SOURCE: ISO/IEC 18014-2 (International Organization for Standardization, “ISO/IEC 18014-2 -- Information technology -- Security techniques -- Time-stamping services -- Part 2: Mechanisms producing independent tokens,” December 2009.) [ISO18014‑2]]

2.6.  ID Token

JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] that contains Claims about the Authentication (Authentication) event

NOTE: It MAY contain other Claims. The actual format and the standard claims included in the ID Token are explained in Section 4.4 (ID Token).

2.7.  Identifier

Value that uniquely characterizes an Entity (Entity) in a specific context

2.8.  Issuer

Entity (Entity) that issues a set of Claims

2.9.  Issuer Identifier

Case sensitive URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components that acts as a verifiable Identifier for an Issuer

2.10.  OpenID Provider (OP)

OAuth 2.0 Authorization Server that is capable of providing Claims to a Relying Party

2.11.  Relying Party (RP)

OAuth 2.0 Client application requiring Claims from an OpenID Provider (OpenID Provider (OP))

2.12.  Validation

Process intended to establish the soundness or correctness of a construct

3.  Authorization Endpoint

For the purpose of this specification, it is assumed that the Relying Party knows the location of the Authorization Endpoint in one way or another. It could be through out-of-band information sharing or through some form of discovery operation such as OpenID Connect Discovery (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” July 2013.) [OpenID.Discovery], which is out of scope of this specification.

To start the Authentication process for the End User, the RP sends the User-Agent to the Authorization Endpoint through HTTP redirection or other mechanisms. The parameters that are sent are that of the OAuth 2.0 Authorization Request plus some OpenID Connect specific parameters. They are sent to the Authorization Endpoint using HTTPS and the server MUST be able to process these parameters.

3.1.  Request Parameters

Followings are the OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] parameters.

scope

REQUIRED. The value MUST contain the openid. This scope value requests ID Token, which is a JWT that includes the Claims about the End-User Authentication event.

response_type

REQUIRED. The value MUST be code.

client_id

REQUIRED. OAuth 2.0 Client Identifier.

redirect_uri

REQUIRED. Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider. This URI MUST exactly match one of the redirect_uris registered for the Client, with the matching performed as described in Section 6.2.1 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) (Simple String Comparison).The redirection URI MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0, though the use of TLS is strongly RECOMMENDED.

state

RECOMMENDED. Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with the browser cookie.

Followings are the extension parameters that this specification defines. All of them are OPTIONAL.

nonce

OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values.

display

OPTIONAL. ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The defined values are:

page

The Authorization Server SHOULD display authentication and consent UI consistent with a full User-Agent page view. If the display parameter is not specified this is the default display mode.

popup

The Authorization Server SHOULD display authentication and consent UI consistent with a popup User-Agent window. The popup User-Agent window SHOULD be 450 pixels wide and 500 pixels tall.

touch

The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface. The Authorization Server MAY attempt to detect the touch device and further customize the interface.

wap

The Authorization Server SHOULD display authentication and consent UI consistent with a "feature phone" type display.

prompt

OPTIONAL. Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are:

none

The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing. This can be used as a method to check for existing authentication and/or consent.

login

The Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot prompt the End-User, it MUST return an error.

consent

The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client.

select_account

The Authorization Server SHOULD prompt the End-User to select a user account. This allows an End-User who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they might have current sessions for. If it cannot prompt the End-User, it MUST return an error.

The prompt parameter can be used by the Client to make sure that the End-User is still present for the current session or to bring attention to the request. If this parameter contains none with any other value, an error is returned.

max_age

OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. When max_age is used, the ID Token returned MUST include an auth_time Claim Value.

ui_locales

OPTIONAL. End-User's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

id_token_hint

OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User's current or past authenticated session with the Client. This SHOULD be present when prompt=none is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response. The Authorization Server need not be listed as an audience of the ID Token when it is used as an id_token_hint value.

login_hint

OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the phone_number Claim. The use of this parameter is left to the OP's discretion.

acr_values

OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this authentication request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in ID Token section of OpenID Connect Messages. The acr Claim is requested as a Voluntary Claim by this parameter.

Following is a non-normative example using HTTP redirect (with line wraps within values for display purposes only):

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

3.2.  Server Processings

Upon receipt of the parameters, the server MUST perform the following.

1. Check if scope includes openid. If it does not, just proceed with normal OAuth processing;
2. Authenticate the user and obtain authorization from the user as needed;
3. Record the enough information to be able to create the id_token;
4. Find out what response_type the request was using and send the result back accordingly;

3.3.  Authorization Response

If the Resource Owner authenticates and authorizes, the Authorization Endpoint returns the OAuth 2.0 response as follows:

3.3.1.  Authorization Successful Response

The Authorization Server saves the association between code and id_token, and returns code and other OAuth 2.0 parameters as defined in Section 4.1.2 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

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?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj

3.3.2.  Code Validation

To validate a code issued from the Authorization Endpoint with an ID Token in response to a request containing a response_type of code id_token or code id_token token, the Client SHOULD do the following:

1. Hash the octets of the ASCII representation of the code with the hash algorithm specified in JWS (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA] for the alg parameter in the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header.
2. Take the left-most half of the hash and base64url encode it.
3. The value of c_hash in the ID Token MUST match the value produced in the previous step if c_hash is present in the ID Token.

3.3.3.  Authorization Error Response

If the End-User denies the access request or if the request fails, the OP (Authorization Server) informs the RP (Client) by using the Error Response parameters defined in Sections 4.1.2.1 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

In addition to the error codes defined in Sections 4.1.2.1 of OAuth 2.0, this specification also defines the following error codes:

interaction_required

The Authorization Server requires End-User interaction of some form to proceed. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End-User interaction.

login_required

The Authorization Server requires End-User authentication. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for user authentication.

session_selection_required

The End-User is REQUIRED to select a session at the Authorization Server. The End-User MAY be authenticated at the Authorization Server with different associated accounts, but the End-User did not select a session. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface to prompt for a session to use.

consent_required

The Authorization Server requires End-User consent. This error MAY be returned when the prompt parameter in the Authorization Request is set to none to request that the Authorization Server SHOULD NOT display any user interfaces to the End-User, but the Authorization Request cannot be completed without displaying a user interface for End-User consent.

invalid_request_uri

The request_uri in the Authorization Request returns an error or contains invalid data.

invalid_request_object

The request parameter contains an invalid Request Object.

registration_not_supported

The OP does not support use of the registration parameter.

request_not_supported

The OP does not support use of the request parameter.

request_uri_not_supported

The OP does not support use of the request_uri parameter.

4.  Token Endpoint

As in OAuth 2.0, if the response type was code, the Client interacts with the Token Endpoint.

In OpenID Connect, this communication MUST be over TLS. See OpenID Connect Messages for more information on using TLS.

4.1.  Access Token Request

To obtain an Access Token, Refresh Token or ID Token, the Client sends Access Token Request as defined in OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. It the client is a confidential client, then it MUST Authenticate to the Token Endpoint using the authentication method that is agreed between the client and the server for its client_id.

NOTE: Various Client Authentication methods are documented in Section 2.2.1 of OpenID Connect Messages 1.0.

The following is a non-normative example of an Access Token Request:

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

4.2.  Access Token Request Validation

Upon receipt of the request, the Authorization Server MUST:

• Authenticate any Clients that were issued Client Credentials (or for which other Client Authentication methods can be used);
• Ensure the Authorization Code was issued to the authenticated Client;
• Verify that the Authorization Code is valid, and
• Ensure that the Scheme, Host, Path, and Query Parameter segments in the redirect_uri parameter are identical to the redirect_uri parameter value that was included in the initial Authorization Request. If the redirect_uri parameter value not be present when there is only one registered redirect_uri value, the Authorization Server MAY return an error (since the Client should have included the parameter) or MAY proceed without an error (since OAuth 2.0 permits the parameter to be omitted in this case); and
• Check if the received code is associated with a previously created ID Token;

NOTE: The code may have a special structure that indicates what was to be included in the ID Token, or the server might pull them from the database that stored such information using the code.

4.3.  Access Token Response

After receiving and validating a valid and authorized Access Token Request from the Client, the Authorization Server returns a successful response that includes an Access Token and an ID Token. The parameters in the successful response are defined in Section 4.1.4 of OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

This specification only describes OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750]. The OAuth 2.0 response parameter token_type MUST be set to Bearer unless another Token Type has been negotiated with the Client. Servers SHOULD support OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] for interoperability. For security reasons Servers MAY only allow Clients to register specific token_type.

Clients MUST support OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] and MAY support other token_type.

In addition to the OAuth 2.0 response parameters, the following parameters MUST be included in the response:

id_token

ID Token value associated with the authenticated session.

Following is a non-normative example:

HTTP/1.1 200 OK

  {
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   "refresh_token": "8xLOxBtZp8",
   "expires_in": 3600,
   "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
  }

As in the OAuth 2.0 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], Clients SHOULD ignore unrecognized response parameters.

For the case where a Refresh Token was used in the request instead of the Access Token, refer to Section 4.6 (Refresh Token Response).

4.4.  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),” May 2013.) [JWT].

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

The following Claims are used within the ID Token:

iss

REQUIRED. Issuer Identifier for the Issuer of the response. The iss value is a case sensitive URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components.

sub

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

aud

REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the special case when there is one audience, the aud value MAY be a single case sensitive string.

exp

REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 (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. The exp value is a number.

iat

REQUIRED. Time at which the JWT was issued. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. The iat value is a number.

auth_time

OPTIONAL or REQUIRED. Time when the End-User authentication occurred. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] auth_time response parameter.) The auth_time value is a number.

nonce

OPTIONAL or REQUIRED. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authorization Request. If present in the Authorization Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authorization Request. Authorization Servers SHOULD perform no other processing on nonce values used. Use of the nonce is REQUIRED for all requests where an ID Token is returned directly from the Authorization Endpoint. It is OPTIONAL when the ID Token is returned from the Token Endpoint. The nonce value is a case sensitive string.

at_hash

OPTIONAL or REQUIRED. Access Token hash value. If the ID Token is issued from the Authorization Endpoint with an access_token, this is REQUIRED. This is OPTIONAL when the ID Token is issued from the Token Endpoint. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

c_hash

Sometimes REQUIRED. Code hash value. If the ID Token is issued from the Authorization Endpoint with a code, this is REQUIRED. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] header. For instance, if the alg is HS512, hash the code value with SHA-512, then take the left-most 256 bits and base64url encode them. The c_hash value is a case sensitive string.

acr

OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 (International Organization for Standardization, “ISO/IEC 29115:2013 -- Information technology - Security techniques - Entity authentication assurance framework,” March 2013.) [ISO29115] level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of "level 0" is appropriate. Authentications with level 0 SHOULD never be used to authorize access to any resource of any monetary value. (This corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] nist_auth_level 0.) An absolute URI or a registered name (Johansson, L., “An IANA Registry for Level of Assurance (LoA) Profiles,” August 2012.) [RFC6711] SHOULD be used as the acr value; registered names MUST NOT be used with a different meaning than that which is registered. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The acr value is a case sensitive string.

amr

OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the amr Claim is beyond the scope of this specification. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The amr value is an array of case sensitive strings.

azp

OPTIONAL or REQUIRED. Authorized Party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 client_id of the party that will be using it. This Claim is only REQUIRED when the party requesting the ID Token is not the same as the sole audience of the ID Token. It MAY be included even when the Authorized Party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.

sub_jwk

NOT RECOMMENDED or REQUIRED. Public key value used to check the signature of an ID Token issued by a Self-Issued OpenID Provider, as specified in [OpenID.SelfIssued] (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Self-Issued 1.0,” July 2013.). The key is a bare key in JWK [JWK] (Jones, M., “JSON Web Key (JWK),” May 2013.) format (not an X.509 certificate value). Use of the sub_jwk Claim is REQUIRED when the OP is a Self-Issued OP and is NOT RECOMMENDED when the OP is not Self-Issued. The iss value is a JSON object.

[Editor's Note] Perhaps sub_jwk should be moved to [OpenID.SelfIssued] (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Self-Issued 1.0,” July 2013.).

ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored.

ID Tokens MUST be signed using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and OPTIONALLY both signed and then encrypted using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality. ID Tokens MUST NOT use none as the alg value.

ID Tokens SHOULD NOT use the JWS or JWE x5u, x5c, jku, or jwk header parameter fields. Instead, key values and key references used for ID Tokens are communicated in advance using Discovery and Registration parameters.

The following is a non-normative example of a base64url decoded ID Token:

  {
   "iss": "https://server.example.com",
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "auth_time": 1311280969,
   "acr": "urn:mace:incommon:iap:silver",
   "at_hash": "MTIzNDU2Nzg5MDEyMzQ1Ng"
  }

4.5.  ID Token Validation by the Client

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

1. If the Client has negotiated the encryption algorithm to be used for ID Token, then the Client MUST decrypt the ID Token using the key pair specified for it according to JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” May 2013.) [JWE] and JWA (Jones, M., “JSON Web Algorithms (JWA),” May 2013.) [JWA].

   NOTE:

   The Client and the Server MAY utilize [OpenID.Registration] (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.) for this purpose, which allows the client to provided the algorithm through id_token_encrypted_response_alg parameter and the associated key pair.

2. The Client MUST validate that the aud (audience) Claim contains its client_id value registered at the Issuer identified by the iss (issuer) Claim as an audience. The aud (audience) Claim MAY contain an array with more than one element. The ID Token MUST be rejected if the ID Token does not list the Client as a valid audience, or if it contains additional audiences not trusted by the Client.
3. If the ID Token contains multiple audiences, the Client SHOULD verify that an azp Claim is present.
4. If an azp (authorized party) Claim is present, the Client SHOULD verify and that its client_id is the Claim value.
5. Validation the issuer through TLS server validation MUST be performed.
6. Optionally, the Client MAY perform ID Token signature Validation for added security. In this case, the Client MUST validate the signature of all other ID Tokens according to JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2013.) [JWS] using the algorithm specified in the alg parameter of the JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.) [JWT] header. When checking the signature:
   1. The alg value SHOULD be the default of RS256 or the algorithm sent by the Client during the registration process. If the Client used the OpenID Connect Dynamic Registration 1.0, then it is in the id_token_signed_response_alg parameter.
   2. If the alg parameter of the JWT header is a MAC based algorithm such as HS256, HS384, or HS512, the octets of the UTF-8 representation of the client_secret corresponding to the client_id contained in the aud (audience) Claim are used as the key to validate the signature. Multiple audiences are not supported for MAC based algorithms.
   3. For other Signing algorithms, the Client MUST use the signing key provided in Discovery by the Issuer. The issuer MUST exactly match the value of the iss (issuer) Claim.
7. The current time MUST be less than the value of the exp Claim.
8. The iat Claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is Client specific.
9. If a nonce value was sent in the Authorization Request, a nonce Claim MUST be present and its value checked to verify that it is the same value as the one that was sent in the Authorization Request. The Client SHOULD check the nonce value for replay attacks. The precise method for detecting replay attacks is Client specific.
10. 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.
11. If the auth_time Claim was requested, either through a specific request for this Claim or by using the max_age parameter, the Client SHOULD check the auth_time Claim value and request re-authentication if it determines too much time has elapsed since the last End-User authentication.

4.6.  Refresh Token Response

If an ID Token is returned as a result of a token refresh request, the following requirements apply:

• its iss Claim value MUST be the same as in the ID Token issued when the original authentication occurred,
• its sub Claim value MUST be the same as in the ID Token issued when the original authentication occurred,
• its iat Claim MUST represent the time that the new ID Token is issued,
• its aud Claim value MUST be the same as in the ID Token issued when the original authentication occurred,
• if the ID Token contains an auth_time Claim, its value MUST represent the time of the original authentication - not the time that the new ID token is issued,
• its azp Claim value MUST be the same as in the ID Token issued when the original authentication occurred; if no azp Claim was present in the original ID Token, one MUST NOT be present in the new ID Token, and
• otherwise, the same rules apply as apply when issuing an ID Token at the time of the original authentication.

5.  Initiating Login at Client from Third Party

In some cases, the login flow can start at the Authorization Server or another party by contacting the Client via a stored link. The target resource at the Client can be a deep link, rather than a default landing page.

The Client MAY optionally register (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2013.) [OpenID.Registration] an initiate_login_uri that can be used by the Authorization Server or another party to initiate a login for an End-User at the Client.

The Authorization Server or a third party sends a Login Initiation Request to the Client Initiation URI with the following parameters:

login_hint

OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in. If the client receives a value for this string-valued parameter, it MUST include it in the subsequent authorization request as the login_hint parameter value.

iss

REQUIRED. Issuer Identifier for the Issuer that the Client is to send the authentication request to. Its value MUST be a URL using the https scheme.

target_link_uri

OPTIONAL. URI that the Client is requested to redirect to after authentication. Clients MUST verify the value of the target_link_uri to prevent being used as an open redirector to external sites.

Other parameters MAY be sent, if defined by extensions. Any parameters used that are not understood MUST be ignored by the Client.

Clients SHOULD employ frame busting and other techniques to prevent End-Users from being logged in by third party sites without their knowledge.

6.  Security Considerations

For Security Considerations, refer to OpenID Connect Consolidated Security and Privacy Considerations document.

7.  Privacy Considerations

For Privacy Considerations, refer to OpenID Connect Consolidated Security and Privacy Considerations document.

8.  IANA Considerations

8.1.  JSON Web Token Claims Registry

This specification registers the Claims defined in Section 4.4 (ID Token) in the IANA JSON Web Token Claims registry defined in [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2013.).

8.1.1.  Registry Contents

• Claim Name: azp
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: nonce
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: auth_time
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: at_hash
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: c_hash
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: acr
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: amr
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

• Claim Name: sub_jwk
• Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification Document(s): Section 4.4 (ID Token) of this document

8.2.  OAuth Parameters Registry

This specification registers the following parameters in the IANA OAuth Parameters registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

8.2.1.  Registry Contents

• Parameter name: nonce
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: display
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: prompt
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: max_age
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: ui_locales
• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: id_token_hint

• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: login_hint

• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: acr_values

• Parameter usage location: Authorization Request
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.1 (Request Parameters) of this document
• Related information: None

• Parameter name: id_token

• Parameter usage location: Authorization Response, Access Token Response
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 4.3 (Access Token Response) of this document
• Related information: None

8.3.  OAuth Extensions Error Registry

This specification registers the following errors in the IANA OAuth Extensions Error registry defined in RFC 6749 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

8.3.1.  Registry Contents

• Error name: interaction_required
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.3.3 (Authorization Error Response) of this document

• Error name: login_required
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.3.3 (Authorization Error Response) of this document

• Error name: session_selection_required
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.3.3 (Authorization Error Response) of this document

• Error name: consent_required
• Error usage location: Authorization Endpoint
• Related protocol extension: OpenID Connect
• Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net
• Specification document(s): Section 3.3.3 (Authorization Error Response) of this document

9.  References

9.1. Normative References

9.2. Informative References

Appendix A.  Examples

In this appendix, several examples on the request and responses are shown to aid the developers test their code.

response_type=code

  https://server.example.com/op/authorize?
    response_type=code
    &client_id=s6BhdRkqt3
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &scope=openid
    &nonce=n-0S6_WzA2Mj
    &state=af0ifjsldkj

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
    &state=af0ifjsldkj

Upon receipt of the code, the Client sends Token Request to the Token Endpoint to obtain the Tokens.

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

 HTTP/1.1 200 OK

  {
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   "refresh_token": "8xLOxBtZp8",
   "expires_in": 3600,
   "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
  }

Verifying and decoding the ID Token will yield the following Claims:

  {
   "iss": "http://server.example.com",
   "sub": "248289761001",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "at_hash": "77QmUPtjPfzWtF2AnpK9RQ"
  }

Appendix B.  Acknowledgements

As a successor version of OpenID, this specification heavily relies on ideas explored in OpenID Authentication 2.0 (OpenID Foundation, “OpenID Authentication 2.0,” December 2007.) [OpenID.2.0]. Please refer to Appendix C of OpenID Authentication 2.0 for the full list of the contributors for that specification.

In addition, the OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification.

Naveen Agarwal (naa@google.com), Google

Amanda Anganes (aanganes@mitre.org), Mitre

Casper Biering (cb@peercraft.com), Peercraft

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

Tim Bray (tbray@textuality.com), Google

Johnny Bufu (jbufu@janrain.com), Janrain

Brian Campbell (bcampbell@pingidentity.com), Ping Identity

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

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

Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services

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

Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea

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

Edmund Jay (ejay@mgi1.com), Illumila

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

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

Nov Matake (nov@matake.jp), Independent

Chuck Mortimore (cmortimore@salesforce.com), Salesforce

Anthony Nadalin (tonynad@microsoft.com), Microsoft

Hideki Nara (hdknr@ic-tact.co.jp), Tact Communications

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

David Recordon (dr@fb.com), Facebook

Justin Richer (jricher@mitre.org), Mitre

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

Luke Shepard (lshepard@fb.com), Facebook

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

Paul Tarjan (pt@fb.com), Facebook

Appendix C.  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.

Authors' Addresses