OpenID Connect Core 1.0 - draft 10

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, Discovery, Dynamic Client Registration, Session Management, JSON Web Token, JSON Web Signature, 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.1.1.  Authorization Request
        3.1.2.  Authorization Response
        3.1.3.  Authorization Error Response
    3.2.  Token Endpoint
        3.2.1.  Access Token Request
        3.2.2.  Access Token Response
        3.2.3.  Token Error Response
    3.3.  UserInfo Endpoint
4.  Serializations
    4.1.  Query String Serialization
    4.2.  JSON Serialization
5.  Extensions
6.  Related Specifications
7.  Security Considerations
8.  IANA Considerations
    8.1.  OAuth Parameters Registry
        8.1.1.  Scope Parameters
        8.1.2.  Authorization Request Parameters
        8.1.3.  Access Token Response Parameters
9.  Open Issues and Things To Be Done (TBD)
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Document History
§  Authors' Addresses

1.  Terminology

In addition to 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" that are defined by OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” May 2011.) [OAuth.2.0], this specification defines the following terms:

Assertion

A set of Claims about the End-User that are attested to by the OpenID Provider and Resource Servers.

Authentication

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

Claim

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

Claims Provider

An Authorization Server that can return claims about a user.

End-User

A human resource owner.

Entity

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

ID Token

A token that contains a specific set of claims about an authenticated user. See OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.) [OpenID.Session] for more information.

OpenID Provider (OP)

A service capable of providing identity information to a Relying Party.

OP Endpoints

End-User Authentication Endpoint, Authorization Endpoint, 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)

An application requiring identity information from an OpenID Provider.

RP Endpoint

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

UserInfo Endpoint

A protected resource that, when presented with an access token by the client, returns authorized information about the user represented by that access token.

2.  Overview

The 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 OpenID Connect UserInfo 1.0 (Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., Jay, E., and G. George, “OpenID Connect UserInfo 1.0,” July 2011.) [OpenID.UserInfo].
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 the OpenID Connect HTTP Redirect Binding 1.0 (Sakimura, N., Ed., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect HTTP Redirect Binding 1.0,” July 2011.) [OpenID.HTTP‑Redirect].

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 claims about the user.
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.) [OAuth.2.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 include 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 strings.

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.

The following extension parameters are also defined:

display

OPTIONAL. A string value that specifies how the authorization server displays the authentication page to the user.

none

The authorization server MUST NOT display any authentication page.

popup

The authorization server displays a popup authentication page.

mobile

The authorization server performs authentication using a mobile device???

prompt

OPTIONAL. A space delimited, case sensitive list of string values that specifies how the authorization server prompts the user for reauthentication and reapproval. The possible values are:

login

The authorization server MUST prompt the user for reauthentication.

consent

The authorization server MUST prompt the user for reapproval before returning information to the client.

select_account

The authorization server MUST prompt the user to select a user account if the current account does not match the account in the request.

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.) [OAuth.2.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.) [OAuth.2.0].

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

Example: The request is sent over to the Authorization Server through HTTP redirect as follows:

HTTP/1.1 302 Found
Location: https://server.example.com//authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
        &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&state=1f_8skd

Then, after appropriate user authenticaiton and authorization, 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.) [OAuth.2.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.) [OAuth.2.0], this specification defines the following additional error codes:

invalid_request_redirect_uri

The redirect_uri in the request is missing or malformed.

login_required

The authorization server requires user authentication.

session_selection_required

The user is required to select a session at the authorization server. The user may be authenticated at the authorization server with different associated accounts, but the user did not select a session or no session selection is requested from the user due to the display parameter being set to none.

approval_required

The authorization server requires user approval.

user_mismatched

The current logged in user at the authorization server does not match the requested user.

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 are 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.) [OAuth.2.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.) [OAuth.2.0].

Following is a non-normative example:

{
    "access_token": "SlAV32hkKG",
    "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.) [OAuth.2.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.) [OAuth.2.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.) [OAuth.2.0], this specification defines the following error codes.

invalid_authorization_code

The authorization code is missing, malformed, or invalid.

3.3.  UserInfo Endpoint

The UserInfo endpoint returns claims about the authenticated user. This endpoint is defined in the OpenID Connect UserInfo 1.0 (Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., Jay, E., and G. George, “OpenID Connect UserInfo 1.0,” July 2011.) [OpenID.UserInfo] 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 using the 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 [W3C.REC‑html401‑19991224] (Jacobs, I., Hors, A., and D. Raggett, “HTML 4.01 Specification,” December 1999.).

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",
  }
}

5.  Extensions

OpenID Connect supports OPTIONAL extension parameters such as 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,” July 2011.) [OpenID.Framework].

6.  Related Specifications

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

• OpenID Connect UserInfo 1.0 (Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., Jay, E., and G. George, “OpenID Connect UserInfo 1.0,” July 2011.) [OpenID.UserInfo] - Schema and format of claims returned by the UserInfo endpoint of OpenID Connect
• OpenID Connect HTTP Redirect Binding 1.0 (Sakimura, N., Ed., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect HTTP Redirect Binding 1.0,” July 2011.) [OpenID.HTTP‑Redirect] - Concrete HTTP Redirect based protocol binding for OpenID Connect messages
• OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” July 2011.) [OpenID.Discovery] - Dynamic discovery for user and server endpoints and information
• OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0 - draft 02,” July 2011.) [OpenID.Registration] - Dynamic registration of OpenID Connect clients with OpenID Providers
• OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.) [OpenID.Session] - Session management for OpenID Connect sessions
• OpenID Connect Framework 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Framework 1.0,” July 2011.) [OpenID.Framework] - Extension and general claims framework

7.  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.) [OAuth.2.0.SC].

8.  IANA Considerations

8.1.  OAuth Parameters Registry

8.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

8.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

8.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

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

[[ To be removed from the final specification ]]

Following items remain to be done in this draft:

• Finish the security consideration section.
• Properly capitalize the Defined Words.
• 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.)

10.  References

10.1. Normative References

10.2. Informative References

Appendix A.  Acknowledgements

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

This specification is largely compliant with OAuth 2.0 draft 16. 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 Services

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

[[ To be removed from the final specification ]]

-10

• Correct issues raised by Pam Dingle and discussed on the mailing list after the 7-Jul-11 working group call.
• Adopted long_names.

-09

• Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call.

-08

• Consistency and cleanup pass, including removing unused references.
• Moved display and prompt parameter definitions from the Framework spec back to the Core spec.
• Removed obsolete OAuth 2.0-derived language about prefixing errors with x_.

-07

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

-06

• Claims Syntax. Session Token. Misc.

-05

• Reference OAuth 2.0 now since it will be stable.

-04

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

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

-02

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

-01

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

Authors' Addresses