OpenID Connect Core 1.0 - draft 04

Abstract

OpenID Connect is an identity framework that provides authentication, authorization, and attribute transmition capability. It allows third party attested claims from distributed sources. The specification suite consists of Building Blocks (Core, JSON Web Token, JSON Web Signatures, JSON WEB Encryption, JSON Web Keys, Simple Web Discovery), Protocol Bindings (e.g, Artifact Binding, Web App Binding, User Agent Binding) and Extensions. This specification is the "Core" of the suite that defines the messages used and abstract flow which will be further constrained or extended in the companion specifications in the suite.

Table of Contents

1.  Requirements Notation and Conventions
2.  Terminology
3.  Overview
4.  Messages
    4.1.  Authorization Endpoint
    4.2.  Token Endpoint
    4.3.  UserInfo Endpoint
    4.4.  Session Management Endpoints
5.  serializations
    5.1.  Query String serialization
    5.2.  JSON Serialization
    5.3.  Conversions of OpenID 2.0 encodings
6.  Signatures
7.  Encryption
8.  Requests and Responses
9.  Verification
    9.1.  Authorization Request Verification
    9.2.  Authorization Response Verification
    9.3.  UserInfo Request Verification
    9.4.  UserInfo Response Verification
10.  Extensions
11.  Security Considerations
    11.1.  Assertion manufacture/modification
    11.2.  Assertion disclosure
    11.3.  Assertion repudiation
    11.4.  Assertion redirect
    11.5.  Assertion reuse
    11.6.  Secondary authenticator manufacture
    11.7.  Secondary authenticator capture
    11.8.  Assertion substitution
    11.9.  Authentication Request Disclosure
    11.10.  Timing Attack
    11.11.  Authentication Process Threats
12.  IANA Considerations
    12.1.  OAuth Parameters Registry
13.  Open Issues and Things To Be Done (TBD)
Appendix A.  Acknowledgements
Appendix B.  Document History
14.  Normative References
§  Authors' Addresses

1.  Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) .

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

2.  Terminology

Protected Resource

An access-restricted resource which can be obtained using an OAuth-authenticated request.

Resource Server

A server capable of accepting and responding to protected resource requests.

Client

An application obtaining authorization and making protected resource requests on behalf of the resource owner and with its authorization.

Resource Owner

An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an End-user.

End-user

A human resource owner.

Authentication

An act of verifying End-User's identity through the verification of the credential.

Access Token

A string representing an access authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization servers.

Refresh Token

A token used by the client to obtain a new access token without having to involve the resource owner.

Authorization Code

A short-lived token representing the authorization provided by the end-user. The authorization code is used to obtain an access token and a refresh token.

Authorization Grant

A general term used to describe the intermediate credentials (such as an end-user password or authorization code) representing the resource owner authorization. Access grants are used by the client to obtain an access token. By exchanging access grants of different types for an access token, the resource server is only required to support a single authentication scheme.

Authorization Server

A server capable of authenticating the resource owner and issuing tokens after obtaining authorization from the authenticated Resource Owner. The authorization server may be the same server as Resource Server or a separate entity. A single authorization server may issue tokens for multiple resource servers.

OpenID Provider (OP)

Authorization Servers that are able to support OpenID Connect Messages.

Relying Party (RP)

Client and Resource Servers.

Authorization Endpoint

The Authorization Server's endpoint capable of authenticating the End-User and obtaining authorization.

Client Identifier

An unique identifier that the client to identify itself to the OP.

Client Secret

A shared secret established between the OP and client.

Token Endpoint

The Authorization Server's HTTP endpoint capable of issuing tokens.

OP Endpoints

End-User Authentication, Authorization, and Token Endpoint.

RP Endpoints

The endpoint to which the OP responses are returned through redirect.

UserInfo Endpoint

A protected resource that when presented with a token by the client returns authorized information about the current user.

Claims

A statement that something is true or factual.

Assertion

A set of Claims about the End-User which is attested by the OP and Resource Servers.

Compact Serialization

Compact Serialization defined in JSON Web Token (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt].

Base64url

Base 64 Encoding [RFC3548] (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” July 2003.) with URL and Filename Safe Alphabet without padding.

3.  Overview

OpenID Connect protocol in abstract follows the following steps.

1. The Client sends a request to the Server's End-User Authorization Endpoint.
2. The Server authenticates the user and obtains appropriate authorization.
3. The Server responds with access_token and a few other variables.
4. The Client sends a request with the access_token to the Userinfo Endpoint.
5. Userinfo Endpoint returns the additional user information supported by the Server.

Each message may be signed and encrypted. When the message is encrypted, it MUST be signed first then encrypted. This specification only defines the abstract messsage flow and message formats. The actual use MUST base on one of the companion protocol bindings specifications such as OpenID Connect Artifact Binding 1.0 (Sakimura, N., Ed., Bradley, J., de Madeiros, B., Ito, R., and M. Jones, “OpenID Connect Artifact Binding 1.0,” January 2011.) [OpenID.AB] or OpenID Connect Authorization Code Binding 1.0 (Mortimore, C., Ed., Sakimura, N., Bradley, J., de Madeiros, B., Ito, R., and M. Jones, “OpenID Connect Authorization Code Binding 1.0,” January 2011.) [OpenID.AC].

4.  Messages

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

1. Authorization Endpoint: The Client sends a request to the Server at the Authorization endpoint. The Server then authenticate the End-User to find out if he is eligible to make the authorization. Then, upon the authorization action of the End-User, the 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 be set to token.
2. Token Endpoint: The Client sends the Access Token Request to the Token Endpoint to obtain Access Token Response which includes access_token.
3. UserInfo Endpoint: The access_token MAY be used as a query parameter to obtain user information/assertion/claims about the user by sending a request to the userinfo endpoint.
4. Session Management Endpoints: The openid token MAY be sent to these endpoints to manage the session.

Both Request and Response may either be serialized into Query String serialization (Query String serialization) or JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627].

4.1.  Authorization Endpoint

Autorization Code Request / Response interacts with Authorization Endpoint.

4.1.1.  Authorization Request

Following is the list of variables to be sent as the top level keys:

response_type

REQUIRED. The parameter value MUST be set to code for requesting an Authorization Code, token for requesting an Access Token. The Authorization Server MAY decline to provide one or more of these response types.

client_id

REQUIRED. The client identifier recognized by the Authorization Server.

redirect_uri

REQUIRED unless a redirection URI has been established between the client and authorization server via other means. An absolute URI to which the authorization server will redirect the user-agent to when the End-User authorization step is completed. The authorization server SHOULD require the client to pre-register their redirection URI.

scope

OPTIONAL. The scope of the access request expressed as a list of space-delimited strings. The value of the scope parameter is defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. It MUST include openid as one of the string. [[ToDo: Maybe we do not need it, as openid param is required.]]

state

OPTIONAL. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

openid

REQUIRED. A JSON object that holds OpenID request variables.

type

REQUIRED. A type identifier that identifies the message type. A URI http://openid.net/specs/cc/1.0#env .

Following is the list of OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0] variables are to be sent under the key "openid": when OpenID 2.0 identifier compatibility is sought.

type

REQUIRED. A type identifier that identifies the message type. Set to "http://openid.net/specs/cc/1.0/#req".

immediate

OPTIONAL. indicates if the authorization server should display the authorization user interface. "True" if it should not display the user interface or "False" to display. Default is "False".

claimed_id

OPTIONAL. The claimed_id as in OpenID 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0]

identity

OPTIONAL. The local identifier as in OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0].

realm

REQUIRED if PPID were used in previous authentications. URL pattern the OP SHOULD ask the end user to trust. See Section 9.2 of OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0].

server_id

OPTIONAL. The intended recipient of this request.

pubkey

OPTIONAL. The base64url encoded DER format X.509 certificate of the RP.

atype

OPTIONAL. Type of assertion to be returned at the end. Values are one of the following:

• openid2json : (Default) OpenID Artifact Binding's default assertion format, which is JSON.
• openid2jsonp : openid2json wrapped in "openidjsonp();" so that it will be a JSONP format.
• openid2json+sig: openid2json assertion signed.
• openid2json+sig+enc: openid2json assertion signed and encrypted.
• saml2: SAML ver.2 assertion.
• wss : WS-Security assertion.

These variables are sent from the client to the end-user authorization endpoint according to the protocol bindings of this specification. There are two serialization of the above variables: Query Parameters serialization and JSON serialization.

Following is a non-normative example when they are sent in the query parameters serialization.

GET /authorize?scope=openid&response_type=code
&openid.type=http%3A%2F%2Fopenid.net%2Fspecs%2Fcc%2F1.0%2F%23req
&client_id=s6BhdRkqt3&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

Following is a non-normative example when they are sent as a JSON object serialization.

{
  "type": "http://openid.net/specs/cc/1.0#env,
  "openid": {
    "type": "http://openid.net/specs/cc/1.0#req",
    "server_id": "http://example.com/op/",
    "immediate": "true",
    "claimed_id":"http://specs.openid.net/auth/2.0/identifier_select",
    "identity": "http://specs.openid.net/auth/2.0/identifier_select",
    "ns.pape": "http://specs.openid.net/extensions/pape/1.0",
    "pape.auth_level.ns.nist": "http://csrc.nist.gov/publications/nistpubs/800-63/SP800-63V1_0_2.pdf",
    "pape.preferred_auth_level_types": "nist"
  },
  "redirect_uri": "https://example.com/rp/endpoint_url",
  "response_type":"code",
  "client_id": "http://example.com/rp/",
  "scope": "openid",
  "state": "af0ifjsldkj"
}

4.1.2.  Authorization Response

If the End-User grants the access request, the Authorization Server issues an Authorization Code or an Access Token and delivers them to the Client. Following are the list of the parameter included in the Response message when the response_type in the request was code. Note that if the response_type in the request was token, the Access Token Response (Access Token Response) defined later MUST be returned instead.

code

REQUIRED. The authorization code generated by the authorization server. The authorization code SHOULD expire shortly after it is issued to minimize the risk of leaks. The client MUST NOT reuse the authorization code. If an authorization code is used more than once, the authorization server MAY revoke all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI.

state

REQUIRED if the state parameter was present in the client authorization request. Set to the exact value received from the client.

For example, the Authorization Server redirects the End-User's user-agent by sending the following HTTP response:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=i1WsRn1uB1

Clients SHOULD ignore unrecognized response parameters. The sizes of tokens and other values received from the authorization server, are left undefined by this specification. Clients should avoid making assumptions about value sizes. Servers should document the expected size of any value they issue.

4.1.3.  Authorization Error Response

If the end-user denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the client by adding the following parameters to the redirection URI query component using the application/x-www-form-urlencoded format as defined by W3C.REC&nbhy;html401&nbhy;19991224 (Ragget, D., “HTML 4.01 Specification,” December 1999.) [html401]:

error

REQUIRED. A single error code as described below.

error_description

OPTIONAL. A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.

error_uri

OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

state

REQUIRED if the state parameter was present in the client authorization request. Set to the exact value received from the client.

4.1.3.1.  Error Codes

The Authorization Server includes one of the following error codes with the error response:

invalid_request

The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

invalid_client

The client identifier provided is invalid, the client failed to authenticate, the client did not include its credentials, provided multiple client credentials, or used unsupported credentials type.

unauthorized_client

The authenticated client is not authorized to use the access grant type provided.

invalid_grant

The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI).

unsupported_grant_type

The access grant included - its type or another attribute - is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, malformed, or exceeds the previously granted scope.

invalid_request_response_type

The requested response type is unsupported or is missing.

invalid_request_type

The request type is unsupported.

invalid_request_openid_type

The openid type in the the request is not supported.

invalid_request_redirect_uri

The redirect_uri in the request is missing or malformed.

invalid_request_signature

The request has an invalid signature.

invalid_request_realm

The openid request realm is missing or malformed.

invalid_request_atype

The request contains an unsupported response assertion type.

invalid_request_recipient

The recipient of the request is invalid or does not match.

The error codes can be extended by the string prefixed by x_. If custome error code are used, error_uri MUST be provided.

4.2.  Token Endpoint

Access Token Request / Response interacts with an OpenID Token Endpoint. Upon the successful request, the OpenID returns two tokens, Access Token and OpenID Token.

4.2.1.  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, resource owner credentials, an assertion, or a refresh token).

To make the Access Token Request, the Client sends the following parameters to the Token Endpoint:

grant_type

REQUIRED. The access grant type included in the request. Value MUST be one of authorization_code, refresh_token, or an absolute URI identifying an assertion format supported by the authorization server.

client_id

REQUIRED. The client identifier.

client_secret

REQUIRED. Client Secret. If the secret_type is "shared", send the pre-shared secret. If the secret_type is "jwt", send the compact serealization of the JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt] Signature over the 'code'.

secret_type

OPTIONAL. Type of the client_secret. "shared" or "jwt". Defaults to "shared".

In addition, the client MUST include the appropriate parameters specified in the bindings used.

4.2.2.  Access Token Response

After receiving and verifying a valid and authorized access token request from the client, the Authorization Server returns a Positive Assertion that includes an Access Token.

The token response contains the following parameters which 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.

access_token

REQUIRED if the response type is token or code_and_token, otherwise MUST NOT be included. The Access Token issued by the Authorization Server.

token_type

REQUIRED. The type of the token issued. Value is case insensitive.

refresh_token

OPTIONAL. The Refresh Token used to obtain new Access Tokens using the same End-User authorization. The authorization server SHOULD NOT issue a Refresh Token when the access grant type is set to none.

expires_in

OPTIONAL. The duration in seconds of the access token lifetime if an access token is included. For example, the value 3600 denotes that the access token will expire in one hour from the time the response was generated by the authorization server.

scope

OPTIONAL. The scope of the access token as a list of space-delimited strings. The value of the scope parameter is defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. The authorization server SHOULD include the parameter if the requested scope is different from the one requested by the client.

openid

REQUIRED if it was requested in the request. An OpenID Token. It is a JWS (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” March 2011.) [jws] signed claim described below.

It MAY include any other extension parameters.

Following is a non-normative example.

{
    "access_token": "SlAV32hkKG",
    "token_type": "jwt",
    "refresh_token": "8xLOxBtZp8",
    "user_id": "http://op.example.com/alice#1234",
    "domain": "op.example.com",
    "expires_in": 3600,
    "openid":"jwtheader.jwtpayload.jwtcrypto"
}

Clients SHOULD ignore unrecognized response parameters. The sizes of tokens and other values received from the authorization server, are left undefined by this specification. Clients should avoid making assumptions about value sizes. Servers should document the expected size of any value they issue.

4.2.2.1.  OpenID Token

The OpenID Token is a JWS signed claim that attests the following:

server_id

REQUIRED. The unique identifier of the authorization server such that when paired with the user_id creates a globally unique and never reassigned identifier.

user_id

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

client_id

REQUIRED. The client identifier recognized by the authorization server.

aud

REQUIRED. The JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt]aud (audience) claim.

exp

REQUIRED. The JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt] exp (expiration time) claim.

pape

OPTIONAL. (TBD) If we want this token to be short, we probably want to define a shorter equivalent of PAPE.

4.2.3.  Token Error Response

If the assertion request is invalid or unauthorized, the authorization server constructs the response by adding the following parameter to the entity body of the HTTP response using the "application/json" media type:

error

REQUIRED. A single error code as described below.

error_description

OPTIONAL. A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.

error_uri

OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

4.2.3.1.  Error Codes

The Authorization Server includes one of the following error codes with the error response:

invalid_request

The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

invalid_client

The client identifier provided is invalid, the client failed to authenticate, the client did not include its credentials, provided multiple client credentials, or used unsupported credentials type.

unauthorized_client

The authenticated client is not authorized to use the access grant type provided.

invalid_grant

The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI).

unsupported_grant_type

The access grant included - its type or another attribute - is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, malformed, or exceeds the previously granted scope.

invalid_client_secret

The client secret does not matched pre-shared secret code, is of a different type, or has an invalid signature.

invalid_secret_type

The specified secret type is unsupported.

invalid_request_signature

The request has an invalid signature.

invalid_request_code

The authorization code is missing, malformed, or invalid.

invalid_request_openid_type

The openid type in the the request is not supported.

The error codes can be extended by the string prefixed by x_. If custome error code are used, error_uri MUST be provided.

4.3.  UserInfo Endpoint

UserInfo Request/Response interacts with UserInfo Endpoint.

4.3.1.  UserInfo Request

Client MAY send request with following parameters to the UserInfo Endpoint to obtain further information about the user.

[[TBD: How to ask the attributes the Client is requesting?]]

access_token

REQUIRED. The access_token obtained above.

user_id

REQUIRED. A locally unique and never reassigned identifier for the user. e.g. "24400320" or "AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4". It MUST NOT exceed 255 ASCII characters in length. It could be a pairwise private identifier of the enduser between the Client and the Server.

client_id

REQUIRED. The client identifier recognized by the authorization server.

4.3.2.  UserInfo Response

The response is a JSON object which contains some (or all) of the following reserved keys:

user_id

REQUIRED. A locally unique and never reassigned identifier for the user. e.g. "24400320" or "AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4". It MUST NOT exceed 255 ASCII characters in length. It MUST NOT be reassigned to another user.

server_id

REQUIRED. The unique identifier of the authorization server such that when paired with the user_id creates a globally unique and never reassigned identifier.

client_id

REQUIRED. The client identifier recognized by the authorization server.

asserted_user

REQUIRED. One of "true" if the access was issued for this user or "false" if it is for a different user.

profile_urls

OPTIONAL. An array of URLs that belong to the user across any number of domains.

display_name

OPTIONAL. The display name of the user. e.g., "David Recordon".

given_name

OPTIONAL. The first name of the user. e.g., "David".

family_name

OPTIONAL. The family name of the user. e.g., "Recordon".

email

OPTIONAL. The verified email address of the user. e.g., "recordond@gmail.com".

language

OPTIONAL. End User's preferred language as specified by ISO639.

picture

OPTIONAL. The URL of End User's Picture. e.g., "http://graph.facebook.com/davidrecordon/picture".

openid

REQUIRED if OpenID variables were specified in the Authorization Request. It is a JSON Object.

If the OP desires to provide the identifier transition service from OpenID 2.0, it SHOULD provide the following parameters in addition under the key openid. The key openid includes the following parameters.

claimed_id

OPTIONAL. The OpenID 2.0 verified identifier of this user, if the user has OpenID 2.0 account.

identity

OPTIONAL. The OpenID 2.0 Local ID that this user was verified against, if the user has OpenID 2.0 account.

op_endpoint

OPTIONAL. The OP Endpoint URL.

Upon receipt of these parameters, the Client MUST migrate the user to the new user_id.

If the Authorization Server supports authorization for distributed resources from different entities, it needs to provide different Access Tokens to each resource endpoints. To do this, it returns a JSON object access_tokens.

access_tokens

OPTIONAL. An array of JSON objects that has "endpoint", "access_token", "user_id" and "expires_in" as its subkey.

The key "access_tokens" holds an array of JSON object composed of the following parameters.

endpoint

REQUIRED. Resource Endpoint URL to which the token is used to access.

access_token

REQUIRED. Access token used to access the resource. [Alternatively: An array of JSON objects that has "user_id", "expires_in" and other variables that the resource requires, which is encoded into Encrypted JWT.]

token_type

OPTIONAL. "plain", "jwt", or a fully qualified type URI of the token's type. Defaults to "plain".

expires_in

OPTIONAL. The duration in seconds of the access token lifetime if an access token is included. For example, the value 3600 denotes that the access token will expire in one hour from the time the response was generated by the authorization server. If token type is "jwt", then it MUST NOT be specified.

4.3.3.  UserInfo Error Response

(TBD)

The Authorization Server includes one of the following error codes with the error response:

invalid_request

The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

invalid_client

The client identifier provided is invalid, the client failed to authenticate, the client did not include its credentials, provided multiple client credentials, or used unsupported credentials type.

unauthorized_client

The authenticated client is not authorized to use the access grant type provided.

invalid_grant

The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, expired authorization token, bad end-user password credentials, or mismatching authorization code and redirection URI).

unsupported_grant_type

The access grant included - its type or another attribute - is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, malformed, or exceeds the previously granted scope.

invalid_access_token

The access token is not valid for the requested resource, malformed, is in an incorrect format, outside the valid scope, or expired.

invalid_refresh_token

The refresh token is not valid, malformed, is in an incorrect format, outside the valid scope, or expired.

invalid_request_signature

The request has an invalid signature.

invalid_request_type

The request type is unsupported.

invalid_request_atype

The request contains an unsupported response assertion type.

invalid_request_recipient

The recipient of the request is invalid or does not match.

4.4.  Session Management Endpoints

To manage a session, the client sends a request to the session management endpoints at the authorization server. The session management endpoints at the authorization server are:

Session Refresh

Refreshes an expired ID Token

Check Session

Get a plain text JSON structure from a ID Token

End Session

Ends a session

The sequences for session management are as follows:

4.4.1.  Session Refresh

To refresh a ID Token session that has expired, the client sends a request to the Refresh Session endpoint with an ID Token. A new ID Token is returned in JWS signed format.

Request Parameters:

openid

REQUIRED. A previously issued ID Token from a session request

state

REQUIRED. An opaque value used by the Client to maintain state between the request and callback. If provided, the Authorization Server MUST include this value when redirecting the user-agent back to the Client. Clients are strongly advised to use this variable to relate the request and response.

redirect_uri

REQUIRED. An absolute URI to which the authorization server will redirect the user-agent to with the new ID Token.

Response:

The response is a new ID Token. In a typical HTTP binding, an HTTP 302 redirect to the specified redirect_uri in the request with a new ID Token.

openid

A new ID Token

The following is a non-normative session refresh request:

Request:

GET /op/refresh_token?openid=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI3MzJ9.Vdj-sU3xxwHRd9rF6gjBTw3YMm1BqmT43fGDCpa96jo
&state=bar&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fidtoken_cb
Host: server.example.com

Response:

HTTP/1.1 302 OK
Location: http://client.example.com/idtoken_cb?openid=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ&state=bar&expires_in=3600

4.4.2.  Check Session

For clients that are not capable of dealing with JWS signed ID Tokens, they can send the ID Token to the Check Session endpoint. It will validate the ID Token and return a plain text JSON structure of the ID Token.

Request Parameters:

openid

REQUIRED. A previously issued ID Token from a session request

Response:

The response body is a plain text JSON structure of the base64url decoded payload of the signed ID Token. In a typical HTTP binding, the response is a HTTP 200 response code with the content-type header set to "application/json".

The following is a non-normative example of a check session request:

Request:
POST /op/check_openid?openid=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ

Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
  "iss":"http://server.example.com",
  "client_id","http://client.example.com",
  "audience", "http://client.example.com",
  "user_id":"user_328723",
  "exp":1303852880
}

4.4.3.  End Session

To end the session, the client sends a ID Token to the End Session endpoint. Upon receiving the request, the authorization server performs the logout flow for the user and then redirects the user-agent to the specified redirect_uri.

Request Parameters:

openid

REQUIRED. A previously issued ID Token from a session request

state

REQUIRED. An opaque value used by the Client to maintain state between the request and callback. If provided, the Authorization Server MUST include this value when redirecting the user-agent back to the Client. Clients are strongly advised to use this variable to relate the request and response.

redirect_uri

REQUIRED. An absolute URI to which the authorization server will redirect the user-agent to with the new ID Token.

Response:

The response is dependant on the particular binding. In HTTP binding, the response is a HTTP 302 redirect response to the redirect_uri specified in the request.

The following is a non-normative session refresh request:

Request:

GET /op/end_session?openid=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC5leGFtcGxlLmNvbSJ9.eyJpc3N1ZXIiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJjbGllbnRfaWQiOiJjbGllbnQuZXhhbXBsZS5jb20iLCJhdWRpZW5jZSI6ImNsaWVudC5leGFtcGxlLmNvbSIsImlkIjoidXNlcl8yMzQyMzQiLCJleHAiOjEzMDM4NTI4ODB9.aJwagC6501Da-zK-X8Az9B-Y625aSEfxVuBpFEDjOxQ&state=bar&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fendtoken_cb
Host: server.example.com

...
   Authorizion server performs logout flow
...

Response:

HTTP/1.1 302 OK
Location: http://client.example.com/endtoken_cb?state=bar

5.  serializations

Each message can be serialized either in query parameter serialization or JSON serialization unless it was explicitly stated in the previous sections.

5.1.  Query String serialization

In order to serialize the parameters into Query String Serialization, the client constructs the string by adding the following parameters to the end-user authorization endpoint URI query component using the application/x-www-form-urlencoded format as defined by HTML 4.01 Specification (Ragget, D., “HTML 4.01 Specification,” December 1999.) [html401]:

Following is a non-normative example of such Serialization.

GET /authorize?scope=openid&response_type=code&openid.type=http%3A%2F%2Fopenid.net%2Fspecs%2Fcc%2F1.0%2F%23req&
client_id=s6BhdRkqt3&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HT
TP/1.1
Host: server.example.com

5.2.  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",
  "openid": {
    "type": "http://openid.net/specs/ab/1.0#id_res",
    "mode": "id_res",
    "op_endpoint": "https://op.example.com/op_endpoint",
    "client_id": "http://rp.example.com/",
    "server_id": "http://op.example.com/",
    "claimed_id": "https://example.com/alice#1234",
    "identity": "alice",
    "issued_at": 1274889460
  }
}

5.3.  Conversions of OpenID 2.0 encodings

The two encoding form used in [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.), "HTTP encoding" and "key-value form encoding" can be converted to the OpenID Connect JSON form as follows:

5.3.1.  key-value form encoding Conversion

Section 4.1.1 of [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) defines key-value form encoding. Each line begins with a key, followed by a colon, and the value associated with the key. The line is terminated by a single newline (UCS codepoint 10, "\n"). A key or value MUST NOT contain a newline and a key also MUST NOT contain a colon.

This encoding can be trivially converted to JSON objects by making the key the JSON key and the value the JSON value. The resulting JSON object is stored as the value of the top-level key "openid".

For example, the key-value form encoding

mode:error
error:This is an example message

is converted to a OpenID JSON Encoding as

{
    "openid": {
        "mode": "error",
        "error": "This is an example message"
    }
}

5.3.2.  HTTP encoding Conversion

In [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.), OpenID query parameters are prefixed by "openid." : e.g., openid.sreg.fname and openid.pape.level. They can be translated into a JSON object by listing all the query parameters under the key "openid". Subkeys are constructed by removing "openid." prefix from each parameters. For values, strings are converted to JSON String and num

For example, a query string openid.sreg.fname=Nat&openid.pape.level=1 are converted to JSON as follows:

{
  "openid":{
     "sreg.fname":"Nat",
     "pape.level":1
  }
}

5.3.3.  Additional Constraint

To simplify the implementations, the following practice is strongly RECOMMENDED.

• For the support of the [PAPE1.0] (Recordon, D., Jones, M., Bufu, J., Ed., Daughty, J., and N. Sakimura, “OpenID Provider Authentication Property Extension 1.0,” December 2008.), use "pape" as the prefix.
• For the support of the [AX1.0] (Hardt, D., Bufu, J., and J. Hoyt, “OpenID Attribute Exchange 1.0,” December 2007.), use "ax" as the prefix.
• For the support of the SREG1.1, use "sreg" as the prefix.

6.  Signatures

Depending on the transport through wich the messages are transported, the integrity of the message may not be guaranteed, nor the originator of the message is not authenticated. To mitigate these risks, OpenID Connect supports JSON Web Signatures(JWS) (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” March 2011.) [jws].

Following is the parameters for JWT.

typ

OPTIONAL. One of "JWT", "openid2json+sig".

alg

REQUIRED. One of the algorithm specified in Table 4 of JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt]

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

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Following is a non-normative example of such signature in JSON serialization, where ES256 algorithm was used.

{
    "header": [
        "eyJhbGciOiJFUzI1NiJ9"
    ],
    "payload": "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
    "signature": [
        "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q"
    ]
}

7.  Encryption

To achieve message confidentiality and audience restriction, OpenID Connect uses JSON Web Encryption (JWE) (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Encryption,” March 2011.) [jwe].

8.  Requests and Responses

Requests and Responses can either be plain, signed or encrypted. Signature should be applied to the entire request or response. Signed request and responses in the query are sent in the parameter "signed" together with other parameters. If the request and responses are in the JSON Serialization, the JWS signed version MUST use the JSON serialization.

If the request and responses are to be encrypted with JSON Web Encryption (JWE) (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Encryption,” March 2011.) [jwe], non-encrypted payload MUST NOT be sent. The parameter name for the encrypted payload MUST be 'jwe'.

9.  Verification

9.1.  Authorization Request Verification

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

9.2.  Authorization Response Verification

To verify the validity of the Authorization Response, the client MUST to the following:

1. If the response was signed, the Client SHOULD verify the signature as in JWT as the first step.
2. Check that OP that it connected was really the intended OP through TLS/SSL server certificate check if the endpoint is TLS/SSL endpoint.
3. Check if "type" is "http://openid.net/specs/cc/1.0/#id_res".
4. Verify that the "domain" matches the domain including sub-domain of the server's token endpoint URI.
5. Check if the current time is after "issued_at" and before "issued_at" + "expires_in".
6. If the claimed_id field is present, the client MUST verify that the user info endpoint is authoritative to issue assertions about it. This is done by performing OpenID 2.0 discovery on the URL and finding a <xrd:Service> element with the following information:
   • <xrd:Type> - whose text content is "http://openid.net/specs/cc/1.0/".
   • <xrd:URI> - whose text content is the URL of this user info endpoint.
7. If this tag is not found via OpenID 2.0 discovery or if the URI does not match, the client MUST ignore the presence of the claimed_id parameter.

Note: An authorization server MUST only issue assertions about user identifiers on its domain. The authorization server is responsible for managing its own local namespace and enforcing that each user_id is locally unique and never reassigned.

If the client does not verify the signature, it MUST make a User Info API request.

9.3.  UserInfo Request Verification

If the request was signed, the Server MUST verify the signature as in JWT (Jones, M., Belfanz, D., Bradeley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” January 2011.) [jwt].

9.4.  UserInfo Response Verification

To verify the validity of the UserInfo Response, the client MUST to the following:

1. If the response was signed, the Client SHOULD verify the signature as in JWT as the first step.
2. Check that OP that it connected was really the intended OP through TLS/SSL server certificate check if the endpoint is TLS/SSL endpoint.
3. Check if the current time is after "issued_at" and before "issued_at" + "expires_in".

10.  Extensions

OpenID Connect supports the extensions that are as defined in Section 12 of [OpenID.authentication‑2.0] (specs@openid.net, “OpenID Authentication 2.0,” 2007.) . This specification adds following list to the disallowed aliases.

request_uri, refresh_uri, op_endpoint, user_id, redirect_uri, client_id, server_id, client_meta_uri, server_meta_uri, client_secret, immediate, pubkey, certs_uri, state, code, atype, proofkey, enc_data, enc_key, enc_iv, enc_type, enc_ref, access_token, access_token_secret, issued_at, expires_in, refresh_token.

11.  Security Considerations

Followings are the list of attack vectors and remedies that were considered for this specification.

For details of the attack vector, see [SP800‑63] (National Institute of Standards and Technology, “NIST SP800-63rev.1: Electronic Authentication Guideline,” .).

11.1.  Assertion manufacture/modification

To mitigate this attack, there are two ways to mitigate it.

1. 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.
2. 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.

11.2.  Assertion disclosure

The Assertion disclosure can be mitigated in the following two ways.

1. Assertion is sent over TLS/SSL protected channel, where RP is authenticated by "client_id" and "client_secret".
2. Signed Assertion is encrypted by the RP's public key.

11.3.  Assertion repudiation

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.

11.4.  Assertion redirect

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.

11.5.  Assertion reuse

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.

11.6.  Secondary authenticator manufacture

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.

11.7.  Secondary authenticator capture

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.

11.8.  Assertion substitution

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.

11.9.  Authentication Request Disclosure

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.

11.10.  Timing Attack

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

11.11.  Authentication Process Threats

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.

12.  IANA Considerations

12.1.  OAuth Parameters Registry

The following is the parameter registration request for the "scope" parameter as defined in this specification:

Parameter name: openid

Parameter usage location: The End-User Authorization Endpoint request, the End-User Authorization Endpoint response, the Token Endpoint request, the Token Endpoint response, and the WWW-Authenticate header field.

Change controller: IETF

Specification document(s): [[ this document ]]

Related information: None

13.  Open Issues and Things To Be Done (TBD)

[[To be removed from the final specification.]]

Following items remains to be done in this draft.

1. Check that all the "protocols" has been abstracted and "messages" are protocol independent.
2. IANA registration issue while OAuth registry is not up yet.
3. Clean Up and add references.
4. Update JWT/JWS/JWE related things with the most current version of them.
5. Finish the security consideration section.
6. Properly capitalize the Defined Words.
7. Better to split the Authentication and Authorization server? (Model-wise, yes, but it gets complicated. Current model is implicitly assuming that the Authentication and Authorization server are operated by the same entity and the protocol between them are proprietary.)

Appendix A.  Acknowledgements

As a successor version of OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0], this specification heavily relies on OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0]. Please refer to Appendix C of OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0] for the full list of the contributors for OpenID Authentication 2.0 (specs@openid.net, “OpenID Authentication 2.0,” 2007.) [OpenID.authentication‑2.0].

This specification is largely compliant with OAuth 2.0 draft 15. As the draft is not yet referenceable, relevant text has been incorporated into this draft. 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've done in the drafting and editing of this specification.

Anthony Nadalin (tonynad@microsoft.com), Microsoft.

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

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

David Recordon (dr@fb.com)<author>, Facebook.

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

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

John Bradley (jbradely@mac.com) <author>, Protiviti Government Service.

Mike Jones (Michael.Jones@microsoft.com), Microsoft.

Nat Sakimura (n-sakimura@nri.co.jp) <author/editor>, Nomura Research Institute, Ltd.

Paul Tarjan (pt@fb.com), Facebook.

Ryo Itou (ritou@yahoo-corp.jp), Yahoo! Japan.

Appendix B.  Document History

-01

First Draft that incorporates the core of both openidonnect.com proposal and OpenID Artifact Binding RC3 and abstracted.

-02

Catch up to OAuth 2.0 d15. Replaced JSS and JSE to JWS and JWE. Section grouping and reorganizations. Added more contributors.

-03

Combined with Session Management. Moved "openid" back to Token Endpoint. Renaming the sections according to the Endpoint names. Rewrote intro to the Messages section to be more approacheable.

-04

To keep the ID Token small so that it fits cookie more easily, moved OPTIONAL parameters to UserInfo endpoint response.

14. Normative References

Authors' Addresses