identity 1.0 documentation

OpenID Connect Basic Client Profile 1.0

«  OpenID Connect   ::   Contents   ::   OpenID Connect Implicit Client Profile 1.0  »

OpenID Connect Basic Client Profile 1.0

Abstract

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and RESTful manner.

OpenID Connect Basic Client Profile is a profile of the OpenID Connect Standard 1.0 Specification that is designed to be easy to read and implement for basic web-based Relying Parties using the OAuth code grant type. OpenID Providers should consult the Standard specification. This profile omits implementation and security considerations for OpenID Providers.

(draft 20)

1. Introduction

OpenID Connect Basic Client Profile 1.0 is a profile of the OpenID Connect Messages 1.0 [OpenID.Messages] and OpenID Connect Standard 1.0 [OpenID.Standard] specifications that is designed to be easy to read and implement for basic Web-based Relying Parties using the OAuth authorization_code grant type.

This specification intentionally duplicates content from the Messages and Standard specifications to provide a self-contained implementation profile for basic Web-based Relying Parties using the OAuth authorization_code grant type.

See the OpenID Connect Implicit Client Profile 1.0 [OpenID.Implicit] specification for a related profile for basic Web-based Relying Parties using the OAuth implicit grant type.

OpenID Providers and non-Web-based applications should instead consult the Messages and Standard specifications.

This profile omits implementation and security considerations for OpenID Providers and non-Web-based applications.

( draft 28 )

1.1. Requirements Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

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

All uses of JSON Web Signature (JWS) [JWS] data structures in this specification utilize the JWS Compact Serialization; the JWS JSON Serialization is not used.

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

( draft 28)

1.2. Terminology

This specification uses the terms “Access Token”, “Refresh Token”, “Authorization Code”, “Authorization Grant”, “Authorization Server”, “Authorization Endpoint”, “Client”, “Client Identifier”, “Client Secret”, “Protected Resource”, “Resource Owner”, “Resource Server”, and “Token Endpoint” defined by OAuth 2.0 [RFC6749].

This specification also defines the following terms:

Claim
Claims
Piece of information asserted about an Entity.
Claims Provider
Server that can return Claims about an Entity.
End-User
Human Resource Owner.
Entity
Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity.
ID Token
JSON Web Token (JWT) [JWT] that contains Claims about the authentication event. It MAY contain other Claims.
Identifier
Value that uniquely characterizes an Entity in a specific context.
Issuer
Entity that issues a set of Claims.
Issuer Identifier
Verifiable Identifier for an Issuer. An Issuer Identifier is a case sensitive URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components.
OpenID Provider (OP)
OpenID Provider
OP
OAuth 2.0 Authorization Server that is capable of providing Claims to a Relying Party.
Pairwise Pseudonymous Identifier (PPID)
Pairwise Pseudonymous Identifier
PPID
Identifier that identifies the Entity to a Relying Party that cannot be correlated with the Entity’s PPID at another Relying Party.
Personally Identifiable Information (PII)
Personally Identifiable Information
PII
Information that (a) can be used to identify the natural person to whom such information relates, or (b) is or might be directly or indirectly linked to a natural person to whom such information relates.
Relying Party (RP)
Relying Party
RP
OAuth 2.0 Client application requiring Claim`s from an :term:`OpenID Provider.
UserInfo Endpoint
Protected resource that, when presented with an Access Token by the Client, returns authorized information about the End-User represented by the corresponding Authorization Grant.
Validation
Process intended to establish the soundness or correctness of a construct.
Verification
Process intended to test or prove the truth or accuracy of a fact or value.
Voluntary Claim
Claim specified by the Client as being useful but not Essential for the specific task requested by the End-User.

IMPORTANT NOTE TO READERS: The terminology definitions in this section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as “Issuer Identifier”, reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed.

( draft 28)

2. Protocol Elements

Authorization Requests can follow one of two paths; the Implicit Flow or the Authorization Code Flow.

The Authorization Code Flow is suitable for Clients that can securely maintain a Client Secret between themselves and the Authorization Server whereas, the Implicit Flow is suitable for Clients that cannot.

This specification only provides information that is sufficient for basic Clients using the Code Flow.

( draft 28 )

2.1. Code Flow

The Code Flow consists of the following steps:

1. Client prepares an Authorization Request containing the desired request parameters. 2. Client sends a request to the Authorization Server. 3. Authorization Server authenticates the End-User. 4. Authorization Server obtains the End-User Consent/Authorization. 5. Authorization Server sends the End-User back to the Client with code. 6. Client sends the code to the Token Endpoint to receive an Access Token and ID Token in the response.

( draft 28 )

2.1.1. Client Prepares Authorization Request

When the Client wishes to access a Protected Resource and the End-User Authorization has not yet been obtained, the Client prepares an Authorization Request to the Authorization Endpoint.

Communication with the Authorization Endpoint MUST utilize TLS. See Section 7.1 for more information on using TLS.

Clients MAY construct the request using the HTTP GET or the HTTP POST method as defined in RFC 2616 [RFC2616].

If using the HTTP GET method, the parameters are serialized using the Query String Serialization, per Section 3.1. If using the HTTP POST method, the request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224].

The following is a non-normative example of an Authorization Request URL (with line wraps within values for display purposes only):

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

( draft 28 )

2.1.1.1. Request Parameters

Note

This profile of OpenID Connect uses the following OAuth 2.0 request parameters:

response_type
REQUIRED. This value MUST be code. This requests that both an Access Token and an ID Token be returned from the Token Endpoint in exchange to code.
client_id
REQUIRED. OAuth 2.0 Client Identifier.
scope

REQUIRED.

Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. OpenID Connect requests MUST contain the openid scope value.

OPTIONAL scope values of profile, email, address, phone, and offline_access are also defined.

See Section 2.4 for more about the scope values defined by this specification.

redirect_uri

REQUIRED.

Redirection URI to which the response will be sent. This MUST be pre-registered with the OpenID Provider.

This URI MUST exactly match one of the redirect_uris registered for the Client, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison).

If the Client only uses the OAuth authorization_code grant type, the redirection URI MAY use the http scheme, provided that the Client Type is confidential, as defined in Section 2.1 of OAuth 2.0.

state

RECOMMENDED.

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

Note

  • code フローの場合も redirect_uri はチェックすべき、ということ
  • CSRFは state で対策

This specification also defines the following request parameters:

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

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

page
The Authorization Server SHOULD display authentication and consent UI consistent with a full User-Agent page view. If the display parameter is not specified this is the default display mode.
popup
The Authorization Server SHOULD display authentication and consent UI consistent with a popup User-Agent window. The popup User-Agent window SHOULD be 450 pixels wide and 500 pixels tall.
touch
The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface. The Authorization Server MAY attempt to detect the touch device and further customize the interface.
wap
The Authorization Server SHOULD display authentication and consent UI consistent with a “feature phone” type display.
prompt

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

none
The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if the End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing. This can be used as a method to check for existing authentication and/or consent.
login
The Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot prompt the End-User, it MUST return an error.
consent
The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client.
select_account
The Authorization Server SHOULD prompt the End-User to select a user account. This allows an End-User who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they might have current sessions for. If it cannot prompt the End-User, it MUST return an error.

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

max_age
OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User. When max_age is used, the ID Token returned MUST include an auth_time Claim Value.
ui_locales
OPTIONAL. End-User’s preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value “fr-CA fr en” represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
claims_locales
OPTIONAL. End-User’s preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
id_token_hint
OPTIONAL. Previously issued ID Token passed to the Authorization Server as a hint about the End-User’s current or past authenticated session with the Client. This SHOULD be present when prompt=none is used. If the End-User identified by the ID Token is logged in or is logged in by the request, then the Authorization Server returns a positive response; otherwise, it SHOULD return a negative response. The Authorization Server need not be listed as an audience of the ID Token when it is used as an id_token_hint value.
login_hint
OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the phone_number Claim. The use of this parameter is left to the OP’s discretion.
acr_values
OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this authentication request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2.2. The acr Claim is requested as a Voluntary Claim by this parameter.

( draft 28 )

2.1.2. Client Sends Request to Authorization Server

Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint using HTTPS.

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

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

(draft 28)

2.1.3. Authorization Server Authenticates End-User

The Authorization Server logs in the End-User or verifies whether he is logged in, depending upon the request parameter values used.

If interaction with the End-User occurs over an HTTP channel, it MUST use TLS, as per Section 7.1.

The exact authentication methods used are out of scope for this specification.

( drarft 28 )

2.1.5. Authorization Server Sends End-User Back to Client

Once the authorization is determined, the Authorization Server returns a successful response or an error response.

( draft 28 )

2.1.5.1. End-User Grants Authorization

If the Resource Owner grants the access request, the Authorization Server issues a code and delivers it to the Client by adding the following query parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format as defined in Section 4.1.2 of OAuth 2.0 [RFC6749].

code
REQUIRED. OAuth 2.0 Authorization Code.
state
OAuth 2.0 state value. REQUIRED if the state parameter is present in the Client Authorization Request. Clients MUST verify that the state value is equal to the value of state parameter in the Authorization Request.

The following is a non-normative example (with line wraps for the display purposes only):

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
  code=SplxlOBeZQQYbYS6WxSbIA
  &state=af0ifjsldkj

( draft 28 )

2.1.5.2. End-User Denies Authorization or Invalid Request

If the End-User denies the authorization or the End-User authentication fails, the Authorization Server MUST return the error Authorization Response as defined in 4.1.2.1 of OAuth 2.0 [RFC6749]. No other parameters SHOULD be returned.

( draft 28 )

2.1.6. Client Obtains ID Token and Access Token

The Client then makes an Access Token Request using the Authorization Code to obtain tokens from the Token Endpoint in the following manner:

( draft 28 )

2.1.6.1. Client Sends Code

The Client makes a request to the Token Endpoint using the Form Serialization, per Section 3.2, as described in Section 4.1.3 of OAuth 2.0 [RFC6749].

The Client authenticates itself by communicating its form-urlencoded Client Credentials in an Authorization header using the HTTP Basic method, as described in 2.3.1 of OAuth 2.0. (This method is the one identified by using the client_secret_basic authentication method value in OpenID Connect Discovery 1.0 [OpenID.Discovery]).

Communication with the Token Endpoint MUST utilize TLS. See Section 7.1 for more information on using TLS.

The following is a non-normative example of such a Token Request (with line wraps for the display purposes only):

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

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
  &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

( draft 28 )

2.1.6.2. Client Receives Tokens

The Client receives a response with the following parameters as described in Section 4.1.4 of OAuth 2.0 [RFC6749].

The response SHOULD be encoded using UTF-8.

access_token
REQUIRED. Access Token for the UserInfo Endpoint.
token_type
REQUIRED. OAuth 2.0 Token Type value. The value MUST be Bearer or another token_type value that the Client has negotiated with the Authorization Server. Clients implementing this profile MUST support the OAuth 2.0 Bearer Token Usage [RFC6750] specification. This profile only describes the use of bearer tokens.
id_token
REQUIRED. ID Token.
expires_in
OPTIONAL. Expiration time of the Access Token in seconds since the response was generated.
refresh_token
OPTIONAL. Refresh Token.

The Client can then use the Access Token to access protected resources at Resource Servers.

The following is a non-normative example (with line wraps for the display purposes only):

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
 "access_token":"SlAV32hkKG",
 "token_type":"Bearer",
 "expires_in":3600,
 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "id_token":"eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

( draft 28 )

2.2. ID Token

The ID Token is a security token that contains Claims about the authentication event and other requested Claims.

The ID Token is represented as a JSON Web Token (JWT) [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) Claim.

The following Claims are used within the ID Token:

iss
REQUIRED. Issuer Identifier for the Issuer of the response. The iss value is a case sensitive URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components.
sub
REQUIRED. Subject identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case sensitive string.
aud
REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the special case when there is one audience, the aud value MAY be a single case sensitive string.
exp
REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular. The exp value is a number.
iat
REQUIRED. Time at which the JWT was issued. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. The iat value is a number.
auth_time
OPTIONAL or REQUIRED. Time when the End-User authentication occurred. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. When a max_age request is made then this Claim is REQUIRED. The auth_time value is a number.
nonce
OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token. The Client MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authorization Request. If present in the Authorization Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authorization Request. Use of the nonce is OPTIONAL when using the code flow. The nonce value is a case sensitive string.
at_hash
OPTIONAL. Access Token hash value. This is OPTIONAL when the ID Token is issued from the Token Endpoint, which is the case for this profile; nonetheless, an at_hash Claim MAY be present. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token’s JWS [JWS] header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.
acr
OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value “0” indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 [ISO29115] level 1. Authentication using a long-lived browser cookie, for instance, is one example where the use of “level 0” is appropriate. Authentications with level 0 SHOULD never be used to authorize access to any resource of any monetary value. An absolute URI or a registered name [RFC6711] SHOULD be used as the acr value; registered names MUST NOT be used with a different meaning than that which is registered. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The acr value is a case sensitive string.
amr
OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the amr Claim is beyond the scope of this specification. Parties using this claim will need to agree upon the meanings of the values used, which may be context-specific. The amr value is an array of case sensitive strings.
azp
OPTIONAL or REQUIRED. Authorized Party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 client_id of the party that will be using it. This Claim is only REQUIRED when the party requesting the ID Token is not the same as the sole audience of the ID Token. It MAY be included even when the Authorized Party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.

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

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

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

{
 "iss": "https://server.example.com",
 "sub": "24400320",
 "aud": "s6BhdRkqt3",
 "exp": 1311281970,
 "iat": 1311280970
}

Note

ID Token/Session Token
Claim OIDC(ID Token) OAuth Auth(ID Token/Session Token)
iss(Issuer Identifier) REQUIRED REQUIRED
sub(Subject identifier) REQUIRED(String Array/String) REQUIRED(client_id)
aud(Audience Identifier(s)) REQUIRED REQUIRED
exp(Expiration Time) REQUIRED REQUIRED
iat(Issued At) REQUIRED REQUIRED
auth_time REQUIRED REQUIRED
nonce OPTIONAL N/A
at_hash(Access Token hash value) OPTIONAL N/A
acr (Authentication Context Class Reference) OPTIONAL N/A
amr(Authentication Methods References) OPTIONAL OPTIONAL
azp (Authorized Party) OPTIONAL/REQUIRED N/A
profile N/A OPTIONAL
alv(Authentication Assurance Level) N/A OPTIONAL

2.2.1. Client Prepares an Authorization Request

When the Client wishes to access a Protected Resource, and the End-User Authorization has not yet been obtained, the Client prepares an Authorization Request to the Authorization Endpoint.

The scheme used in the Authorization Endpoint URL MUST be HTTPS.

Clients MAY construct the request using the HTTP GET or the HTTP POST method as defined in RFC 2616 [RFC2616].

If using the HTTP GET method, the parameters are serialized using Query String Serialization. If using the HTTP POST method, the request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224].

This profile further constrains the following request parameters:

response_type

It MUST be code.

This requests that both an Access Token and an ID Token be returned from the Token Endpoint in exchange to code.

Other REQUIRED parameters in the request include the following:

client_id
The OAuth 2.0 Client Identifier.
scope
It MUST include openid as one of the space delimited ASCII strings. OPTIONAL scope strings of profile, email, address, and phone are also supported.
redirect_uri
A redirection URI where the response will be sent. This MUST be pre-registered with the provider.

The request MAY contain the following OPTIONAL parameters:

state

RECOMMENDED.

An opaque value used to maintain state between the request and the callback; serves as a protection against XSRF attacks.

display

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

The following values are supported:

page
The Authorization Server SHOULD display authentication and consent UI consistent with a full user-agent page view. If the display parameter is not specified this is the default display mode.
popup
The Authorization Server SHOULD display authentication and consent UI consistent with a popup user-agent window. The popup user-agent window SHOULD be 450 pixels wide and 500 pixels tall.
touch

The Authorization Server SHOULD display authentication and consent UI consistent with a device that leverages a touch interface.

The Authorization Server MAY attempt to detect the touch device and further customize the interface.

wap
The Authorization Server SHOULD display authentication and consent UI consistent with a “feature phone” type display.
prompt

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

This value informs the Authorization Server that it 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.
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.

nonce

A string value used to associate a Client session with an ID Token, and to mitigate replay attacks.

The value is passed through unmodified from the Authorization Request to the ID Token.

Use of the nonce is OPTIONAL when using the code flow.

Note

Basic is code flow, so “nonce is OPTIONAL for this profile”.

The following is a non-normative example of an Authorization Request URL (with line wraps for display purposes only):

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

(draft 20)

2.2.2. Client sends a request to the Authorization Server

Having constructed the Authorization Request, the Client sends it to the Authorization Endpoint.

This MAY happen via HTTPS redirect, hyperlinking, or any other secure means of directing the User-Agent to the URL.

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

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

(draft 20)

2.2.3. Authorization Server Authenticates the End-User

The authorization server authenticates the resource owner to make sure that the consent is obtained from the right party.

The exact method of how the authentication is performed is out of scope of this specification.

(draft 20 )

2.2.5. Authorization Server Sends the End-User Back to the Client

Once the authorization is determined, the Authorization Server returns a successful response or an error response.

(draft 20)

2.2.5.1. End-User Grants Authorization

If the Resource Owner grants the access request, the Authorization Server issues a code and delivers it to the Client by adding the following query parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format as defined in Section 4.1.2 of OAuth 2.0 [OAuth2.0].

code
REQUIRED. The OAuth 2.0 authorization code.
state
REQUIRED if the state parameter is present in the client Authorization Request. Clients MUST verify that the state value is equal to the exact value of state parameter in the Authorization Request.

The following is a non-normative example (with line wraps after the second line for the display purposes only):

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj

(draft 20)

2.2.5.2. End-User Denies Authorization or Invalid Request

If the End-User denies the authorization or the End-User authentication fails, the Authorization Server MUST return the error authorization response as defined in 4.1.2.1 of OAuth 2.0 [OAuth2.0].

No other parameters SHOULD be returned.

(draft 20)

2.2.6. Client obtains ID Token and Access Token

Once code is obtained, the Client requests the tokens at the Token Endpoint in the following manner:

(draft 20)

The Client makes a request to the token endpoint as described in Section 4.1.3 of OAuth 2.0 [OAuth2.0].

The following is a non-normative example of such a token request (with line wraps after the second line for the display purposes only):

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

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

(draft 20)

access_token
REQUIRED. The Access Token for the UserInfo Endpoint.
token_type
REQUIRED. The value MUST be “bearer”
id_token
REQUIRED. The ID Token.
expires_in
OPTIONAL. The expiration time in seconds of the Access Token.
refresh_token
OPTIONAL. The Refresh Token.

The Client can then use the Access Token to access protected resources at Resource Servers.

The following is a non-normative example (with line wraps after the second line for the display purposes only):

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"SlAV32hkKG",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "id_token":"eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

(draft 20)

2.3. ID Token

The ID Token is a security token that contains Claims about the authentication event and other requested Claims. The ID Token is represented as a JSON Web Token (JWT) [JWT].

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

The following Claims are REQUIRED within the ID Token:

iss
REQUIRED. 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 [RFC3339] for details regarding date/times in general and UTC in particular.

iat

REQUIRED.

Type Integer.

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

The value is number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time.

See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular.

Additional optional claims may be present in the ID Token.

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

{
 "iss": "https://client.example.com",
 "user_id": "24400320",
 "aud": "s6BhdRkqt3",
 "exp": 1311281970,
 "iat": 1311280970
}

(draft 20)

2.4. Scope Values

OpenID Connect Clients use scope values as defined in 3.3 of OAuth 2.0 [RFC6749] to specify what access privileges are being requested for Access Tokens.

The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints.

For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values. This specification describes only the scope values used by OpenID Connect.

OpenID Connect allows additional scope values to be defined and used. Scope values used that are not understood by an implementation SHOULD be ignored.

Claims requested by the following scopes are treated by Authorization Servers as Voluntary Claims.

OpenID Connect defines the following scope values:

openid
REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the openid scope value is not present, the behavior is entirely unspecified.
profile
OPTIONAL. This scope value requests access to the End-User’s default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
email
OPTIONAL. This scope value requests access to the email and email_verified Claims.
address
OPTIONAL. This scope value requests access to the address Claim.
phone
OPTIONAL. This scope value requests access to the phone_number and phone_number_verified Claims.
offline_access
OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User’s UserInfo Endpoint even when the End-User is not present (not logged in).

Multiple scope values MAY be used by creating a space delimited, case sensitive list of ASCII scope values.

The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 2.3.2.

In some cases, the End-User will be given the option to have the OpenID Provider decline to provide some or all information requested by Clients. To minimize the amount of information that the End-User is being asked to disclose, a Client can elect to only request a subset of the information available from the UserInfo Endpoint.

The following is a non-normative example of a scope Request.

scope=openid profile email phone

(draft 28)

If the requested schema is openid, the response MUST return a JSON object that contains the full set or subset of 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.

Note

Drop claims if you don’t want to return.

The members MAY be represented in multiple languages and scripts. To specify the languages and scripts, BCP47 [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.

Reserved Member Definitions
Member Type Description
user_id string REQUIRED Identifier for the End-User at the Issuer.
name string End-User’s full name in displayable form including all name parts, ordered according to End-User’s locale and preferences.
given_name string Given name or first name of the End-User.
family_name string Surname or last name of the End-User.
middle_name string Middle name of the End-User.
nickname string Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.
preferred_username string

Shorthand name that the End-User wishes to be referred to at the RP, such as janedoe or j.doe.

This value MAY be any valid JSON string including special characters such as @, /, or whitespace. This value MUST NOT be relied upon to be unique by the RP. (See Section 2.3.2.2.)

profile string URL of End-User’s profile page.
picture string URL of the End-User’s profile picture.
website string URL of End-User’s web page or blog.
email string The End-User’s preferred e-mail address.
email_verified boolean True if the End-User’s e-mail address has been verified; otherwise false.
gender string The End-User’s gender: Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable.
birthday string The End-User’s birthday, represented as a date string in MM/DD/YYYY format. The year MAY be 0000, indicating that it is omitted.
zoneinfo string String from zoneinfo [zoneinfo] time zone database. For example, Europe/Paris or America/Los_Angeles.
locale string The End-User’s locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Implementations MAY choose to accept this locale syntax as well.
phone_number string The End-User’s preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim. For example, +1 (425) 555-1212 or +56 (2) 687 2400.
address JSON object The End-User’s preferred address. The value of the address member is a JSON [RFC4627] structure containing some or all of the members defined in Section 2.4.2.1.
updated_time string Time the End-User’s information was last updated, represented as a RFC 3339 [RFC3339] datetime. For example, 2011-01-03T23:58:42+0000.

Following is a non-normative example of such response:

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

The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. 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

(draft 17, March 15, 2012 )

2.5. UserInfo Endpoint

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

UserInfo Endpoint Servers MUST require the use of a transport-layer security mechanism. The UserInfo Endpoint Server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support other transport-layer mechanisms with equivalent security.

NOTE: The UserInfo Endpoint response is not guaranteed to be about the Interactive user identified by the user_id element of the ID Token. 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.

(draft 20)

2.5.1. UserInfo Request

Clients MAY send requests with the following parameters to the UserInfo Endpoint to obtain further information about the End-User. The UserInfo Endpoint is an OAuth 2.0 [OAuth2.0] Protected Resource that complies with the OAuth 2.0 Bearer Tokens [OAuth.Bearer] specification. As such, the Access Token SHOULD be specified via the HTTP Authorization header.

access_token
REQUIRED. The Access Token obtained from an OpenID Connect Authorization Request. This parameter MUST only be sent using one method hrough either the HTTP Authorization header or a form-encoded HTTP POST body parameter.
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.

The following is a non-normative example:

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

(draft 20)

2.5.2. UserInfo Response

If the requested schema is openid, the response MUST return a JSON object that contains the full set or subset of 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 [RFC5646] language tags MUST be added to each member names delimited by a #, e.g., family_name#ja-Kana-JP for expressing Family Name in Katakana in Japanese, which is commonly used to index and represent the phonetics of the Kanji representation of the same represented as family_name#ja-Hani-JP.

orphan:

Member

Type

Description

user_id

string

Identifier for the user at the issuer.

name

string

User’s full name in displayable form including all name parts, ordered according to user’s locale and preferences.

given_name

string

Given name or first name of the user.

family_name

string

Surname or last name of the user.

middle_name

string

Middle name of the user.

nickname

string

Casual name of the user that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.

profile

string

URL of user’s profile page.

picture

string

URL of the user’s profile picture.

website

string

URL of user’s web page or blog.

email

string

The user’s preferred e-mail address.

verified

boolean

True if the user’s e-mail address has been verified; otherwise false.

gender

string

The user’s gender: female or male.

birthday

string

The user’s birthday, represented as a date string in MM/DD/YYYY format. The year MAY be 0000, indicating that it is omitted.

zoneinfo

string

String from zoneinfo [zoneinfo] timezone database. For example, Europe/Paris or America/Los_Angeles.

locale

string

The user’s locale, represented as an RFC 5646 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Implementations MAY choose to accept this locale syntax as well.

phone_number

string

The user’s preferred telephone number. For example, +1 (425) 555-1212 or +56 (2) 687 2400.

address

JSON object

The user’s preferred address. The value of the address member is a JSON [RFC4627] structure containing some or all of these string-valued fields: formatted, street_address, locality, region, postal_code, and country. The street_address field MAY contain multiple lines if the address representation requires it. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the user’s privacy preferences. For example, the country and region might be returned without returning more fine-grained address information.

updated_time

string

Time the user’s information was last updated, represented as a RFC 3339 [RFC3339] datetime. For example, 2011-01-03T23:58:42+0000.

Following is a non-normative example of such a response:

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

The UserInfo Endpoint MUST return Claims in JSON format unless a different format was specified during OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. 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 JSON Web Token (JWT) —————— ———————————

3. Protocol Flows

Authorization Requests can follow one of two paths; the Implicit Flow or the Authorization Code Flow. The Authorization Code Flow is suitable for clients that can securely maintain a client secret between themselves and the Authorization Server whereas, the Implicit Flow is suitable for clients that cannot. Clients that do not support TLS MUST use the Authorization Code Flow to prevent the interception of Access Tokens.

The OpenID Connect Basic Client profile only documents clients using the Implicit Flow. OpenID Providers MUST support both flows. Clients wanting to use the Authorization Code Flow and OpenID Providers should consult the OpenID Connect Standard 1.0 specification.

Note

Basic = Implicit Flow

4. UserInfo Endpoint

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

User Info Endpoint Servers MUST require the use of a transport-layer security mechanism. The authorization server MUST support TLS 1.2 as described in RFC 5246 [:rfc:5246] and MAY support other transport-layer mechanisms with equivalent security.

NOTE: The UserInfo Endpoint response is not guaranteed to be about the Subject in the session. Therefore, it MUST NOT be used as an assertion about the End-User in the session unless the user_id matches the user_id in the ID Token.

Note

ID Token is the assertion in Connect. What is “User Info Endpoint Server” ?

(Draft 15)

5. Discovery and Registration

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

However, if installations choose to support unanticipated interactions between Relying Parties and OpenID Providers that do not have pre-configured relationships, they SHOULD accomplish this by implementing the facilities defined in the OpenID Connect Discovery 1.0 [OpenID Connect Discovery 1.0] and OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] specifications.

(Draft 15)

6. Query String Serialization

In order to serialize the parameters using the query string serialization, the client constructs the string by adding the parameters and values to the query component using the application/x-www-form-urlencoded format as defined by [W3C.REC‑html401‑19991224].

Following is a non-normative example of such serialization:

GET /authorize?scope=openid&response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

Host: server.example.com

7. Security Considerations

For security considerations other than those listed below, refer to the OpenID Connect Messages 1.0 [OpenID.Messages] and OpenID Connect Standard 1.0 [OpenID.Standard] specifications.

(draft 28)

7.1. 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] 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] 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.

Whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125 [RFC6125].

( draft 28 )

Note

  • <basic.2.1.1>

8. Privacy Considerations

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

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

The server SHOULD make the UserInfo access log available to the user so that the user can monitor who accessed his data.

To protect the user from a possible correlation among clients, the use of a Pairwise Pseudonymous Identifier (PPID) as the user_id SHOULD be considered.

10. Normative References

[ISO29115]
McCallister, E., “ITU-T Recommendation X.eaa | ISO/IEC 2nd CD 29115 – Information technology - Security techniques - Entity authentication assurance framework,” ISO/IEC 29115.
[ISO3166-1]
International Organization for Standardization, “ISO 3166-1:1997. Codes for the representation of names of countries and their subdivisions – Part 1: Country codes,” 1997.
[ISO639-1]
International Organization for Standardization, “ISO 639-1:2002. Codes for the representation of names of languages – Part 1: Alpha-2 code,” 2002.
[OAuth.2.0]
Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.
[OAuth.2.0.Bearer]
Jones, M., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol: Bearer Tokens,” September 2011.
[OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” September 2011.
[OpenID.Registration]
Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” September 2011.
[OpenID.Session]
de Medeiros, B., “OpenID Connect Session Management 1.0,” September 2011.
[RFC2119]
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616]
Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol – HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC3339]
Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC4627]
Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC5246]
Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT).
[RFC5646]
Phillips, A. and M. Davis, “Tags for Identifying Languages,” BCP 47, RFC 5646, September 2009 (TXT).
[SP800-63]
National Institute of Standards and Technology, “NIST SP800-63rev.1: Electronic Authentication Guideline,” NIST SP800-63.
[W3C.REC-html401-19991224]
Raggett, D., Jacobs, I., and A. Hors, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML).
[zoneinfo]
Public Domain, “The tz database,” June 2011.

«  OpenID Connect   ::   Contents   ::   OpenID Connect Implicit Client Profile 1.0  »