OpenID Connect Messages 1.0 - draft 07

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.

This specification only defines the endpoints and the associated message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Standard.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
    1.3.  Overview
2.  Messages
    2.1.  Authorization Endpoint
        2.1.1.  ID Token
            2.1.1.1.  User Identifier Types
        2.1.2.  Authorization Request
            2.1.2.1.  OpenID Request Object
        2.1.3.  Authorization Response
        2.1.4.  Authorization Error Response
    2.2.  Token Endpoint
        2.2.1.  Client Authentication
        2.2.2.  Access Token Request
        2.2.3.  Access Token Response
        2.2.4.  Token Error Response
    2.3.  Check ID Endpoint
        2.3.1.  Check ID Request
        2.3.2.  Check ID Response
        2.3.3.  Check ID Error Response
    2.4.  UserInfo Endpoint
        2.4.1.  UserInfo Request
        2.4.2.  UserInfo Response
            2.4.2.1.  Address Claim
        2.4.3.  UserInfo Error Response
    2.5.  Claim Types
        2.5.1.  Normal Claims
        2.5.2.  Aggregated and Distributed Claims
3.  Serializations
    3.1.  JSON Serialization
4.  Signatures and Encryption
    4.1.  Supported Algorithms
    4.2.  Keys
    4.3.  Signing
    4.4.  Encryption
5.  Verification
    5.1.  Authorization Request Verification
        5.1.1.  Encrypted Request Object
        5.1.2.  Signed Request Object
        5.1.3.  Parameter Verification
    5.2.  ID Token Verification
    5.3.  Check ID Request Verification
    5.4.  Check ID Response Verification
    5.5.  UserInfo Response Verification
6.  String Operations
7.  Related Specifications
8.  Security Considerations
    8.1.  Request Disclosure
    8.2.  Server Masquerading
    8.3.  Token Manufacture/Modification
    8.4.  Server Response Disclosure
    8.5.  Server Response Repudiation
    8.6.  Request Repudiation
    8.7.  Access Token Redirect
    8.8.  Token Reuse
    8.9.  Eavesdropping or leaking authorization codes (Secondary Authenticator Capture)
    8.10.  Token Substitution
    8.11.  Timing Attack
    8.12.  Other Crypto Related Attacks
    8.13.  Signing and Encryption order
    8.14.  Issuer Identifier
    8.15.  TLS Requirements
9.  Privacy Considerations
    9.1.  Refresh Token, and Access Token Lifetime
10.  IANA Considerations
11.  References
    11.1.  Normative References
    11.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value.

1.2.  Terminology

This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0], and the terms "Claim Names" and "Claim Values" defined by JSON Web Token (JWT) (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT]. This specification also defines the following terms:

Authentication

An act of verifying End-User's possession of previously provisioned credentials.

Authentication Context

Information that the Relying Party may require before it makes an entitlements decision with respect to an authentication response. Such context may include, but is not limited to, the actual authentication method used or level of assurance such as ITU-T X.1254 | ISO/IEC 29115 (McCallister, E., “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” November 2011.) [ISO29115] entity authentication assurance level.

Authentication Context Class Reference

Identifier that identifies the Authentication Context.

Claim

A piece of information about an Entity that a Claims Provider asserts about that Entity.

Claims Provider

A Server that can return Claims about an Entity.

End-User

A human Resource Owner.

Entity

Something that has a separate and distinct existence and that can be identified in context. An End-User is one example of an Entity.

Personally Identifiable Information (PII)

Any 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)

An identifier that identifies the Entity to a Relying Party. An Entity's PPID at one Relying Party cannot be correlated with the Entity's PPID at another Relying Party.

ID Token

A token that contains Claims about the authentication event.

Issuer

An Entity that issues a set of Claims.

Issuer Identifier

A verifiable identifier for an Issuer. An Issuer Identifier is an HTTPS URL that only contains scheme, host, and OPTIONALLY, port number components. (No path component may be present.)

Message

A request or a response between an OpenID Relying Party and an OpenID Provider.

OpenID Provider (OP)

A service capable of providing Claims to a Relying Party.

OP Endpoints

Authorization Endpoint, Token Endpoint, and UserInfo Endpoint.

OpenID Request Object

A JSON object that holds the OpenID request parameters.

Relying Party (RP)

An application requiring Claims from an OpenID Provider.

Check ID Endpoint

A resource that, when presented with an ID Token by the Client, returns Claims about the user session represented by that ID Token.

UserInfo Endpoint

A Protected Resource that, when presented with an Access Token by the Client, returns Claims about the End-User represented by that Access Token.

1.3.  Overview

The OpenID Connect protocol, in abstract, follows the following steps.

1. The Client sends a request to the Authorization Server's End-User Authorization Endpoint.
2. The Authorization Server authenticates the End-User and obtains appropriate authorization.
3. The Authorization Server responds with an Access Token, an Id Token, and a few other variables.
4. Optionally, the Client sends a request with the ID Token to the Authorization Server's Check ID Endpoint (Check ID Endpoint).
5. Optionally, the Check ID Endpoint responds with authentication information pertaining to the supplied ID Token.
6. The Client sends a request with the Access Token to the UserInfo Endpoint (UserInfo Endpoint).
7. UserInfo Endpoint returns the additional End-User information supported by the Resource Server.

This specification only defines the abstract message flow and message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Basic Client (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Basic Client 1.0,” December 2011.) [OpenID.Basic] or OpenID Connect Standard (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” December 2011.) [OpenID.Standard].

2.  Messages

In OpenID Connect protocols, in abstract, the process proceeds by the Client interacting with endpoints. There are a number of endpoints involved.

1. Authorization Endpoint: The Client sends a request to the Authorization Server at the Authorization Endpoint. The Authorization Server then authenticates the End-User to find out if he is eligible to make the authorization. Then, upon the authorization action of the End-User, the Authorization Server returns an Authorization Response that includes Authorization Code, code. For some Clients, Implicit Grant may be used to obtain access_token without using code. In this case, response_type MUST include token.
2. Token Endpoint: The Client sends the Access Token Request to the Token Endpoint to obtain an Access Token Response which includes an access_token.
3. UserInfo Endpoint: The access_token MAY be sent to the UserInfo Endpoint to obtain Claims about the End-User.
4. Check ID Endpoint: An ID Token MAY be sent to the Check ID Endpoint to obtain information about the authentication event.

2.1.  Authorization Endpoint

The Client sends an Authorization Request to the Authorization Endpoint to obtain either an Authorization Response or an ID Token (ID Token) or both depending on response_type and scope.

2.1.1.  ID Token

The ID Token is a token that contains Claims about the authentication event. The Token is a JSON Web Token (JWT) (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [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. It is used as an Access Token for the Check ID Endpoint, or consumed directly by the Client.

The ID Token MUST minimally attest to the following Claims:

iss

REQUIRED. The Issuer Identifier for the Issuer of the response.

user_id

REQUIRED. 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. This member identifies the audience that this ID Token is intended for. It MUST be the OAuth 2.0 client_id of the Client.

exp

REQUIRED. Type Integer. Identifies the 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 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.

acr

OPTIONAL. (Authentication Context Class Reference): Specifies an Authentication Context Class Reference of the ID Token. The values "1", "2", "3", and "4" map to the ITU-T X.1254 | ISO/IEC 29115 (McCallister, E., “ITU-T Recommendation X.1254 | ISO/IEC DIS 29115 -- Information technology - Security techniques - Entity authentication assurance framework,” November 2011.) [ISO29115] entity authentication assurance level of the authentication performed. The value "0" indicates the End User authentication did not meet the requirements of ISO/IEC 29115 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 nist_auth_level 0.) An absolute URI or a registered short name (Johansson, L., “An IANA registry for SAML 2.0 Level of Assurance Context Classes,” June 2011.) [LoA.Registry] MAY be used as an acr value.

nonce

REQUIRED. Clients MUST verify that the nonce value is equal to the value of the nonce parameter in the Authorization Request.

auth_time

OPTIONAL. If the id_token ("id_token" member) member of the OpenID Request Object (OpenID Request Object) contains the Claim request auth_time, then this Claim is REQUIRED. The Claim Value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time that the End-User authentication occurred. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE auth_time response parameter.)

ID Tokens MUST be signed using JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] and OPTIONALLY both signed and encrypted using JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation and/or confidentiality (Signing and Encryption order).

Clients SHOULD directly validate the ID Token per ID Token Verification (ID Token Verification). Clients that do not understand the ID Token format or that do not wish to directly process ID Tokens MAY treat them as opaque values and submit them to the Check ID Endpoint (Check ID Endpoint) for verification and decryption.

2.1.1.1.  User Identifier Types

Provider's Discovery documents SHOULD list their supported identifier types in the user_id_types_supported element.

If there is more than one type listed in the array, the Client MAY elect to provide its preferred identifier type using the user_id_type parameter during registration.

The types supported by this specification are:

public

This provides the same user_id value to all Clients. It is the default if the provider has no user_id_types_supported element in its discovery document.

pairwise

This provides a different user_id value to each Client, to prevent correlation of the user's activities by Clients without the user's permission.

2.1.1.1.1.  Pairwise Identifier Algorithm

The Provider MUST calculate a unique user_id value for each Sector Identifier.

If the Client has not provided a value for sector_identifier_url in registration, the Sector Identifier used for pairwise identifier calculation is the host component of the registered redirect_uri.

If there are multiple hostnames in the registered redirect_uris, the Client MUST register a sector_identifier_url. When a sector_identifier_url is provided, the host component of that URL is used as the Sector Identifier for the pairwise identifier calculation.

The value of the sector_identifier_url must be a HTTPS URL that points to a JSON file containing an array of redirect_uri values. The values of the registered redirect_uris must be included in the elements of the array, or the registration MUST fail.

A number of algorithms MAY be used by Providers to calculate the pairwise identifier. This specification includes a simple example.

For instance, the Sector Identifier can be concatenated with a local account ID and a salt value that is kept secret by the Provider. The concatenated string is then hashed by an appropriate algorithm.

Calculate user_id = SHA256 ( sector_identifier | local_account_id | salt ).

2.1.2.  Authorization Request

Section 4.1.1 and 4.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0] defines the OAuth Authorization Request parameters. In this specification, the values to the parameters are defined as follows.

response_type

A space delimited, case sensitive list of ASCII string values. Acceptable values include code, token, and id_token. The value MUST include code for requesting an Authorization Code, token for requesting an Access Token, and id_token for requesting an ID Token.

scope

A space delimited, case sensitive list of ASCII string values. The values specify an additive list of Claims that are returned by the UserInfo Endpoint. The following values are defined:

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. The openid value also requests that the ID Token associated with the authentication session be returned. If the response_type includes token, the ID Token is returned in the Authorization Response along with the Access Token. If the response_type includes code, the ID Token is returned as part of the Token Endpoint response. This scope value requests access to the user_id Claim at the UserInfo Endpoint.

profile

OPTIONAL. This requests that access to the End-User's profile Claims (Reserved Member Definitions) excluding the address and email Claims at the UserInfo Endpoint be granted by the issued Access Token.

email

OPTIONAL. This requests that access to the email and verified Claims at the UserInfo Endpoint be granted by the issued Access Token.

address

OPTIONAL. This requests that access to address Claim at the UserInfo Endpoint be granted by the issued Access Token.

phone

OPTIONAL. This requests that access to the phone_number Claim at the UserInfo Endpoint be granted by the issued Access Token.

Other REQUIRED OAuth 2.0 parameters in the request include:

client_id

The OAuth 2.0 Client Identifier.

redirect_uri

A redirection URI where the response will be sent.

The request MAY contain the following OAuth 2.0 parameters:

state

RECOMMENDED. An opaque value used to maintain state between the request and the callback; it can serve as a protection against XSRF attacks, among other uses.

The following extension parameters are also defined:

nonce

REQUIRED. A random, unique string value used to mitigate replay attacks.

display

OPTIONAL. An ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User.

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.

embedded

The Authorization Server SHOULD display authentication and consent UI consistent with the limitations of an embedded user-agent.

prompt

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

none

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 scopes. This can be used as a method to check for existing authentication and/or consent.

login

The Authorization Server MUST prompt the End-User for reauthentication.

consent

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

select_account

The Authorization Server MUST prompt the End-User to select a user account. This allows a user who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they may have current sessions for.

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

request

OPTIONAL. A JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] encoded OpenID Request Object (OpenID Request Object).

request_uri

OPTIONAL. An URL that points to an OpenID Request Object. This is used to pass an OpenID Request Object by reference.

2.1.2.1.  OpenID Request Object

The OpenID Request Object is used to provide OpenID request parameters that MAY differ from the default ones. Implementing support for the OpenID Request Object is OPTIONAL. Supporting it is necessary for implementations that need to request or provide sets of Claims other than the default UserInfo (UserInfo Endpoint), and ID Token Claim sets.

The OpenID Request Object is a JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] that is passed as the value of the "request" parameter in the Authorization Request. The OpenID Request Object can also be sent by reference. Parameters that affect the information returned from the UserInfo Endpoint are in the "userinfo" member. Parameters that affect the information returned in the ID Token are in the "id_token" member. If the same parameters are present both in the Authorization Request and in the OpenID Request Object, the latter takes precedence.

The OpenID Request Object MUST contain all REQUIRED OAuth 2.0 Authorization Request parameters and MAY contain OPTIONAL and extension OAuth 2.0 parameters. The OAuth 2.0 parameter values included MUST match the actual OAuth 2.0 request parameters used.

The OpenID Request Object MAY contain a set of members defined by this specification and MAY contain other members that are not defined by this specification. With only one exception, OpenID Request Object members MUST be understood by both parties; that exception is that OpenID Providers MAY ignore requests for Claims they can not provide or do not understand; however, Relying Parties MAY also consider it an error condition if all requested required Claims are not provided.

The OpenID Request Object JWT MAY be signed or unsigned (plaintext). When it is a plaintext JWT, this is indicated by use of the JWT "alg":"none" convention in the JWT header. If signed, the OpenID Request Object SHOULD contain the standard JWT "iss" (issuer) and "aud" (audience) Claims.

The OpenID Request Object members defined by this specification are:

userinfo

OPTIONAL. (UserInfo request): Requests affecting the values to be returned from the UserInfo Endpoint. If not present, the UserInfo Endpoint behaves in the default manner.

id_token

OPTIONAL. (ID Token request): Requests affecting the values to be to be returned in the ID Token. If not present, the default ID Token contents are used. If present, these parameters are used to request additional Claims incremental to the default Claims of the ID Token. (ID Token)

An example OpenID Request Object body before JWT encoding is as follows:

{
 "response_type": "code id_token",
 "client_id": "s6BhdRkqt3",
 "redirect_uri": "https://client.example.com/cb",
 "scope": "openid profile",
 "state": "af0ifjsldkj",
 "userinfo":
   {
     "claims":
       {
         "name": null,
         "nickname": {"optional": true},
         "email": null,
         "verified": null,
         "picture": {"optional": true}
       }
   },
 "id_token":
   {
     "claims":
       {
        "auth_time": null,
        "acr": { "values":["2"] }
       },
     "max_age": 86400,

   }
}

2.1.2.1.1.  "userinfo" member

The structure of the userinfo (UserInfo Request) member is a JSON object that MAY contain the following members:

claims

OPTIONAL. (Requested Claims): A JSON object containing a set of Claims being requested from the UserInfo Endpoint. If not present, the UserInfo Claims held by the OP that are specified by the scope values used are returned.

preferred_locales

OPTIONAL. A list of preferred languages and scripts for the entire Claims request, represented as a JSON array of BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tag values, ordered by preference.

All members of the userinfo object are OPTIONAL. Other members MAY be present and if so, SHOULD understood by both parties.

2.1.2.1.1.1.  "claims" member

The claims member is a JSON object with a member for each requested Claim. The member names are the requested Claim names. The member values MAY be either:

null

This indicates that this Claim is being requested in the default manner. In particular, this is a required Claim.

A JSON Object

This is used to provide additional information about the Claim being requested.

The Claims MAY be represented in multiple languages and scripts. To specify languages and scripts for the Claim request, BCP47 (Phillips, A. and M. Davis, “Tags for Identifying Languages,” September 2009.) [RFC5646] language tags delimited by a "#" MUST be added to each requested Claim Name for which a particular language and script is requested. For example, the Claim family_name#ja-Kana-JP is used 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 value represented as family_name#ja-Hani-JP.

All members of the claims object are OPTIONAL.

2.1.2.1.1.1.1.  Requested Claims Member

The members defined by this specification for the JSON object value following a Claim Name member are:

optional

This is an OPTIONAL Claim parameter. If present, its value MUST be true, which indicates that it is an optional Claim. If it is not present, it is a required Claim.

Other members MAY be defined to provide additional information about the requested Claim. If the claims member is present in the userinfo object, the Claims requested within it override the Claim set that would otherwise be returned from the UserInfo Endpoint.

2.1.2.1.2.  "id_token" member

The structure and function of the id_token (ID Token request) member of the OpenID Request Object is similar to that of the userinfo member. It MAY include the OPTIONAL claims and preferred_locales members. The structure of these members is the same as that for the userinfo member. If the claims member is present in the id_token object, the Claims requested within it modify the Claim set that would otherwise be returned in the ID Token. Unlike for the userinfo member, typically these Claims will augment, rather than override the default set.

Following Claims MAY be requested in the ID Token by specifying it in the claims member:

user_id

OPTIONAL. (User Identifier): The User Identifier for which an ID Token is being requested. If the specified user is not currently authenticated to the Authorization Server, they may be prompted for authenticated, unless the prompt parameter in the Authorization Request is set to none. The Claim Value in the request is an object containing the single element value.

 "user_id": {"value":"248289761001"}

auth_time

OPTIONAL. (authenticated at): Requests that the auth_time Claim be present in the "id_token" (ID Token) response. The Claim Value in the request is null.

acr

OPTIONAL. (Authentication Context Class Reference): Requests the desired Authentication Context Class References. The element values is an ordered array of strings representing acceptable Authentication Context Class Reference values appearing in order of preference.

 "acr": {"values":["2","http://id.incommon.org/assurance/bronze"]}

In addition to the claims member, these additional members are defined within the id_token member of the OpenID Request Object:

max_age

OPTIONAL. (max authentication age): Specifies that the End-User must be actively authenticated if any present authentication is older than the specified number of seconds. (The max_age request parameter corresponds to the OpenID 2.0 PAPE max_auth_age request parameter.)

It is anticipated that additional id_token parameters MAY be defined to request that additional properties hold for the authentication - for instance, that certain authentication policies be applied (in the same spirit of the OpenID 2.0 PAPE auth_policies values), or that the authentication conform to the policies defined by a specified trust framework. These parameters MAY be defined by extension specifications.

All members of the id_token object are OPTIONAL. Other members MAY be present and if so, SHOULD be understood by both parties.

2.1.3.  Authorization Response

When the response_type in the request is token, the Authorization Response MUST return the parameters defined in section 4.2.2 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0]. This specification only supports Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.) [OAuth.Bearer]. The OAuth 2.0 response parameter "token_type" MUST be set to "Bearer".

When the response_type in the request is code, the Authorization Response MUST return the parameters defined in section 4.1.2 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0].

When the response_type includes other values, they must be returned as defined by their registration. The id_token return type is defined in OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” December 2011.) [OAuth.Responses].

2.1.4.  Authorization Error Response

If the End-User denies the access request or if the request fails, the Authorization Server informs the Client by returning parameters defined in sections 4.1.2.1 and 4.2.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0].

In addition to the error codes defined in section 4.1.2.1 and 4.2.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0], this specification defines the following error codes:

invalid_request_redirect_uri

The redirect_uri in the Authorization Request does not match any of the Client's pre-registered redirect_uris.

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.

user_mismatched

The current logged in End-User at the Authorization Server does not match the requested user. 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 the correct End-User authentication.

invalid_request_uri

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

invalid_openid_request_object

The request parameter contains an invalid OpenID Request Object.

Errors are returned as defined by the registered OAuth 2.0 response_type.

2.2.  Token Endpoint

The Client sends an Access Token Request to the Token Endpoint to obtain Access Token Response, which MAY include Access Token, Refresh Token (Refresh Token, and Access Token Lifetime), ID Token (ID Token), and other variables.

2.2.1.  Client Authentication

During Client Registration, the Client MAY register an authentication method. If no method is registered, the default method of client_secret_basic MUST be used.

The Supported options are:

client_secret_basic

Clients in possession of a client password authenticate with the Authorization Server in accordance with section 3.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0] using HTTP Basic authentication scheme.

client_secret_post

Clients in possession of a client password authenticate with the Authorization Server in accordance with section 3.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0] by including the client credentials in the request body.

client_secret_jwt

Clients in possession of a client password create a JWT using the HMAC-SHA algorithm. The HMAC (Hash-based Message Authentication Code) is calculated using the client_secret as the shared key. The client Authenticates in accordance with section 2.2 of (JWT) Bearer Token Profiles (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” December 2011.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Mortimore, C., Ed., Campbell, B., Jones, M., and Y. Goland, “OAuth 2.0 Assertion Profile,” October 2011.) [OAuth.Assertions]. The JWT MUST contain the Claims:

iss

REQUIRED. The iss (issuer) Claim. This MUST contain the client_id of the OAuth Client.

prn

REQUIRED. The prn (principal) Claim. This MUST contain the client_id of the OAuth Client.

aud

REQUIRED. The aud (audience) Claim. A value that identifies the Authorization Server as the intended audience. The Authorization Server MUST verify that it is an intended audience for the token. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.

jti

REQUIRED. The jti (JWT ID) Claim. A unique identifier for the token. The JWT ID MAY be used by implementations requiring message de-duplication for one-time use assertions.

exp

REQUIRED. The exp (expiration) Claim that limits the time window during which the JWT can be used.

iat

OPTIONAL. The iat (issued at) Claim that identifies the time at which the JWT was issued.

The authentication token MUST be sent as the value of the client_assertion parameter.

The value of the client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".

private_key_jwt

Clients that have registered a public key sign a JWT using the RSA algorithm if a RSA key was registered or the ECDSA algorithm if an Elliptic Curve key was registered. The Client Authenticates in accordance with section 2.2 of (JWT) Bearer Token Profiles (Jones, M., Campbell, B., and C. Mortimore, “JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0,” December 2011.) [OAuth.JWT] and OAuth 2.0 Assertion Profile (Mortimore, C., Ed., Campbell, B., Jones, M., and Y. Goland, “OAuth 2.0 Assertion Profile,” October 2011.) [OAuth.Assertions]. The JWT MUST contain the Claims:

iss

REQUIRED. The iss (issuer) Claim. This MUST contain the client_id of the OAuth Client.

prn

REQUIRED. The prn (principal) Claim. This MUST contain the client_id of the OAuth Client.

aud

REQUIRED. The aud (audience) Claim. A value that identifies the Authorization Server as the intended audience. The Authorization Server MUST verify that it is an intended audience for the assertion. The Audience SHOULD be the URL of the Authorization Server's Token Endpoint.

jti

REQUIRED. The jti (JWT ID) Claim. A unique identifier for the token. The token ID MAY be used by implementations requiring message de-duplication for one-time use assertions.

exp

REQUIRED. The exp (expiration) Claim that limits the time window during which the JWT can be used.

iat

OPTIONAL. The iat (issued at) Claim that identifies the time at which the JWT was issued.

The authentication token MUST be sent as the value of the client_assertion parameter.

The value of the client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".

For example:

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

grant_type=authorization_code&
code=i1WsRn1uB1&
client_id=s6BhdRkqt3&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=PHNhbWxwOl...[omitted for brevity]...ZT

2.2.2.  Access Token Request

The Client obtains an Access Token by authenticating with the Authorization Server and presenting its access grant (in the form of an Authorization Code, or Refresh Token).

In addition to the Client authentication parameters, if this is a Refresh Token Request, the Client MUST send the additional parameters specified in Section 6 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0]. Otherwise the Client MUST send the request parameter for the Access Token Endpoint as specified in section 4.1.3 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0].

2.2.3.  Access Token Response

After receiving and verifying 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 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0].

This specification further constrains that only Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.) [OAuth.Bearer] are issued at the Token Endpoint. The OAuth 2.0 response parameter "token_type" MUST be set to "Bearer".

In addition to the OAuth 2.0 response parameters, the following parameters MUST be included in the response if the Authorization Request scope parameter contains openid:

id_token

The ID Token value associated with the authentication session.

Following is a non-normative example:

{
 "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 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0], Clients SHOULD ignore unrecognized response parameters.

2.2.4.  Token Error Response

If the token request is invalid or unauthorized, the Authorization Server constructs the error response. The parameters of the Token Error Response are defined as in Section 5.2 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth2.0].

2.3.  Check ID Endpoint

The Check ID Endpoint validates ID Tokens and returns a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] object that contains Claims about the authentication event associated with the supplied ID Token.

Clients MUST not send encrypted ID Token to the Check ID Endpoint. If the Client registers id_token_encrypted_response_algs during OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2011.) [OpenID.Registration], the Client must decrypt the ID Token, and SHOULD directly verify the ID Token per ID Token Verification (ID Token Verification).

This endpoint can be used by Clients that are not able to or do not wish to directly handle ID Tokens. In such cases, Clients MAY treat the ID Token as an opaque value, and use the Check ID Endpoint to retrieve and examine the Claims associated with the ID Token.

2.3.1.  Check ID Request

To request the information about the authentication performed on the End-User, Clients MAY send requests with the following parameter to the Check ID Endpoint:

access_token

REQUIRED. The ID Token obtained from an OpenID Connect Authorization Request.

2.3.2.  Check ID Response

The response is a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] object containing the ID Token (ID Token) Claims.

Other Claims MAY be requested by specifying the desired ID Token Claims to be returned in an OpenID Request Object (OpenID Request Object) when making an Authorization Request.

The content-type of the response where applicable MUST be set to application/json.

2.3.3.  Check ID Error Response

When an error occurs, an error response is returned with an error code defined in Section 3.1 of OAuth 2.0 Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.) [OAuth.Bearer].

2.4.  UserInfo Endpoint

The UserInfo Endpoint is a Protected Resource that returns Claims about the authenticated End-User. Claims are represented by a JSON object that contains a collection of name and value pairs for the 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.

access_token

REQUIRED. The Access Token obtained from an OpenID Connect Authorization Request.

schema

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

id

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

2.4.2.  UserInfo Response

If the requested schema is openid, the response MUST return a JSON object that contains the full set or a subset of the Claims that are defined below. Additional Claims (not specified below) MAY also be returned.

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., familyName#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 familyName#ja-Hani-JP.

For privacy reasons, OpenID Providers MAY elect to not provide values for some schema elements as part of the openid scope.

The user_id Claim in the UserInfo Endpoint response MUST exactly match the user_id Claim in the ID Token, before using additional UserInfo Endpoint Claims.

The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2011.) [OpenID.Registration]. The UserInfo Endpoint MAY return Claims in JWT format, which can be signed and/or encrypted. The UserInfo Endpoint MUST return a content-type header to indicate the format that is being returned. The following are accepted content types:

The following is a non-normative example of such a response:

{
 "user_id": "248289761001",
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "email": "janedoe@example.com",
 "picture": "http://example.com/janedoe/me.jpg"
}

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

The 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

The 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

The city or locality component.

region

The state, province, prefecture or region component.

postal_code

The zip code or postal code component.

country

The country name component.

2.4.3.  UserInfo Error Response

When an error condition occurs, the UserInfo Endpoint returns an Error Response. In addition to the error codes defined in section 3.1 of OAuth 2.0 Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.) [OAuth.Bearer], this specification defines the following error codes:

invalid_schema

The requested schema is invalid or unsupported.

2.5.  Claim Types

The UserInfo Endpoint MAY return the following three types of Claims:

Normal Claims

Claims that are directly asserted by the OpenID Provider.

Aggregated Claims

Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned by OpenID Provider.

Distributed Claims

Claims that are asserted by a Claims Provider other than the OpenID Provider but are returned as references by the OpenID Provider.

The UserInfo endpoint MUST support normal Claims.

Aggregated and Distributed Claims support is OPTIONAL.

2.5.1.  Normal Claims

Normal Claims are represented as members in a JSON object. The Claim Name is the member name and the Claim Value is the member value.

The following is a non-normative normal Claims response:

{
 "name": "Jane Doe"
 "given_name": "Jane",
 "family_name": "Doe",
 "email": "janedoe@example.com",
 "picture": "http://example.com/janedoe/me.jpg"
}

2.5.2.  Aggregated and Distributed Claims

Aggregated and distributed Claims are represented by using special _claim_names and _claim_sources members of the JSON object containing the Claims.

_claim_names

This value is a JSON object whose member names are the Claim Names for the Aggregated and Distributed Claims. The member values are references to the member names in the _claim_sources member from which the actual Claim Values can be retrieved.

_claim_sources

This value is a JSON object whose member names are referenced by the member values of the _claim_names member. The member values contain sets of Aggregated Claims or reference locations for Distributed Claims. The member values can have one of the following formats depending on whether it is providing Aggregated or Distributed Claims:

Aggregated Claims

A JSON object that MUST contain the JWT member whose value is a JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] that MUST contain all the Claims in the _claim_names object that references the corresponding _claim_sources member. Other members MAY be present if they are understood by both parties.

JWT

REQUIRED. JWT Value.

Distributed Claims

A JSON object that contains the following members and values:

endpoint

REQUIRED. The value is the OAuth 2.0 resource endpoint from which the associated Claim can be retrieved. The endpoint URL MUST return the Claim as a JWT.

access_token

OPTIONAL. Access Token enabling retrieval of the Claims from the endpoint URL by using the OAuth 2.0 Bearer (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.) [OAuth.Bearer] scheme. Claims SHOULD be requested using the Authorization Request header field and Claims Sources MUST support this method. If the Access Token is not available, Clients MAY need to retrieve the Access Token out of band or use an a priori Access Token that was negotiated between the Claim Source and Client, or the Claim Source MAY reauthenticate the End-User and/or reauthorize the Client.

Other members MAY be present, if understood by both parties.

The following is a non-normative response with Aggregated Claims:

Claims Provider A contains the following Claims for Jane Doe:
{
 "address": {
   "street_address": "1234 Hollywood Blvd.",
   "locality": "Los Angeles",
   "region": "CA",
   "postal_code": "90210",
   "country": "US"},
 "phone_number": "+1 (310) 123-4567"
}

Claims Provider A signs the JSON Claims, resulting in a signed JWT:
jwt_header.jwt_part2.jwt_part3

Authorization Server returns Jane Doe's aggregated Claims from Claims Provider A:
{
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "birthday": "01/01/2001",
 "eye_color": "blue",
 "email": "janedoe@example.com",
 "_claim_names": {
  "address": "src1",
  "phone_number": "src1"
 },
 "_claim_sources": {
  "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"}
 }
}

The following is a non-normative response with Distributed Claims:

Claims Provider A (Jane Doe's Bank) contains the following Claims for Jane Doe:
{
 "shipping_address": {
   "street_address": "1234 Hollywood Blvd.",
   "locality": "Los Angeles",
   "region": "CA",
   "postal_code": "90210",
   "country": "US"},
 "payment_info": "Some_Card 1234 5678 90123 4562",
 "phone_number": "+1 (310) 123-4567"
}

A Claims Provider B (Credit Agency) contains the following Claims for Jane Doe:
{
 "credit_score": "650"
}

Authorization Server returns Jane Doe's Claims along with the Distributed Claims from
Claims Provider A and B by sending the Access Tokens and URL locations where the Claims
may be retrieved:
{
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "email": "janedoe@example.com",
 "birthday": "01/01/2001",
 "eye_color": "blue",
 "_claim_names": {
  "payment_info": "src1",
  "shipping_address": "src1",
  "credit_score": "src2"
 },
 "_claim_sources": {
  "src1": {"endpoint": "https://bank.example.com/claimsource"},
  "src2": {"endpoint": "https://creditagency.example.com/claimshere", "access_token": "ksj3n283dke"}
 }
}

3.  Serializations

Parameter names and values MAY be JSON serialized into a JSON structure.

3.1.  JSON Serialization

The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. Each parameter MAY have JSON Structure as its value.

Following is a non-normative example of such serialization:

{
 "access_token":"SlAV32hkKG",
 "expires_in":3600,
 "refresh_token":"8xLOxBtZp8"
}

4.  Signatures and Encryption

Depending on the transport through which the messages are sent, the integrity of the message may not be guaranteed and the originator of the message may not be authenticated. To mitigate these risks, OpenID Connect messages MAY utilize JSON Web Signature (JWS) (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] to sign the content.

To achieve message confidentiality, OpenID Connect messages MAY use JSON Web Encryption (JWE) (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] to encrypt the content.

When the message is both signed and encrypted, it MUST be signed first then encrypted (Signing and Encryption order).

4.1.  Supported Algorithms

The server advertises its supported signing and encryption algorithms in its discovery document. The related elements are:

userinfo_algs_supported

A JSON array containing a list of the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] signing and encryption algorithms supported by the UserInfo Endpoint.

id_token_algs_supported

A JSON array containing a list of the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] signing and encryption algorithms supported by the Authorization Server for the ID Token.

request_object_algs_supported

A JSON array containing a list of the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] and JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] signing and encryption algorithms supported by the Authorization Server for the OpenID Request Object (OpenID Request Object). Servers SHOULD support HS256.

token_endpoint_auth_algs_supported

A JSON array containing a list of the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signing algorithms supported by the Token Endpoint for the private_key_jwt method. Servers SHOULD support RS256.

The Client registers its required algorithms for Signing and Encryption using the following Registration parameters:

require_signed_request_object

OPTIONAL. The JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signature algorithm that MUST be required by the Authorization Server. All OpenID Request Objects from this client_id MUST be rejected if not signed by this algorithm.

userinfo_signed_response_algs

OPTIONAL. The JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signature algorithm required for userinfo responses. If this is specified the response will be JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] serialized.

userinfo_encrypted_response_algs

OPTIONAL. A space separated list of the JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] alg and enc algorithms required for userinfo responses. If this is requested in combination with signing, the response MUST be signed first then encrypted (Signing and Encryption order). If this is specified, the response will be JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] serialized.

id_token_signed_response_algs

OPTIONAL. The JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signing algorithm required for id_token issued to this client_id. The default if not specified is HS256 using the provided client_secret as the shared key.

id_token_encrypted_response_algs

OPTIONAL. A space separated list of the JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] alg and enc algorithms required for id_token issued to this client_id. If this is requested the response MUST be signed then encrypted. The default if not specified is no encryption.

4.2.  Keys

The Server advertises its supported signing and encryption algorithms in its discovery document. The related elements are:

The Provider provides its public Keys during Discovery in the following elements:

jwk_url

URL of the OP's JSON Web Key (Jones, M., “JSON Web Key (JWK),” December 2011.) [JWK] document that contains the Server's signing key that is used for JWS signing the JWT. It MAY also be used by the Client to JWE encrypt the JWT to the Server if x509_encryption_url or jwk_encryption_url is not specified, but this is discouraged. A separate encryption key SHOULD be used.

jwk_encryption_url

URL of the OP's JSON Web Key (Jones, M., “JSON Web Key (JWK),” December 2011.) [JWK] document that contains the Server's encryption key that is used by the Client to JWE encrypt the JWT to the Server. If it is not present, its value is the same as the URL provided by jwk_url.

x509_url

URL of the OP's X.509 certificates in PEM format that are used by the Server for Signing the JWT. It MAY also be used by the Client to JWE Encrypt the JWT to the Server if x509_encryption_url is not specified and the key usage includes keyEncipherment.

x509_encryption_url

URL of the OP's X.509 certificates in PEM format that contains the Server's encryption key that is used by the Client to JWE encrypt the JWT to the Server. If it is not present, the URL provided by the x509_url is used instead. The certificate MUST include keyEncipherment in the key usage.

The Client provides its public Keys during Registration, in the following elements:

jwk_url

OPTIONAL. URL for the Client's JSON Web Key (Jones, M., “JSON Web Key (JWK),” December 2011.) [JWK] document that is used for JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signing of the Request Objects. If jwk_encryption_url is not provided, it is also used by the Server for JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] encryption of JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] to the Client.

jwk_encryption_url

OPTIONAL. URL for the Client's JSON Web Key (Jones, M., “JSON Web Key (JWK),” December 2011.) [JWK]. It is used by the Server for JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] encryption of the response objects.

x509_url

OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain. It is used by the Client for JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] signing of the request objects. If x509_encryption_url is not present, it is also used for JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] encryption of the JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] to the Client if the key usage includes keyEncipherment.

x509_encryption_url

OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain, used for JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] encryption of JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] to the Client.

If keys are specified in both x509 and jwk, they MUST be the same keys.

Key algorithms like Elliptic Curve signing and key agreement require separate keys for signing and encryption for security. For RSA a single key MAY be used for both, but it is good practice to separate them.

4.3.  Signing

The signing party MUST select a signature algorithm based on the supported algorithms of the recipient in Section 4.1 (Supported Algorithms).

Symmetric Signatures

When using HMAC Signatures, the alg Claim of the JWS header MUST be set to the appropriate algorithm as defined in JSON Web Signature (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS]. The client_secret MUST be used as the signature key.

Asymmetric Signatures

When using RSA or ECDSA Signatures, the alg Claim of the JWS header MUST be set to the appropriate algorithm as defined in JSON Web Signature (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS]. The private key MUST be the one associated with the Public Signing Key provided in Section 4.2 (Keys). If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWS header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. The key usage of the respective keys MUST include signature. In particular, if the key found through x5u is used, the key usage MUST include digitalSignature.

4.4.  Encryption

The encrypting party MUST select an encryption algorithm based on the supported algorithms of the recipient in Section 4.1 (Supported Algorithms).

All JWT MUST be signed before encryption to provide integrity and to verify the Issuer.

Symmetric Encryption algorithms that provide an integrated integrity check MUST be used if supported by both the sender and receiver. The A128GCM and A256GCM algorithms support this.

Symmetric Encryption

Use the client_secret to KeyWrap a random Content Encryption Key to be used for encrypting the signed JWT.

Asymmetric Encryption RSA

Use the link registered/discovered in Section 4.2 (Keys) to retrieve the relevant key. The jwk_encryption_url or x509_encryption_url link MUST be used if provided. If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWS header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. Use the supported RSA KeyWrap algorithm to KeyWrap a random Content Encryption Key to be used for encrypting the signed JWT. The key usage of the respective keys MUST include encryption. In particular, if the key found through x5u is used, the key usage MUST include keyEncipherment.

Asymmetric Encryption Elliptic Curve

Create an ephemeral Elliptic Curve public key for the epk element of the JWE header. Use the link registered/discovered in Section 4.2 (Keys) to retrieve the relevant key. The jwk_encryption_url or x509_encryption_url link MUST be used if provided. If there are multiple keys in the referenced JWK document, the kid MUST be specified in the JWE header. If there are multiple certificates at the referenced certificate location, then x5t MUST be specified in the JWS header. Use the ECDH-ES algorithm to KeyWrap a random Content Encryption Key to be used for encrypting the signed JWT. The key usage of the respective keys MUST include encryption. In particular, if the key found through x5u is used, the key usage MUST include keyEncipherment.

5.  Verification

5.1.  Authorization Request Verification

Authorization Request Verification consists of two main steps. (1) Encryption and Signature validation of the value of request or the content of request_uri, (2) Parameter verification.

If an OpenID Request Object was sent in the request parameter or by reference in the request_uri parameter, the Request Object MUST verify as JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] or JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] objects that are encoded in the JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT].

5.1.1.  Encrypted Request Object

If the Authorization Server has advertised JWE encryption algorithms in the request_object_algs_supported element of its Discovery Document, these are used by the Client to JWE encrypt the JWT.

The Authorization Server MUST decode the JWT in accordance with JSON Web Encryption (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] specification. The result MAY be either OpenID Request Object or a JWS Signed JWT. In the latter case, the signature verification MUST be performed as defined in Signed Request Object (Signed Request Object).

The Authorization Server MUST return the error if there is a decryption error.

5.1.2.  Signed Request Object

To perform Signature Verification, the alg parameter in the JWT header MUST match the value of the require_signed_request_object set during Client Registration (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2011.) [OpenID.Registration] or otherwise pre-registered value.

The signature must be validated against the key registered for that client_id and algorithm, in accordance with the JSON Web Signature (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] specification.

The Authorization Server MUST return the error authorization response if there is a signature validation error.

5.1.3.  Parameter Verification

The Authorization Server MUST construct the Authorization Request Message from the OpenID Request Object and other parameters. Note that if the same parameter exists both in the OpenID Request Object and other parameters, the former takes precedence. Using this Authorization Request Message, the Authorization Server performs the following steps of the request verification:

1. The Authorization Server MUST understand all the parameters except for the unsupported Claims. If there is any parameters that it does not understand except for the unsupported Claims, it MUST return an error response.
2. The Authorization Server MUST verify that all the OAuth 2.0 variables according to OAuth 2.0.
3. The Authorization Server MUST verify that all the required parameters are present.
4. If the user_id Claim as a member of id_token element is requested with a specific value, the Authorization Server MUST only send a positive response if that user has an active session with the authorization server. The Authorization server MUST not reply with an ID Token or Access Token for a different user, even if they have an active session with the Authorization Server.
5. If the acr Claim is requested as a required Claim in the id_token member with values as a parameter, the Authorization Server MUST return an acr Claim value that matches one of the requested values. The Authorization server MAY ask the user to re-authenticate with additional factors to meet the requirements. If this is a required Claim and the requirement cannot be met, then the Authorization Server MUST return an error. The Client MAY make this Claim optional by including "optional": true in the acr Claim request. If the Claim is optional and the requested value for the user cannot be provided, the Authorization server SHOULD return the session's current acr as the value of the acr Claim. If the Claim is optional, the Authorization server is not required to provide this Claim in its response.

If the Authorization Server encounters any error, it MUST return the error response.

5.2.  ID Token Verification

To verify the validity of ID Token in the Authorization or Token Endpoint Response, the Client MUST do the following:

1. If the Client has provided an id_token_encrypted_response_algs parameter during Registration, decrypt the id_token (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE], using the key pair specified during Registration.
2. The Client MUST validate that the client_id in the aud (audience) Claim is one it has registered for the Issuer identified by the value in the iss (issuer) Claim. The ID Token MUST be rejected if the value of aud (audience) is not valid for the Issuer.
3. The Client MUST verify the ID Token signature according to Section 5 of JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS] using the algorithm specified in the alg parameter of the JWT header.
4. The value of alg SHOULD be the algorithm sent by the Client in the id_token_signed_response_algs parameter during Registration.
5. If the alg parameter of the JWT header is one of HS256, HS384, or HS512, the client_secret for the client_id contained in the aud (audience) Claim is used to validate the signature.
6. For other Signing algorithms the Client must use the signing key provided in Discovery by the Issuer exactly matching the value of the iss (issuer) Claim.
7. The current time MUST be less than the value of the exp Claim.
8. 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.
9. 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.
10. 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.

5.3.  Check ID Request Verification

The Authorization Server MUST check that the access_token is present in the request and if it is signed, it MUST verify the signature according to Section 5 of JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS].

If the JWS algorithm is symmetric, such as the default HS256 for id_token, the client_secret for the client_id contained in the aud (audience) Claim MUST be used to validate the signature.

The Authorization Server MUST check that the id_token provided as the access_token contains all REQUIRED Claims.

5.4.  Check ID Response Verification

If the Client does not directly verify the ID Token signature, it MUST make a request to the Check ID Endpoint to validate the ID Token.

To verify the validity of the Token response, the Client MUST do the following:

1. Check that the OP that responded was really the intended OP.
2. The Client MUST validate that the client_id in the aud (audience) Claim is one it has registered for the Issuer identified by the value in the iss (issuer) Claim. The ID Token MUST be rejected if the value of aud (audience) is not valid for the Issuer.
3. The value of the iss (issuer) Claim must match the Issuer for the Check ID Endpoint"
4. The current time MUST be less than the value of the exp Claim.
5. 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.
6. 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.
7. 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.
8. The Check ID Endpoint has not returned an error for the ID Token being expired or invalid.
9. Check that the iss (issuer) is equal to that of the pre-configured or discovered Issuer Identifier for the user session.

5.5.  UserInfo Response Verification

To verify the validity of the UserInfo response, the Client MUST do the following:

1. If the Client has provided a userinfo_encrypted_response_algs parameter during Registration, decrypt the id_token (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE], using the key pair specified during Registration.
2. If the response was signed, the Client SHOULD validate the signature according to Section 5 of JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS].
3. Check that the OP that responded was really the intended OP through a TLS/SSL server certificate check, per RFC 6125 (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS),” March 2011.) [RFC6125].

6.  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 user_id. 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.

7.  Related Specifications

This specification is an abstract specification. It needs to be bound to a protocol to be used in practice. One such example of protocol binding is:

• OpenID Connect Standard 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Standard 1.0,” December 2011.) [OpenID.Standard] - Protocol binding for the full set of OpenID Connect messages

These related OpenID Connect specifications MAY OPTIONALLY be used in combination with this specification to provide additional functionality:

• OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” December 2011.) [OpenID.Discovery] - Dynamic discovery for user and Authorization Server endpoints and information
• OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2011.) [OpenID.Registration] - Dynamic registration of OpenID Connect Clients with OpenID Providers
• OpenID Connect Basic Client 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Basic Client 1.0,” December 2011.) [OpenID.Basic] - Protocol binding for a subset of the OpenID Connect Messages that is intended for use by basic Relying Parties.
• OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” December 2011.) [OpenID.Session] - Session management for OpenID Connect sessions

8.  Security Considerations

OAuth 2.0 Threat Model and Security Considerations (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2011.) [OAuth.Threat] provides an extensive list of threats and controls that applies to this standard as well. In addition, this standard provides additional control measures listed below.

8.1.  Request Disclosure

If appropriate measures are not taken, a request may be disclosed to an attacker posing security and privacy threat.

In addition to what is stated in section 5.1.1 of the [OAuth.Threat] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2011.), this standard provides a way to provide the confidentiality of the request end to end through the use of request or request_uri parameters, where the content of the request is an encrypted JWT with the appropriate key and cipher. This works even against a compromised user-agent in the case of indirect request.

8.2.  Server Masquerading

A malicious Server may masquerade as the legitimate server using various means. To detect such an attack, the Client needs to authenticate the server.

In addition to what is stated in section 5.1.2 of the [OAuth.Threat] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” October 2011.), this standard provides a way to authenticate the Server through either the use of Signed or Encrypted JWT (JWS and JWE) with an appropriate key and cipher.

8.3.  Token Manufacture/Modification

An Attacker may generate a bogus token or modify the token content (such as the authentication or attribute statements) of an existing parseable token, causing the RP to grant inappropriate access to the Client. For example, an Attacker may modify the parseable token to extend the validity period; a Client may modify the parseable token to have access to information that they should not be able to view.

There are two ways to mitigate this attack:

1. The token can be digitally signed by the OP. The Relying Party SHOULD check the digital signature to verify that it was issued by a legitimate OP.
2. The token can be sent over a protected channel such as 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.). In order to protect the integrity of the token from malicious attack, the Server MUST be authenticated, per RFC 6125 (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS),” March 2011.) [RFC6125]. In this specification, the token is always sent over TLS/SSL protected channel. Note however, that this measure is only applicable to the third party attacker and is not applicable to the case where the Client is the attacker.

8.4.  Server Response Disclosure

Server response may contain authentication and attribute statements that include sensitive Client information. Disclosure of the response contents can make the Client vulnerable to other types of attacks.

The server response disclosure can be mitigated in the following two ways:

1. Using the code response type. The response is sent over a TLS/SSL protected channel, where the Client is authenticated by the client_id and client_secret.
2. For other response types, the signed response can be encrypted with the Client's public key or a shared secret as an encrypted JWT (JWE) with an appropriate key and cipher.

8.5.  Server Response Repudiation

A response may be repudiated by the server if the proper mechanisms are not in place. For example, if a Server does not digitally sign a response, the Server can claim that it was not generated through the services of the Server.

To mitigate this threat, the response may be digitally signed by the Server using a key that supports non-repudiation. The Client SHOULD check the digital signature to verify that it was issued by a legitimate Server and the integrity is intact.

8.6.  Request Repudiation

Since it is possible for a compromised or malicious Client to send request to a wrong party, a Client that was authenticated using only a bearer token can repudiate any transaction.

To mitigate this threat, the Sever MAY require that the request to be digitally signed by the Client using a key that supports non-repudiation. The Server SHOULD check the digital signature to verify that it was issued by a legitimate Client and the integrity is intact.

8.7.  Access Token Redirect

An Attacker uses the access token generated for one resource to obtain access to a second resource.

To mitigate this threat, the access token should be audience and scope restricted. One way of implementing it is to include the identifier of the resource for whom it was generated as audience. The resource verifies that incoming tokens include its identifier as the audience of the token.

8.8.  Token Reuse

An Attacker attempts to use a one-time use token such as an Authorization Code that has been used once with the intended Resource.

To mitigate this threat, the token SHOULD include a timestamp and a short lifetime of validity. The Relying Party checks the timestamp and lifetime values to ensure that the token is currently valid.

Alternatively, the server may record the state of the use of the token and check the status for each request.

8.9.  Eavesdropping or leaking authorization codes (Secondary Authenticator Capture)

In addition to the attack patterns described in 4.4.1.1 of OAuth SC, it can be captured in the User-Agent where the TLS session is terminated if the User-Agent is infested by malware.

However, capturing it is not useful as long as the profile uses either Client authentication or the Response encryption.

8.10.  Token Substitution

A user may attempt to impersonate a more privileged user by subverting the communication channel between the Token Endpoint and Client, for example by reordering the messages, to convince the Token Endpoint that his or her authorization grant corresponds to the grant sent on behalf of the more privileged user.

Responses to token requests is bound to the corresponding requests by message order in HTTP, as both token and requests are protected by TLS that can detect and disallow malicious reordering of packets.

8.11.  Timing Attack

Timing attack is an attack that allows the attacker to obtain unnecessary large amount of information through the elapse time difference in the code path taken by a successful decryption and unsuccessful verification of signed message. It can be used to reduce the effective key length of the cipher used.

Implementations should not terminate the verification process at the instance of the finding error but should continue running until all the octets were processed to avoid this attack.

8.12.  Other Crypto Related Attacks

There are various crypto related attacks possible depending on the method used for encryption and signature / integrity checking.

Implementation should consult the security consideration around the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.) [JWS], JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] and JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.) [JWT] to avoid the vulnerability around these specifications.

8.13.  Signing and Encryption order

Signatures over encrypted text are not considered valid in many jurisdictions. For the integrity of non-repudiation this specification requires signing of the plain text JSON.

It is however strongly RECOMMENDED that the selected Encryption algorithm include integrity to protect against padding oracle and other decryption attacks.

Implementation should consult the security consideration around the JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.) [JWE] to avoid the vulnerability around these specifications.

8.14.  Issuer Identifier

OpenID Connect supports a single issuer per Host and Port combination.

It is RECOMMENDED that only a single issuer per host be used. Simple Web Discovery treats the path component of any URI as part of the user identifier.

8.15.  TLS Requirements

Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 [RFC5246] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) is the most recent version, but has very limited actual deployment, and might not be readily available in implementation toolkits. TLS version 1.0 [RFC2246] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) is the most widely deployed version, and will give the broadest interoperability.

To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.

9.  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_uris.

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 user_id SHOULD be considered.

9.1.  Refresh Token, and Access Token Lifetime

Access Token grants are not revocable by the Authorization Server. Access Token grant lifetimes SHOULD be kept to single use or very short lifetimes.

If access to the User Info Endpoint or other protected resources is required, a Refresh Token should be used. The Client may then exchange the Refresh Token at the Token Endpoint for a fresh short lived Access Token, that can be used to access the resource.

The Authorization Server SHOULD clearly identify long term grants to the User during Authorization.

The Authorization Server MUST provide a mechanisim for the user to revoke Refresh Tokens granted to a Client.

10.  IANA Considerations

This document makes no requests of IANA.

11.  References

11.1. Normative References

11.2. Informative References

Appendix A.  Acknowledgements

As a successor version of OpenID, this specification heavily relies on OpenID Authentication 2.0 (specs@openid.net, “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.

This specification is largely compliant with OAuth 2.0 draft 20. Please refer to the OAuth 2.0 specification for the list of contributors.

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.

Anthony Nadalin (tonynad@microsoft.com), Microsoft

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

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

Casper Biering (cb@peercraft.com), Peercraft

Chuck Mortimore (cmortimore@salesforce.com), Salesforce

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

Chuck Mortimore (cmortimore@salesforce.com), Salesforce.com

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

Johnny Bufu (jbufu@janrain.com), Janrain

John Bradley (jbradely@mac.com), Independent

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 Itou (ritou@yahoo-corp.jp), Yahoo! Japan

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

Appendix B.  Notices

Copyright (c) 2011 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 (i) solely for the purposes of developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to OIDF as the source of the material, but that such attribution does not indicate the endorsement by 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. OpenID 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 ]]

-07

• Removed definition and usage for assertion and claim object
• Consistent use of End-User
• Removed 'format' from userinfo and id_token object of the OpenID Request Object
• email scope allows access to the 'verified' claim
• ID Token 'audience' claim MUST be client_id
• Rename artifact to authorization code
• Removed language pertaining to custom userinfo schemas
• Check ID Endpoint returns only JSON
• Updated Check ID Response verification
• Remove 'audience' parameter from Authorization Request
• Moved display=none to prompt=none
• Added additional display parameter options
• Moved IANA considerations to Standard
• Added error codes to Authorization Endpoint
• Added client authentication section regarding various supported client authentication schemes and their validation. This includes symmetric and asymmetric authentication, JWT Bearer Token Profiles, OAuth 2.0 Assertion Profile
• Updated Check ID Response verification
• Added 'auth_time' to ID Token
• Added validation for request object encryption and signature
• Added explanation for user_id type and calculating pairwise identifiers
• Added steps for signature and validation and encryption and decryption
• Added verification of issuer identifier
• Redefined 'nonce' in Authorization Request. Changed to REQUIRED parameter.
• Changed usage of the word "approval" to "consent"
• Use RFC 6125 to verify TLS endpoints
• ID Token MUST be JWT
• Access Tokens should include an audience claim for the Resource Server
• Updated Security Considerations
• OpenID Request Object parameters takes precedence over the same parameters in the Authorization Request
• Allow other gender strings in UserInfo schema
• Changed UserInfo claim 'locale' to 'preferred_locales' and changed it to be a list of values
• Changed UserInfo claim 'user_id' to REQUIRED. Added requirement to compare user_id from userinfo endpoint to id_token
• RECOMMENDED E.164 format for UserInfo 'phone_number' claim
• Changed UserInfo Error Response to augment and return OAuth 2.0 Bearer Token Error Response
• Expanded section regarding UserInfo 'address' claim
• Added Privacy considerations
• Added rational for signing then encrypting added to security considerations
• Added section about string comparison rules needed
• The Authorization Server MUST understand all the request parameters except for the unsupported claims.
• Make openid scope provide user_id from userinfo endpoint
• Added explanation of select_account
• Check ID Endpoint uses ID Token as Access Token according to Bearer Token spec
• Clients MUST verify client_id in ID Token
• Bumped version + date
• Update John Bradley email and affiliation for Implementer's Draft
• Removed invalid_authorization_code, invalid_id_token error codes
• Section 2.3 client MUST NOT send encrypted JWT to the Check ID Endpoint
• Section 2.1.2.1.2 Added user_id claim and moved iso29115 to claims element of id_token member
• Defined Authentication Context, Authentication Context Class Reference (acr), replaced iso29115 with acr.
• Corrected instances of x509_url_encryption to x509_encryption_url and jwk_url_encryption to jwk_encryption_url

-06

• Changed section 3.1.4.1 to say the errors are returned as defined by the response type not always as query parameters. per ticket #174.
• Bumped version + date.
• Fixed section 3.3.3 to refer to errors in Bearer Token.
• Fixed 3.1.3 to ref the other response types ticket #173.
• Included reference to multiple response types.
• Fixed 3.1.2.1 to indicate default Claims in id_token.
• Fixed section 3.2.2 to reference the access token response from the token endpoint 4.1.4.
• Fixed section 3.2.1 to include refresh tokens.
• Fixed section 3.1.1 to be clear on JWT being the token format per ticket #171.

-05

• Changed check_session to check_id.
• schema=openid now required when requesting UserInfo.
• Removed issued_to, since not well defined.
• Removed display values popup, touch, and mobile, since not well defined.

-04

• Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard".
• Numerous cleanups, including updating references.

-03

• Added secret_type to the Token endpoint.
• Minor edits to the samples.

-02

• Incorporates feedback from Nat Sakimura.

-01

• First Draft that incorporates the merge of the Core and Framework specs.

Authors' Addresses