Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp

Facebook Inc.

dr@fb.com

Protiviti Government Services

jbradley@mac.com

Google Inc.

breno@google.com

Microsoft Corporation

mbj@microsoft.com

MGI1

ejay@mgi1.com

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

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, this specification defines the following terms: A set of Claims about the End-User that are attested to by the OpenID Provider and Resource Servers. An act of verifying End-User's identity through the verification of the credential. A piece of information about an Entity that a Claims Provider asserts about that Entity. An Authorization Server that can return claims about a user. A human resource owner. Something that has separate and distinct existence and that can be identified in context. An opaque token that contains claims about an authenticated user. [todo: Need refinement] A service capable of providing identity information to a Relying Party. End-User Authentication Endpoint, Authorization Endpoint, and Token Endpoint. 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. An application requiring identity information from an OpenID Provider. The endpoint to which the OP responses are returned through redirect. A protected resource that, when presented with an access token by the client, returns authorized information about the user represented by that access token.

The OpenID Connect protocol, in abstract, follows the following steps. The Client sends a request to the Server's end-user authorization endpoint. The Server authenticates the user and obtains appropriate authorization. The Server responds with access_token and a few other variables. The Client sends a request with the access_token to the UserInfo endpoint OpenID Connect UserInfo 1.0. 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.

In OpenID Connect protocols, in abstract, the process proceeds by the client interacting with endpoints. There are number of endpoints involved. 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. Token Endpoint: The Client sends the access token request to the token endpoint to obtain Access Token Response which includes an access_token. UserInfo Endpoint: The access_token MAY be sent to the UserInfo endpoint to obtain claims about the user. 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 or JSON.

The client sends an Authorization Request to the authorization endpoint to obtain an Authorization Response.

Section 4.1.1 and 4.2.1 of OAuth 2.0 defines the OAuth Authorization Request parameters. In this specification, the values to the parameters are defined as follows. 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. It MUST include openid as one of the strings. Other required OAuth 2.0 parameters in the request include: The client identifier. A redirection URI where the response will be sent. The following extension parameters are also defined: OPTIONAL. A string value that specifies how the authorization server displays the authentication page to the user. The authorization server MUST NOT display any authentication page. The authorization server displays a popup authentication page. The authorization server performs authentication using a mobile device??? 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: The authorization server MUST prompt the user for reauthentication. The authorization server MUST prompt the user for reapproval before returning information to the client. 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:

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

Then, after appropriate user authenticaiton and authorization, the Authorization Server redirects the End-User's user-agent by sending the following HTTP 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.

In addition to the error codes defined in section 4.1.2.1 of OAuth 2.0, this specification defines the following additional error codes: The redirect_uri in the request is missing or malformed. The authorization server requires user authentication. 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. The authorization server requires user approval. The current logged in user at the authorization server does not match the requested user.

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

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.

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.

Following is a non-normative example:

As in the OAuth 2.0, Clients SHOULD ignore unrecognized response parameters.

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.

In addition to the error codes defined in Section 5.2 of OAuth 2.0, this specification defines the following error codes. The authorization code is missing, malformed, or invalid.

The UserInfo endpoint returns claims about the authenticated user. This endpoint is defined in the OpenID Connect UserInfo 1.0 specification.

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

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 .

Following is a non-normative example of such 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:

OpenID Connect supports OPTIONAL extension parameters such as OpenID Request Object, ID Token, and UserInfo Response, as defined in OpenID Connect Framework 1.0.

These related OpenID Connect specifications MAY OPTIONALLY be used in combination with this specification to provide additional functionality: OpenID Connect UserInfo 1.0 - Schema and format of claims returned by the UserInfo endpoint of OpenID Connect OpenID Connect HTTP Redirect Binding 1.0 - Concrete HTTP Redirect based protocol binding for OpenID Connect messages OpenID Connect Discovery 1.0 - Dynamic discovery for user and server endpoints and information OpenID Connect Dynamic Client Registration 1.0 - Dynamic registration of OpenID Connect clients with OpenID Providers OpenID Connect Session Management 1.0 - Session management for OpenID Connect sessions OpenID Connect Framework 1.0 - Extension and general claims framework

See OAuth 2.0 Security Considerations.

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

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

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

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

Nomura Research Institute, Ltd. Protiviti Government Services Google Microsoft Corporation MGI1 Nomura Research Institute, Ltd. Protiviti Government Services Microsoft Corporation Google Salesforce MGI1 Nomura Research Institute, Ltd. Protiviti Government Services Google Microsoft Corporation MGI1 AOL Nomura Research Institute, Ltd. Protiviti Government Services Microsoft MGI1 Nomura Research Institute, Ltd. Protiviti Government Services Microsoft Corporation Nomura Research Institute, Ltd. Protiviti Government Services Microsoft Corporation Google Salesforce MGI1 Yahoo Facebook Microsoft Deutsche Telekom AG IBM Oracle Corporation Microsoft Corporation

As a successor version of OpenID, this specification heavily relies on OpenID Authentication 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

[[ To be removed from the final specification ]] -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.