OpenID Connect Core 1.0 - draft 07

Abstract

OpenID Connect is an identity framework that provides authentication, authorization, and attribute transmission capability. It allows third party attested claims from distributed sources. The specification suite builds on OAuth 2.0 and consists of Building Blocks (Core, Framework, JSON Web Token, JSON Web Signatures, JSON WEB Encryption, JSON Web Keys, Simple Web Discovery), Protocol Bindings (e.g., Artifact Binding, Authorization Code 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.

Requirements Language

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

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

Table of Contents

1.  Terminology
2.  Overview
3.  Messages
    3.1.  Authorization Endpoint
    3.2.  Token Endpoint
    3.3.  UserInfo Endpoint
4.  Serializations
    4.1.  Query String serialization
    4.2.  JSON Serialization
5.  Extensions
6.  Security Considerations
7.  IANA Considerations
    7.1.  OAuth Parameters Registry
8.  Open Issues and Things To Be Done (TBD)
9.  Normative References
Appendix A.  Acknowledgements
Appendix B.  Document History
§  Authors' Addresses

1.  Terminology

In addition to "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", "Token Endpoint" defined in OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0], this specification defines the following terms:

Assertion

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

Authentication

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

Base64url

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

Claims

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

Entity

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

End-user

A human resource owner.

OpenID Provider (OP)

Authorization Servers that are able to support OpenID Connect Messages.

OP Endpoints

End-User Authentication, Authorization, and Token Endpoint.

OpenID Request Object

A JSON object that holds the request variables. It holds OpenID request variables. It MAY also contain other OAuth parameters for the request signing purpose, in which case the parameter values MUST match with the OAuth request parameters.

Relying Party (RP)

Client and Resource Servers.

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.

2.  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 message flow and message formats. The actual use MUST be based on one of the companion protocol bindings specifications such as OpenID Connect Artifact Binding 1.0 (Sakimura, N., Ed., Bradley, J., de Medeiros, B., Ito, R., and M. Jones, “OpenID Connect Artifact Binding 1.0,” June 2011.) [OpenID.AB] or OpenID Connect Authorization Code Binding 1.0 (Mortimore, C., Ed., Sakimura, N., Bradley, J., de Medeiros, B., Ito, R., and M. Jones, “OpenID Connect Authorization Code Binding 1.0,” June 2011.) [OpenID.AC].

3.  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 authenticates the End-User to find out if he is eligible to make the authorization. Then, upon the authorization action of the End-User, the 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 an access_token.
3. UserInfo Endpoint: The access_token MAY be sent to the UserInfo Endpoint to obtain user information/assertion/claims about the user by sending a request to the UserInfo endpoint.
4. Session Management Endpoints: The ID 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].

3.1.  Authorization Endpoint

The client sends an Authorization Request to the Authorization Endpoint to obtain an Authorization Response.

3.1.1.  Authorization Request

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

response_type

A space delimited, case sensitive list of string values (Pending OAuth 2.0 changes). Acceptable values are code, token, and none. The value MUST include code for requesting an Authorization Code, token for requesting an Access Token, and none if no response is needed.

scope

It MUST include openid as one of the string.

Other required OAuth 2.0 parameters in the request include:

client_id

The client identifier.

redirect_uri

A redirection URI where the response will be sent.

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

GET /authorize?scope=openid&response_type=code
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&req=HeADeR.pAyl0rd.cRypT0 HTTP/1.1
Host: server.example.com

3.1.2.  Authorization Response

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

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

Response values for other requested response_type parameters are returned in the Access Token Endpoint (Need Confirmation).

The response_type "none" preempts all other values and no other response parameter values are returned.

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&state=1f 8skd

3.1.3.  Authorization Error Response

If the end-user denies the access request or if the request fails, the authorization server informs the client by returning parameters defined in section 4.1.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0].

3.1.3.1.  Error Codes

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

invalid_request_redirect_uri

The redirect_uri in the request is missing or malformed.

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

3.2.  Token Endpoint

Access Token Request / Response interacts with a Token Endpoint. Upon a successful request, it returns an Access Token.

3.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).

The request parameters of the Access Token Request is defined in section 4.1.3 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0].

3.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 parameters in the successful response are defined in Section 4.2.2 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0].

Following is a non-normative example.

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

As in the OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth2.0], Clients SHOULD ignore unrecognized response parameters.

3.2.3.  Token Error Response

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

3.2.3.1.  Error Codes

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

invalid_authorization_code

The authorization code is missing, malformed, or invalid.

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

3.3.  UserInfo Endpoint

The UserInfo endpoint return claims about the authenticated user. This endpoint is defined in the OpenID UserInfo Endpoint (Sakimura, N., Bradley, J., de Medeiros, B., and M. Jones, “OpenID Connect UserInfo Endpoint 1.0,” June 2011.) [UserInfo.Endpoint] specification.

4.  Serializations

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

4.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
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

4.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.  Extensions

OpenID Connect supports OPTIONAL extension parameters in OpenID Request Object, ID Token, and UserInfo Response, as defined in OpenID Connect Framework 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Framework 1.0 - draft 00,” June 2011.) [OpenID.CF].

6.  Security Considerations

See OAuth 2.0 Security Considerations (Lodderstedt, T., Ed., McGloin, M., Hunt, P., and A. Nadalin, “OAuth 2.0 Security Considerations,” April 2011.) [OAuth2.0_securityconsiderations].

7.  IANA Considerations

7.1.  OAuth Parameters Registry

7.1.1.  Scope Parameters

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

7.1.2.  Authorization Request Parameters

The following is the parameter registration request for the Authorization Request in this specification:

• Parameter name: openid
• Parameter usage location: Authorization Request
• Change controller: IETF
• Specification document(s): [[ this document ]]
• Related information: None

7.1.3.  Access Token Response Parameters

The following is the parameter registration request for the Access Token Response in this specification:

• Parameter name: openid
• Parameter usage location: Access Token Response
• Change controller: IETF
• Specification document(s): [[ this document ]]
• Related information: None

8.  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. Clean Up and add references.
2. Update JWT/JWS/JWE related things with the most current version of them.
3. Finish the security consideration section.
4. Properly capitalize the Defined Words.
5. 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.)

9. Normative References

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), Facebook.

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

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

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

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

Nat Sakimura (n-sakimura@nri.co.jp), 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 openidconnect.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 approachable.

-04

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

-05

Reference OAuth 2.0 now since it will be stable.

-06

Claims Syntax. Session Token. Misc.

-07

Moved optional features to new Framework specification and split session management into a separate Session Management specification.

Authors' Addresses