TOC 
DraftN. Sakimura, Ed.
 NRI
 J. Bradley
 Protiviti
 B. de Medeiros
 Google
 M. Jones
 Microsoft
 E. Jay
 MGI1
 September 2, 2011


OpenID Connect Standard 1.0 - draft 04

Abstract

OpenID Connect 1.0 is a simple identity layer on top of OAuth 2.0 protocol. It allows a web site or application to verify the identity of the user based on the authentication performed by the server, as well as to obtain basic profile information about the user in an interoperable and RESTful manner.

OpenID Connect Standard 1.0 is an HTTP protocol binding for OpenID Connect Messages 1.0 request and response messages.



Table of Contents

1.  Requirements Notation and Conventions
2.  Terminology
3.  HTTP Protocol Binding
4.  Authorization Endpoint
    4.1.  Authorization Code Flow
        4.1.1.  Client prepares an Authorization Request
        4.1.2.  Authorization Server Authenticates the End-User
        4.1.3.  Authorization Server Obtains the End-User Consent/Authorization
        4.1.4.  Authorization Server Sends the End-User Back to the Client
        4.1.5.  Client Request Assertion Using the "Code"
    4.2.  Implicit Flow
        4.2.1.  Client Prepares an Authorization Request URL
        4.2.2.  Client Sends a Request to the Authorization Server
        4.2.3.  Authorization Server Authenticates the End-User
        4.2.4.  Authorization Server Obtains the End-User Consent/Authorization
        4.2.5.  Authorization Server Sends the End-User Back to the Client
5.  Token Endpoint
    5.1.  Requesting an Access Token
        5.1.1.  Access Token Request
        5.1.2.  Access Token Response
    5.2.  Refreshing an Access Token
        5.2.1.  Positive Assertion
6.  UserInfo Endpoint
    6.1.  UserInfo Request
    6.2.  UserInfo Response
        6.2.1.  UserInfo Error Response
7.  Check Session Endpoint
    7.1.  Client Session Requests
    7.2.  Check Session Response
        7.2.1.  Check Session Error Response
8.  Session Management Endpoints
9.  Discovery and Registration
10.  Security Considerations
    10.1.  Implicit Grant Flow Threats
11.  IANA Considerations
12.  Normative References
Appendix A.  Footnotes
    A.1.  Example JWT Values
Appendix B.  Acknowledgements
Appendix C.  Document History
§  Authors' Addresses




 TOC 

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.



 TOC 

2.  Terminology

Followings are the additional terminology defined in this specification in addition to those defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] and OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.) [OAuth.2.0].

Artifact
A small string that acts as a reference to the larger body of data.
Request File
A JSON structure that captures the OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] Authorization Request parameters that can be pointed by a URL that is reachable by the Authorization Server.
Request URI
A URL that points to the Request File. It MUST be accessible by the Authorization Server.
Request Registration Endpoint
An HTTPS Endpoint URL provided by the Authorization Server so that the Client MAY register the Request File to obtain the Request URI.


 TOC 

3.  HTTP Protocol Binding

The HTTP (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] protocol is a widely used application level protocol for distribute, collaborative, hypermedia systems. It's ubiquitousness makes it an ideal protocol for use by OpenID Connect. This specification describes the binding of the HTTP protocol with the various endpoints described in OpenID Connect Messages (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].



 TOC 

4.  Authorization Endpoint

Authorization requests follow two paths, the authorization code flow and the implicit grant flow. The authorization code flow is suitable for clients that can securely maintain client secrets between itself and the authorization server whereas the implicit grant flow is suitable for clients that cannot.



 TOC 

4.1.  Authorization Code Flow

The authorization code protocol flow goes through the following steps.

  1. Client prepares an Authorization Request containing the desired request parameters.
  2. Client sends a request to the Authorization Server.
  3. Authorization Server Authenticates the End-User
  4. Authorization Server Obtains the End-User Consent/Authorization
  5. Authorization Server Sends the End-User back to the Client with an Authorization Code
  6. Client requests Assertion using the Authorization Code
  7. Client receives Assertion in the response body
  8. (OPTIONAL) Client accesses the UserInfo endpoint (UserInfo Endpoint)
  9. (OPTIONAL) Client receives UserInfo Response

Note that in each step, the party that receives message MUST verify it according to the verification rule set in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].



 TOC 

4.1.1.  Client prepares an Authorization Request

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

The scheme used in the Authorization URL MUST be HTTPS.

This binding further constrains the following request parameters

response_type
It MUST include code and id_token.

Other required parameters in the request include the following:

client_id
The client identifier.
scope
It MUST include openid as one of the strings. Other values that MAY be included are profile, email, address, and PPID. The values specify an additive list of claims that are returned by the UserInfo endpoint.
redirect_uri
A redirection URI where the response will be sent.

The request can contain the following optional parameters:

state
An opaque value used to maintain state between the request and the callback.
request
A JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” July 2011.) [JWT] encoded OpenID Request Object.
request_uri
A URL that points to an OpenID Request Object.
display
A string value that can be none, popup, or mobile. Refer to OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] for more information.
prompt
A space delimited list that can contain login, consent, and select_account. Refer to OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] for more information
nonce
A random, unique string value.
audience
The identifier of the target audience for an ID token.

There are three methods to send the request to the authorization endpoint: a) query parameters method b) request parameter method, and c) request file method.

The query parameters method is used in simple cases when default UserInfo and ID Token claims are desired and requests and responses do not need to be signed or encrypted.

The request parameter method is used by sending an OpenID Request Object when the client desires to retrieve a different set of UserInfo and ID Token claims. The request parameter method also allows requests and responses to be signed or encrypted.

The request file method works similar to the request parameter method but differs in that it sends an URL as a reference to the OpenID Request Object. It enables large requests to be sent securely and compactly even on browsers with limited capabilities. Clients SHOULD use the request file method to minimize the request size.

Authorization servers MUST support the use of the HTTP "GET" method as define in RFC 2616 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] and MAY support the "POST" method at the authorization endpoint.

If using the HTTP "GET" method, the parameters are serialized using URI query string serialization as defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages]. If using the HTTP "POST" method, the request parameters are added to the HTTP request entity-body using "application/x-www-form-urlencoded" format.



 TOC 

4.1.1.1.  Query Parameters Method

The Client prepares an Authorization Request to the Authorization endpoint using the appropriate parameters with HTTP query string serialization.

The following is a non-normative example of an Authorization Request URL. Note that the line wraps within the values are for display purpose only:

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


 TOC 

4.1.1.1.1.  Client sends a request to the Authorization Server

Having constructed the URL, the client sends the End-User to the HTTPS End-User Authorization Endpoint using the URL. This MAY happen via HTTPS redirect, hyperlinking, or any other means of directing the User-Agent to the URL.

The Client SHOULD send the request using the HTTPS GET method, but MAY send it via the HTTPS POST if the authorization server supports it as defined in [W3C.REC‑html401‑19991224] (Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.)

Following is a non-normative example using HTTP redirect. Note: Line wraps are for display purpose only.

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


 TOC 

4.1.1.2.  Request Parameter Method

The Client prepares an Authorization Request to the Authorization endpoint using the appropriate HTTP parameters serialization. The request parameters MUST include the request parameter defined in the Client Prepares an Authorization Request (Client prepares an Authorization Request) section. The request parameter is a JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” July 2011.) [JWT] encoded OpenID Request Object which specifies the content and format of the response returned from the UserInfo endpoint and ID Token endpoint. The JWT object MAY be signed or signed and encrypted via JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] and JWE (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Encryption,” July 2011.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation and/or confidentiality.

Request parameters in the OpenID Request Object takes precedence over query parameters.

The following is a non-normative example of an OpenID Request Object. Note that the line wraps within the values are for display purpose only:

{
 "response_type": "code id_token",
 "client_id": "s6BhdRkqt3",
 "redirect_uri": "https://client.example.com/cb",
 "scope": "openid profile",
 "state": "af0ifjsldkj",
 "userinfo":
   {
     "claims":
       {
         "name": null,
         "nickname": {"optional": true},
         "email": null,
         "verified": null,
         "picture": {"optional": true},
       },
     "format": "signed"
   }
 "id_token":
   {
     "max_age": 86400,
     "iso29115": "2"
   }
}

The following is a non-normative example of a JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” July 2011.) [JWT] encoded OpenID Request Object. Note that the line wraps within the values are for display purpose only:

JWT algorithm = HS256
HMAC HASH Key = 'aaa'

JSON Encoded Header = "{"alg":"HS256","typ":"JWT"}"
JSON Encoded Payload =  "{"response_type":"code id_token","client_id":"s6BhdRkqt3",
                          "redirect_uri":"https:\/\/client.example.com\/cb","scope":"openid profile","state":"af0ifjsldkj",
                          "userinfo":{"claims":{"name":null,"nickname":{"optional":true},"email":null,"verified":null,
                                                "picture":{"optional":true}},"format":"signed"},
                          "id_token":{"max_age":86400,"iso29115":"2"}}"

JWT =  eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtx
       dDMiLCJyZWRpcmVjdF91cmkiOiJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUiLCJzd
       GF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfS
       wiZW1haWwiOm51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ25lZCJ9LCJpZF9
       0b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY

The following is a non-normative example of an Authorization Request URL. Note that the line wraps within the values are for display purpose only:

https://server.example.com/authorize?
response_type=code%02id_token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&scope=openid
&state=af0ifjsldkj
&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtx
dDMiLCJyZWRpcmVjdF91cmkiOiJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUiLCJzd
GF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfS
wiZW1haWwiOm51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ25lZCJ9LCJpZF9
0b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY


 TOC 

4.1.1.2.1.  Client Sends a Request to the Authorization Server

Having constructed the URL, the client sends the End-User to the HTTPS End-User Authorization Endpoint using the URL. This MAY happen via HTTPS redirect, hyperlinking, or any other means of directing the User-Agent to the URL.

The Client MAY send the request using the HTTP GET method, but MUST send it via the HTTP POST if the authorization server supports it as defined in [W3C.REC‑html401‑19991224] (Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.)

Following is a non-normative example using HTTP redirect. Note: Line wraps are for display purpose only.

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?
response_type=code%20id_token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&scope=openid
&state=af0ifjsldkj
&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtx
dDMiLCJyZWRpcmVjdF91cmkiOiJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUiLCJzd
GF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfS
wiZW1haWwiOm51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ25lZCJ9LCJpZF9
0b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY


 TOC 

4.1.1.3.  Request File Method

The request file method differs from the other methods in that it uses a request file which contains all the authorization request parameters. It sends the request file URL to the authorization endpoint instead of the request parameters.

The Client prepares a file with a JSON serialized Authorization Request described in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] with a globally reachable URL. Optionally, the request may contain other extension parameters. It MAY be signed or signed and encrypted via JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] and JWE (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Encryption,” July 2011.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation and/or confidentiality.

Following is a non-normative example of a Request File. Note that the line wraps within the values are for display purpose only:

{
    "response_type": "code id_token",
    "client_id": "s6BhdRkqt3",
    "redirect_uri": "https://client.example.com/cb",
    "scope": "openid",
    "state": "af0ifjsldkj"
}


 TOC 

4.1.1.3.1.  Client Obtains the URL of the Request File

The Client then records the Request File either locally or remotely and obtains the Request URI, "request_uri".

Optionally, the Authorization Server may provide the Request File registration service at the Request Registration Endpoint, which allows the Client to register the Request File and obtain the URL for it in exchange. This is especially useful for the cases when the RP is behind the firewall or lives on a client device that cannot be accessed from the Authorization Server.



 TOC 

4.1.1.3.2.  Client Sends a Request to Authorization Server via HTTPS Redirect

The Client sends the user to the HTTPS End-User Authorization Endpoint through the HTTP 302 redirect with the following parameters

response_type
REQUIRED. "code".
client_id
REQUIRED. The Client Identifier.
request_uri
REQUIRED. The Request URI.
state
OPTIONAL. 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.

The entire URL MUST NOT exceed 512 bytes.

The Client SHOULD send the request using the HTTP GET method, but MAY send it via the HTTP POST if the authorization server supports it as defined in [W3C.REC‑html401‑19991224] (Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.)

Following is a non-normative example. Note: Line wraps are for display purpose only:

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?response_type=code%20id_token&cliend_id=s6BhdRkqt3
&request_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Frf%2Ejs
&state=af0ifjsldkj


 TOC 

4.1.1.3.3.  Authorization Server Fetches the Request File

Upon receipt of the Request, the Authorization Server MUST send a GET request to the request_uri to retrieve the content unless it is already cached and parse it to recreate the authorization request parameters.

Following is a non-normative example of this fetch process. Note: Line wraps are for display purpose only:

GET /rf.js HTTP/1.1
Host: client.example.com


 TOC 

4.1.2.  Authorization Server Authenticates the End-User

The Authorization Server validates the request to ensure all required parameters are present and valid. If the request is valid, the authorization server MUST authenticate the End-User. The way in which the authorization server authenticates the End-User (e.g. username and password login, session cookies) is beyond the scope of this specification.



 TOC 

4.1.3.  Authorization Server Obtains the End-User Consent/Authorization

Once the user is authenticated, the Authorization Server MUST obtain an authorization decision. This MAY be done by presenting the user with a dialogue that allows the user to recognize what he is consenting to and obtain his consent or by establishing approval via other means ( for example, via previous administrative approval )



 TOC 

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

Once the authorization is determined, the Authorization Server returns a positive or negative response.



 TOC 

4.1.4.1.  End-User Grants Authorization

If the resource owner grants the access request, the authorization server issues an Authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:

code
REQUIRED. The Authorization Code.
state
REQUIRED if the "state" parameter in the request. Set to the exact value of the "state" parameter received from the client.

No other parameter SHOULD be returned. The entire URL MUST NOT exceed 512 bytes.

The following is a non-normative example. Line wraps after the second line is for the display purpose only:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?
code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&state=af0ifjsldkj


 TOC 

4.1.4.2.  End-User Denies Authorization or Invalid Request

If the user denies the authorization or the user authentication fails, the server MUST return the negative authorization response as defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages]. The authorization server returns the client the redirection URI specified in the authorization request with the appropriate error parameters in the HTTP query string. No other parameters SHOULD be returned.

The following is a non-normative example. Line wraps after the second line is for the display purpose only:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?
error=invalid_request
&error_description=the%20request%20is%20not%20valid%20or%20malformed
&state=af0ifjsldkj


 TOC 

4.1.5.  Client Request Assertion Using the "Code"

Upon receipt of the "code", the Client requests an Assertion that includes the "access_token" and other variables. The requests and responses are described in the Token endpoint (Token Endpoint) section.



 TOC 

4.2.  Implicit Flow

The implicit grant flow follows the following steps:

  1. Client prepares an Authorization Request containing the desired request parameters.
  2. Client sends a request to the Authorization Server.
  3. Authorization Server Authenticates the End-User
  4. Authorization Server Obtains the End-User Consent/Authorization
  5. Authorization Server Sends the End-User back to the Client with an Access Token


 TOC 

4.2.1.  Client Prepares an Authorization Request URL

When the user wishes to access a Protected Resource, and the End-User Authorization has not yet been obtained, the Client prepares an Authorization Request URL using URI query string serialization as defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].

The scheme used in the Authorization URL MUST be HTTPS.

This binding further constrains the following request parameters

response_type
It MUST include token and id_token.

The request MUST contain the other required parameters and MAY contain optional parameters as defined in the preparing an authorization request (Client prepares an Authorization Request) section.



 TOC 

4.2.2.  Client Sends a Request to the Authorization Server

Having constructed the URL, the client sends the End-User to the HTTPS End-User Authorization Endpoint using the URL. This MAY happen via HTTPS redirect, hyperlinking, or any other means of directing the User-Agent to the URL.

Following is a non-normative example using HTTP redirect. Note: Line wraps are for display purpose only.

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


 TOC 

4.2.3.  Authorization Server Authenticates the End-User

The Authorization Server validates the request to ensure all required parameters are present and valid. If the request is valid, the authorization server MUST authenticate the End-User. The way in which the authorization server authenticates the End-User (e.g. username and password login, session cookies) is beyond the scope of this specification.



 TOC 

4.2.4.  Authorization Server Obtains the End-User Consent/Authorization

Once the user is authenticated, the Authorization Server MUST obtain an authorization decision. This MAY be done by presenting the user with a dialogue that allows the user to recognize what he is consenting to and obtain his consent or by establishing approval via other means ( for example, via previous administrative approval )



 TOC 

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

Once the authorization is determined, the Authorization Server returns a positive or negative response.



 TOC 

4.2.5.1.  End-User Grants Authorization

If the resource owner grants the access request, the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the "application/x-www-form-urlencoded" format:

access_token
REQUIRED. The Access Token
token_type
REQUIRED. This specification only supports the Bearer Token (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” July 2011.) [OAuth.2.0.Bearer] scheme. As such, this value MUST be set to "Bearer".
state
REQUIRED if the "state" parameter in the request. Set to the exact value of the "state" parameter received from the client.
id_token
REQUIRED if the response_type parameter in the request included the id_token value.

The client can then use the Access Token to access protected resources at resource servers.

The following is a non-normative example. Line wraps after the second line is for the display purpose only:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#
access_token=SlAV32hkKG&
token_type=Bearer&
expires_in=3600&
&state=af0ifjsldkj
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMj
Q4Mjg5NzYxMDAxIiwiYXVkIjoiaHR0cDpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0vzDH3T1G3liaTNOrf
aeWYjuRCEPNXVtaazNQ


 TOC 

4.2.5.2.  End-User Denies Authorization or Invalid Request

If the user denies the authorization or the user authentication fails, the server MUST return the negative authorization response as defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages]. No other parameter SHOULD be returned.



 TOC 

5.  Token Endpoint

The Token endpoint handles requests for retrieving and refreshing access tokens.

Clients MUST use the HTTP "POST" method to make requests to the Token endpoint. Request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded format.

Clients MAY provide authentication parameters in the request to the Token endpoint as described in section 3.2 of OpenID Connect Messages (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] and section 3.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.) [OAuth.2.0].

Authorization servers MUST require the use of a transport-layer security mechanism. The authorization server MUST support TLS 1.2 as described in RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and MAY support other transport-layer mechanisms with equivalent security.

All Token endpoint responses that contain tokens, secrets, or other sensitive information MUST include the following HTTP response header fields and values:



Header NameHeader Value
Cache-Control no-store
Pragma no-cache

 HTTP Response Headers and Values 



 TOC 

5.1.  Requesting an Access Token

To retrieve an access token, a client MUST have an authorization code obtained via the method as described in Authorization Code Flow (Authorization Code Flow).



 TOC 

5.1.1.  Access Token Request

To obtain a access token assertion, the client MUST send the following parameters via HTTPS POST to the Token endpoint using application/x-www-form-urlencoded format in the HTTP request entity-body:

grant_type
REQUIRED. A string "authorization_code".
code
REQUIRED. The authorization code received from the authorization server.

The following is a non-normative example. Line wraps after line 4 are for display purpose only:

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

client_id=s6BhdRkqt3
&client_secret=some_secret12345
grant_type=authorization_code
&code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk


 TOC 

5.1.2.  Access Token Response

Upon receipt of the Token Request, the Server MUST return either Positive or Negative Assertion that corresponds to the received authorization code.



 TOC 

5.1.2.1.  Positive Assertion

A Positive Assertion response returns the "application/json" media type and the response body is the Access Token Response of the OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].

The assertion is a JSON structure which MUST contain the following values:

access_token
The access token.
id_token
The ID Token associated with the authentication session.
token_type
Specifies the access token type. This specification only support the "Bearer" token type.

In addition, it can contain the optional refresh_token, expires_in, and scope values.

Following is a non-normative example of the Positive Assertion:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMj
Q4Mjg5NzYxMDAxIiwiYXVkIjoiaHR0cDpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0vzDH3T1G3liaTNOrfaeWYjuR
CEPNXVtaazNQ"
}


 TOC 

5.1.2.2.  Error Response

If the Token Request is invalid or unauthorized, the Authorization Server constructs the response by returning the Token Error Response defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] in the entity body of the HTTP response using the application/json media type with HTTP response code 400.

Following is a non-normative example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}


 TOC 

5.2.  Refreshing an Access Token

To refresh an Access token that has expired, the client sends a POST request to the Token endpoint with the following parameters in the entity-body using the application/x-www-form-urlencoded format:

grant_type
REQUIRED. A string "refresh_token".
refresh_token
REQUIRED. The refresh token that was issued in a previous Token endpoint request.
scope
REQUIRED. It MUST include openid as one of the strings. Other values that MAY be included are profile, email, address, and PPID. The values specify an additive list of claims that are returned by the UserInfo endpoint.

The authorization MUST verify the validity of the refresh token



 TOC 

5.2.1.  Positive Assertion

Upon successful verification of the refresh token, a positive assertion response returns the "application/json" media type and the response body is the Access Token Response of the OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].

The assertion is a JSON structure which MUST contain the following values:

access_token
The access token.
id_token
The ID Token associated with the authentication session.
token_type
Specifies the access token type. This specification defines the "JWT" type for a JWT token.

In addition, it can contain the optional refresh_token, expires_in, and scope values.

Following is a non-normative example of the refresh token request and response:

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

client_id=s6BhdRkqt3
&client_secret=some_secret12345
&grant_type=refresh_token
&refresh_token=8xLOxBtZp8
&scope=openid


HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "TlBN45jURg",
    "token_type": "Bearer",
    "refresh_token": "9yNOxJtZa5",
    "expires_in": 3600,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMj
Q4Mjg5NzYxMDAxIiwiYXVkIjoiaHR0cDpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0vzDH3T1G3liaTNOrfaeWYjuR
CEPNXVtaazNQ"
}


 TOC 

6.  UserInfo Endpoint

To obtain the additional attributes and tokens/assertions, the client makes a GET or POST request to the UserInfo Endpoint as in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].

Authorization servers MUST require the use of a transport-layer security mechanism. The authorization server MUST support TLS 1.2 as described in RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and MAY support other transport-layer mechanisms with equivalent security.



 TOC 

6.1.  UserInfo Request

Client SHOULD send the UserInfo request defined in section 3.3 of the OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] either in HTTP GET or POST request.

The request parameters are the following:

access_token
REQUIRED. The access_token obtained from an OpenID Connect authorization request. This parameter MUST NOT be sent if the access token is sent in the HTTP Authorization header as described in Section 7.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.) [OAuth.2.0]. Access tokens sent in the authorization header must be Bearer tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” July 2011.) [OAuth.2.0.Bearer]. If the client is using the HTTP GET method, it SHOULD send the access token in the authorization header.
schema
OPTIONAL. The schema in which the data is to be returned. The only predefined value is openid. If this parameter is not included, the response may be a proprietary schema to support backwards compatibility. A URL MAY be passed to define custom schemes not specified by short names. Custom scheme names and responses are out of scope for this specification.
id
This identifier is reserved for backwards compatibility. It MUST be ignored by the endpoint if the openid schema is used.

The following is a non-normative example. Line wraps are for display purpose only:

POST /userinfo HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

access_token=SlAV32hkKG


 TOC 

6.2.  UserInfo Response

Upon receipt of the UserInfo request, the UserInfo endpoint MUST return the JSON Serialization of the UserInfo response as in OpenID Messages (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] in the HTTP response body. The content-type of the HTTP response MUST be set to application/json if the response body is a text JSON structure. If the JSON response is JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] signed or JWE (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Encryption,” July 2011.) [JWE] encrypted, then the content-type MUST be set to application/jwt.

Following is a non-normative example of such response:

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

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


 TOC 

6.2.1.  UserInfo Error Response

When some error condition arises, the UserInfo endpoint returns the JSON serialized Error Response defined in section 3.3.3 of OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] in the entity body of the HTTP response using the application/json media type with HTTP response code 400.

Following is a non-normative example of an error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":"invalid_request"
}


 TOC 

7.  Check Session Endpoint

The Check Session endpoint validates ID Tokens and returns the claims of an issued ID Token in JSON text format. This endpoint is used by clients that are not able to or do not wish to process ID Tokens. Clients MAY treat ID Tokens as opaque values and use the Check Session endpoint to validate and retrieve the claims associated with the ID Token in plain text JSON format.



 TOC 

7.1.  Client Session Requests

Clients MUST make a HTTP POST request using transport-layer security with the following application/x-www-form-urlencoded parameters in the request body:

id_token
REQUIRED. The ID Token obtained from an OpenID Connect authorization request.

The Following is a non-normative example of an Check Session request:

POST /check_session HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

id_token=OjkdKlsdHV3JdsZmP


 TOC 

7.2.  Check Session Response

The Check Session endpoint MUST return the JSON serialized claims associated with the ID Token as described in Check Session Response section of OpenID Messages (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] in the HTTP response body. The content-type of the HTTP response MUST be set to application/json if the response body is a text JSON structure. If the JSON response is JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] signed or JWE (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Encryption,” July 2011.) [JWE] encrypted, then the content-type MUST be set to application/jwt.

The following is a non-normative example of a response from the Check Session endpoint:

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

{
 "iss": "http://server.example.com",
 "user_id": "248289761001",
 "aud": "http://client.example.com",
 "exp": 1311281970
}


 TOC 

7.2.1.  Check Session Error Response

When some error condition arises, the UserInfo endpoint returns the JSON serialized Error Response defined in section 3.4.3 of OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages] in the entity body of the HTTP response using the application/json media type with HTTP response code 400.

Following is a non-normative example of an error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":"invalid_id_token"
}


 TOC 

8.  Session Management Endpoints

The Session Management endpoints are specified in the OpenID Connect Session Management (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” September 2011.) [OpenID.Session] specification.



 TOC 

9.  Discovery and Registration

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

However, if installations choose to support unanticipated interactions between Relying Parties and OpenID Providers that do not have pre-configured relationships, they SHOULD accomplish this by implementing the facilities defined in the OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” September 2011.) [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” September 2011.) [OpenID.Registration] specifications.



 TOC 

10.  Security Considerations

This specification references the security considerations defined in OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.) [OpenID.Messages].

In addition, the following list of attack vectors and remedies are also considered.



 TOC 

10.1.  Implicit Grant Flow Threats

In the implicit grant flow, the access token is returned in the fragment part of the client's redirect_uri through HTTPS, thus it is protected between the OP and the User-Agent, and User-Agent and the RP. The 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 malware.



 TOC 

11.  IANA Considerations

This document makes no request of IANA.



 TOC 

12. Normative References

[JWE] Jones, M., Bradley, J., and N. Sakimura, “JSON Web Encryption,” July 2011.
[JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.
[JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” July 2011.
[OAuth.2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.
[OAuth.2.0.Bearer] Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” July 2011.
[OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” September 2011.
[OpenID.Messages] Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” September 2011.
[OpenID.Registration] Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” September 2011.
[OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” September 2011.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC5246] Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT).
[W3C.REC-html401-19991224] Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML).


 TOC 

Appendix A.  Footnotes



 TOC 

A.1.  Example JWT Values

The JWT values used in the non-normative examples of this specification are only place holders for actual JWT values. The examples use "jwt_header.jwt_part2.jwt_part3" as the place holder value. For an example of an actual JWT, refer to the JWT (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” July 2011.) [JWT] specification.



 TOC 

Appendix B.  Acknowledgements

The OpenID Community would like to thank the following people for the work they've done in the drafting and editing of this specification.

Axel Nennker (axel.nennker@telekom.de), Deutsche Telekom

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

George Fletcher (gffletch@aol.com), AOL

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

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

Nat Sakimura (n-sakimura@nri.co.jp)), Nomura Research Institute, Ltd.

Michael B. Jones (mbj@microsoft.com), Microsoft

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



 TOC 

Appendix C.  Document History

[[ To be removed from the final specification ]]

-04

-03

-02

-01



 TOC 

Authors' Addresses

  Nat Sakimura (editor)
  Nomura Research Institute, Ltd.
Email:  n-sakimura@nri.co.jp
  
  John Bradley
  Protiviti Government Services
Email:  jbradley@mac.com
  
  Breno de Medeiros
  Google
Email:  breno@google.com
  
  Michael B. Jones
  Microsoft Corporation
Email:  mbj@microsoft.com
  
  Edmund Jay
  MGI1
Email:  ejay@mgi1.com