Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp

Protiviti Government Services

jbradley@mac.com

Microsoft Corporation

mbj@microsoft.com

Google

breno@google.com

Salesforce

cmortimore@salesforce.com

MGI1

ejay@mgi1.com

This document describes the more advanced request and response formats for OpenID Connect. 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.

The OpenID Connect Core 1.0.0 specification defines the basic requests and responses in allow easy and simple implementations and conformance. This specification defines various optional parts of OpenID Connect that use more complex requests and responses.

The terms used in this specification are defined in OpenID Connect Core 1.0.

This specification introduces some new parameters to the OpenID Connect Core Authorization Request.

Section 4.1.1 and 4.2.1 of OAuth 2.0 defines OAuth Authorization Request parameters. The following extension parameters are defined: OPTIONAL. A JWT encoded OpenID Request Object. OPTIONAL. A URL that points to the OpenID Request Object.

Following is a non-normative example when they are sent using the query parameters serialization:

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 claim set, as defined in the OpenID UserInfo 1.0 specification. If present, the OpenID Request object is passed as the value of a "request" OAuth 2.0 parameter and is represented as a JWT. Parameters that affect the information returned from the UserInfo endpoint are in the "userinfo" member. Parameters that affect the information returned in an ID Token are in the "id_token" member. If the same parameters are available both as query strings and in the OpenID Request Object, the later takes the precedence.

An example an OpenID request object is as follows:

The OpenID Request object is a JWT that MAY contain a set of members defined by this specification and MAY contain other members that are not defined by this specification. The JWT MAY be signed or unsigned. When it is unsigned, it will be indicated by the JWT "signed":"none" convention in the JWT header. The members defined by this specification are: 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. OPTIONAL. (ID request): Requests affecting the values to be included in the ID Token. If not present, the default ID Token contents are used. If present, these parameters are used to request deltas to the default contents of the ID Token. If signed, the OpenID Request object SHOULD contain the standard JWT "iss" and "aud" claims. All members of the OpenID Request object are OPTIONAL. Other members MAY be present and if so, SHOULD be understood by both parties.

The structure of the "userinfo" (UserInfo request) member is a JSON object that MAY contain the following members: OPTIONAL. (Requested Claims): Set of requested claims from the UserInfo endpoint. If not present, the default UserInfo claims held by the IdP are returned. OPTIONAL. (Format): The requested format for the UserInfo endpoint information. If not present, the format is an unsigned JSON object. OPTIONAL. (Locale): The default languages and scripts of the entire claim request, represented as a space-separated list of BCP47 language tags. 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: This indicates that this claim is being requested in the default manner. In particular, this is a required claim. OR 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 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. The members of the JSON object value following a claim name defined by this specification are: If this is an optional claim, this member's value MUST be true, else, if present, its value MUST be false, which indicates that it is a required 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 default claim set that would otherwise be returned from the UserInfo endpoint. The "format" member of the "userinfo" object is used to specify the requested format of the UserInfo endpoint contents. Values defined are: - in which case the contents are an unsigned JSON object - in which case the contents are a signed JWT - in which case the contents are an signed and encrypted JWT All members of the "userinfo" object are OPTIONAL. Other members MAY be present and if so, SHOULD understood by both parties.

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 "claims", "format", "locale". The same structure of these members are 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 default 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 claim MAY be requested in the ID Token by specifying it in the "claims" member: OPTIONAL. (authenticated at): Requests that the "auth_time" claim be present. The claim value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time that the user authentication occurred. (The "auth_time" claim semantically corresponds to the openid.pape.auth_time response parameter.) In addition to the "claims" member, this additional member is defined within the "id_token" member of the OpenID Request object: OPTIONAL. (max authentication age): Specifies that the 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 openid.pape.max_auth_age request parameter.) OPTIONAL. (entity authentication assurance): Specifies the X.eaa / ISO/IEC29115 entity authentication assurance level that is requested by the client. 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 openid.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 understood by both parties

Authorization responses are defined in the OpenID Connect Core specification.

If the end-user denies the access request or if the request fails, the authorization server informs the client by returning parameters defined in section 4.1.2.1 of OAuth 2.0.

The UserInfo endpoint returns claims for the authenticated user. There are three different types of claims. Claims that are directly asserted by the OpenID Provider. Claims that are asserted by a claims provider other than the OpenID Provider but are returned by OpenID Provider. 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. Claim objects contain members and member values which are the individual claims and claims values. A claim object is represented by a JSON object which contains a collection of name/value pairs for the 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.

Aggregated and distributed claims are represented within the "_claim_names" and "_claim_sources" members of the JSON object. This is a JSON object whose member names are the claims names for the aggregated and distributed claims. The member values are references to the member names in the "_claim_sources" member of the claim object from which the actual value can be retrieved. This is a JSON object whose member names are referenced by the member values of the "_claim_names" member of the claim object. 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 they're storing aggregated claims or distributed claims: A JSON object which MUST contain the "JWT" member whose value is a JWT which MUST contain all the claims in the "_claim_names" object which references the corresponding "_claim_sources" member. Other members MAY be present if they are understood by both parties. REQUIRED. JWT Value A JSON object which contains the following members and values: 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. OPTIONAL. Access token enabling retrieval of the claims from the endpoint URL by using the OAuth 2.0 BEARER scheme. Claims SHOULD be requested using the Authorization request header field and claims sources MUST support this method. Other members MAY be present, if understood by both parties

Clients MAY send requests with the following parameters to the UserInfo endpoint to obtain further information about the user. REQUIRED. The access_token obtained from an OpenID Connect authorization request. This parameter MUST NOT be sent if the access token is sent in the HTTP Authorization header. OPTIONAL. The schema in which the data is to be returned. The only predefined value is openid. If this parameter is not included, the response may be a proprietary schema to support backwards compatibility. A URL MAY be passed to define custom schemes not specified by short names. Custom scheme names and responses are out of scope for this specification. This identifier is reserved for backwards compatibility. It MUST be ignored by the endpoint if the openid schema is used.

If the requested schema is "openid", the response MUST return a plain text JSON object that contains a set of claims that are a subset of those defined below. Additional claims (not specified below) MAY also be returned. The UserInfo endpoint MUST return claims in JSON format unless a request for a different format is made by the client in the authorization request. The UserInfo endpoint MAY return claims in JWT format which can be signed or encrypted via JWS and JWE respectively. describes how to request a different format. The UserInfo endpoint MUST return a content-type header to indicate which format is being returned. The following are accepted content types: Content-Type Format Returned application/json plain text JSON object application/jwt A JWT

The following is a non-normative normal claims responses:

The following is a non-normative claims response containing aggregated and distributed claims:

In addition to the error codes defined in section 4.1.2.1 of OAuth 2.0, this specification defines the following additional error codes: The access token is not valid for the requested resource, malformed, is in an incorrect format, outside the valid scope, or expired. The requested schema is invalid or unsupported.

The introspection endpoint returns a text JSON object which contains information about the end user associated with supplied access or ID token. It is for use by clients that cannot or do not wish to handle signed tokens. Request Parameters: One of the following parameters OPTIONAL. A token obtained from the token endpoint. OPTIONAL. An ID token obtained from the authorization request. Both parameters are optional, but at least one parameter MUST be supplied. Response: The response is a text JSON object of an ID token using the "application/json" media type. If the request contains access token, the authorization server creates a version of an ID token and returns it as a JSON object. However, a session is not created. If the request contains id_token, then the server returns the text JSON object of the ID token. The following is a non-normative example of a request to the introspection endpoint:

In addition to the error codes defined in Section 5.2 of OAuth 2.0, this specification defines the following error codes. The access token is not valid for the requested resource, malformed, is in an incorrect format, outside the valid scope, or expired. The ID token is not valid for the requested resource, malformed, is in an incorrect format, or expired.

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 utilizes JSON Web Signatures (JWS). Following is the parameters for JWT. OPTIONAL. One of "JWT", "openid2json+sig". REQUIRED. One of the algorithm values specified in Table 3 of JWS Compact Serialization SHOULD BE used when passing it through query parameters, while JSON serialization SHOULD BE used when returning it in HTTP Body.

Following is a non-normative example of such signature in Compact serialization, where HS256 algorithm was used (with line breaks for display purposes only):

To achieve message confidentiality and audience restriction, OpenID Connect uses JSON Web Encryption (JWE).

If the request was signed, the Server MUST verify the signature as in JWT.

To verify the validity of the Authorization Response, the client MUST to the following: If the response was signed, the Client SHOULD verify the token signature as the first step. Check that current time is within the validity period contained within the token. Verify that the token was intended for the recipient, using the audience contained within the token. Check that OP that responded was really the intended OP through TLS/SSL server certificate check. If the client does not verify the signature, it MUST make a request to the UserInfo endpoint to validate the token.

If the request was signed, the Server MUST verify the signature as in JWS.

To verify the validity of the UserInfo response, the client MUST do the following: If the response was signed, the Client SHOULD verify the signature as in JWT as the first step. Check that the OP that it connected was really the intended OP by verifying the name in the TLS/SSL server certificate and if the endpoint is a TLS/SSL endpoint. Check if the current time is within the validity period of the JWT.

This document makes no request of IANA.

This specification references the security considerations defined in OAuth 2.0 Security Considerations. Followings are the list of attack vectors and remedies that were considered for this specification. For details of the attack vector, see .

To mitigate this attack, there are two ways to mitigate it. The assertion may be digitally signed by the OP. The Relying Party SHOULD check the digital signature to verify that it was issued by a legitimate OP. The assertion may be sent over a protected channel such as TLS/SSL. In order to protect the integrity of assertions from malicious attack, the OP MUST be authenticated. In this specification, the assertion is always sent over TLS/SSL protected channel.

The Assertion disclosure can be mitigated in the following two ways. Assertion is sent over TLS/SSL protected channel, where RP is authenticated by "client_id" and "client_secret". Signed Assertion is encrypted by the RP's public key.

To mitigate this threat, the assertion may be digitally signed by the OP using a key that supports non-repudiation. The RP SHOULD check the digital signature to verify that it was issued by a legitimate OP.

To mitigate this threat, the assertion includes the identity of the RP for whom it was generated as "client_id". The RP verifies that incoming assertions include its identity as the recipient of the assertion.

The assertion includes a timestamp and a short lifetime of validity. The Relying Party checks the timestamp and lifetime values to ensure that the assertion is currently valid.

Due to the large entropy requirement of the Artifact ("code") and short life nature of its validity, the success probability of this attack is extremely low.

Secondary authenticator (="code") is transmitted only through HTTPS, thus it is protected between the OP and the User-Agent, and User-Agent and the RP. Only the place it can be captured is the User-Agent where the TLS session is terminated, and is possible if the User-Agent is infested by malwares. However, it renders no usefulness as long as the profile in use either RP authentication or assertion encryption.

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

If the authentication request is POSTed directly through a protected channel, it is not possible to disclose the authentication request. If the Request File is encrypted by the OP's public key, the authentication request will not be disclosed unless OP's private key gets compromised or the encryption algorithm becomes vulnerable.

Timing attack can be used to reduce the effective key length of the signature if the time required to return the response in case of a signature error and a correct signature differs. Care should be taken in the implementation to avoid this attack.

In the category of Authentication Process Threats, following threats exists. Online guessing Phishing Pharming Eavesdropping Replay Session hijack Man-in-the-middle Authentication process per se as described in NIST SP800-63-rev1 is out of scope for this protocol, but care SHOULD be taken to achieve appropriate protection.

[[ To be removed from the final specification ]] Following items remain to be done in this draft: Finish the security consideration section. Properly capitalize the Defined Words. Provide more structure to the OpenID Request Object section.

Facebook Nomura Research Institute, Ltd. Protiviti Government Services Google Microsoft Corporation MGI1 Nomura Research Institute, Ltd. Protiviti Government Services Google Microsoft Corporation MGI1 AOL Microsoft Corporation Google rotivity Government Service Microsoft Google Nomura Research Institute, Ltd. Facebook Microsoft Corporation Google rotivity Government Service Microsoft Google Nomura Research Institute, Ltd. Facebook Microsoft Corporation Google rotivity Government Service Microsoft Google Nomura Research Institute, Ltd. Facebook Yahoo Facebook Microsoft Deutsche Telekom AG IBM Oracle Corporation Microsoft Corporation Microsoft Corporation Independent Facebook National Institute of Standards and Technology National Institute of Standards and Technology

[[ To be removed from the final specification ]] -03 Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call. -02 Consistency and cleanup pass, including removing unused references. Moved display and prompt parameter definitions from the Framework spec back to the Core spec. -01 Added RFC5656/BCP47 locale information to claims requests. -00 Split from core when all optional features were removed.