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


OpenID Connect Standard 1.0 - draft 06

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 authorization 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.  OpenID Connect Scopes
    4.2.  Protocol Flows
        4.2.1.  How to Get an Authorization Code, Access Token, and ID Token
        4.2.2.  Authorization Code Flow
        4.2.3.  Implicit Flow
    4.3.  Authorization Request
        4.3.1.  Client Prepares an Authorization Request
        4.3.2.  Authorization Server Authenticates the End-User
        4.3.3.  Authorization Server Obtains the End-User Consent/Authorization
        4.3.4.  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 ID Endpoint
    7.1.  Check ID Requests
    7.2.  Check ID Response
        7.2.1.  Check ID 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.  Notices
Appendix D.  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,” October 2011.) [OpenID.Messages] and OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0].

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,” October 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 that enables the client to store a Request File at the Authorization Server and receive back a Request URI that uniquely identifies the registered Request File.


 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 distributed, collaborative, hypermedia systems. Its 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,” October 2011.) [OpenID.Messages].



 TOC 

4.  Authorization Endpoint

The Authorization Endpoint performs authentication services for the End-User and requests authorization from the End-User to release information to OpenID Connect Relying Party clients. When an End-User accesses a Relying Party client application which requires the End-User's identity and other information, it sends the End-User to the Authorization Server's Authorization Endpoint for authentication and authorization. The Authorization Sever then issues an ID Token which asserts the End-User's identity and an Access Token which allows the client to access the End-User's information at protected resource endpoints. Protected resource endpoints MAY perform different actions or return different information based on the scopes associated with the presented Access Token. Clients MUST specify how the Access Token and ID Token are to be returned is determined by the response_type parameter in the Authorization Request.



 TOC 

4.1.  OpenID Connect Scopes

Clients MUST specify the desired scopes in an authorization request to obtain an Access Token with the proper permissions.

OpenID Connect clients use scopes as defined in 3.3 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0] to specify what access privileges are requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. For OpenID Connect, scopes request what information is to be made available from the UserInfo Endpoint and to request an ID Token. OAuth 2.0 allows additional scopes to be specified as extensions. This specification only describes scopes that are part of OpenID Connect.

OpenID Connect defines the following scopes:

openid
REQUIRED. Informs the Authorization Server that the client is making an OpenID request. If the openid scope is not specified, the Authorization Server SHOULD treat the request as a generic OAuth 2.0 request, and perform no OpenID Connect processing.
profile
OPTIONAL. Requests default profile information.
email
OPTIONAL. Requests an email address.
address
OPTIONAL. Requests an address.

Multiple scopes MAY be requested by creating a space delimited, case sensitive list of scope values.

The End-User may decline a scope request by the client.

To increase conversion, a client may elect to only request a subset of the information from the UserInfo Endpoint.

The following is a non-normative example of a Scope Request.

scope=openid profile email phone


 TOC 

4.2.  Protocol Flows

Authorization requests follow two main paths to obtain Access Tokens and ID Tokens, the Implicit Flow and the Authorization Code Flow. The flows determine how the Access Token and ID Token are returned to the client. Access Tokens contain Resource Owners' credentials to access protected resources. As such, they SHOULD NOT be exposed.

The Implicit Flow is mainly used by clients implemented in a browser using a scripting language. The Access Token and ID Token are returned directly to the client, which MAY expose them to the Resource Owner and other applications which have access to the Resource Owner's user-agent. The Authorization Server does not perform client authentication before issuing the Access Token.

The Authorization Code Flow returns an Authorization Code to the client, which can then exchange it for an Access Token directly. This provides the added benefit of not exposing the Access Token to the Resource Owner and possibly other malicious applications with access to the Resource Owner's user-agent. The Authorization Server can also authenticate the client before exchanging the Authorization Code for an Access Token. The Authorization Code flow is suitable for clients that can securely maintain a client secret between themselves and the Authorization server whereas the Implicit flow is suitable for clients that cannot.



 TOC 

4.2.1.  How to Get an Authorization Code, Access Token, and ID Token

The Authorization server MUST support both the "code" and the "id_token token" response_type.

The client may request any OAuth 2.0 registered response type supported by the Authorization Server.

The OAuth 2.0 specification documents two response types:

code
When supplied as the value for the response_type parameter, a successful response MUST include an authorization code as defined in the OAuth 2.0 specification. Both successful and error responses MUST be added as parameters to the query component of the response. All tokens are returned from the Token Endpoint. Authorization servers MUST support this response_type.
token
When supplied as the value for the response_type parameter, a successful response MUST include an access token as defined in the OAuth 2.0 specification. Both successful and error responses MUST be fragment-encoded. No id_token is provided to the client.

Openid Connect supports these additional flows (de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” October 2011.) [RESPONSE.TYPES] that have been registered:

id_token token
When supplied as the value for the response_type parameter, a successful response MUST include both an access token as well as an id_token. Both success and error responses SHOULD be fragment-encoded. Authorization servers MUST support this response_type.
code token
When supplied as the value for the response_type parameter, a successful response MUST include both an access token and an authorization code as defined in the OAuth 2.0 specification. Both successful and error responses SHOULD be fragment-encoded.
code id_token
When supplied as the value for the response_type parameter, a successful response MUST include both an authorization code as well as an id_token. Both success and error responses SHOULD be fragment-encoded.
code id_token token
When supplied as the value for the response_type parameter, a successful response MUST include an authorization code, an id_token, and an access token. Both success and error responses SHOULD be fragment-encoded.


 TOC 

4.2.2.  Authorization Code Flow

The Authorization Code 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 at the Token Endpoint (Token Endpoint)
  7. Client receives Assertion which contains an Access Token and ID Token in the response body
  8. (OPTIONAL) Client validates the ID Token at the Check ID Endpoint (Check ID Endpoint)
  9. (OPTIONAL) Client receives ID Token Response with the End-User's identity
  10. (OPTIONAL) Client accesses the UserInfo Endpoint (UserInfo Endpoint) with the Access Token
  11. (OPTIONAL) Client receives UserInfo Response

Note that in each step, the party that receives a 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,” October 2011.) [OpenID.Messages].



 TOC 

4.2.3.  Implicit Flow

The implicit 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 and an ID Token if requested
  6. (OPTIONAL) Client validates the ID Token at the Check ID Endpoint (Check ID Endpoint)
  7. (OPTIONAL) Client receives ID Token Response with the End-User's identity
  8. (OPTIONAL) Client accesses the UserInfo Endpoint (UserInfo Endpoint) with the Access Token
  9. (OPTIONAL) Client receives UserInfo Response

Note that in each step, the party that receives a 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,” October 2011.) [OpenID.Messages].



 TOC 

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

Authorization servers MUST require the use of a transport-layer security mechanism at the Authorization Endpoint. 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.

Authorization servers MUST support the use of the HTTP "GET" and "POST" methods defined 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] at the Authorization Endpoint.

Clients MAY use the HTTP "GET" or "POST" method to send the Authorization Request to the Authorization Server. If using the HTTP "GET" method, the request 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,” October 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.3.1.  Client Prepares an Authorization Request

The client prepares an Authorization Request to the Authorization Endpoint with the request parameters using the HTTP "GET" or "POST" method. The scheme used in the Authorization URL MUST be HTTPS.

The required Authorization Request parameters are as follows:

response_type
An OAuth 2.0 registered response type that determines how the authorization response is returned to the client. As described in How to Get an Authorization Code, Access Token, and ID Token (How to Get an Authorization Code, Access Token, and ID Token) , the following registered values are supported:
  • code
  • code id_token
  • token
  • token id_token
  • code token
  • code token id_token
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 as described by OpenID Connect Scopes (OpenID Connect Scopes).
redirect_uri
A redirection URI where the response will be sent.
nonce
A random, unique string value used to mitigate replay attacks. The value is passed through unmodified to the id_token.

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 specifies how the Authorization Server displays the authentication page to the user. The following value is supported: none. 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,” October 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,” October 2011.) [OpenID.Messages] for more information
audience
The identifier of the target audience for an ID token.

There are three methods to construct and send the request to the authorization endpoint:

a.
Simple Request Method
b.
Request Parameter Method
c.
Request File Method

The Simple Request 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 Rile 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.



 TOC 

4.3.1.1.  Simple Request Method

The Client prepares an Authorization Request to the Authorization endpoint using the appropriate parameters. If using the HTTP "GET" method, the request 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,” October 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.

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
&nonce=n-0S6_WzA2Mj
&state=af0ifjsldkj


 TOC 

4.3.1.1.1.  Client sends a request to the Authorization Server

Having constructed the Authorization Request, the client sends it to the HTTPS End-User Authorization Endpoint. This MAY happen via HTTPS redirect, hyperlinking, or any other means of directing the User-Agent to the Authorization Endpoint 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=code%20id_token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&scope=openid
&nonce=n-0S6_WzA2Mj
&state=af0ifjsldkj


 TOC 

4.3.1.2.  Request Parameter Method

The Client prepares an Authorization Request to the Authorization Endpoint using the appropriate HTTP parameters serialization. The client SHOULD construct the request using the HTTP "POST" method, but MAY use the HTTP "GET" method.

The Authorization Request MUST include the request parameter defined in the Client Prepares an Authorization Request (Client Prepares an Authorization Request) section. The Authorization Request MUST NOT include the request_uri parameter.

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 contains the Authorization Request and also specifies the content and format of the responses returned from the UserInfo and Check ID Endpoints. 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.

All Authorization Request parameters that are part of the Authorization Request excluding the request and request_uri parameters MUST also be JSON Serialized into the OpenID Request Object with the same values. This allows the client to send signed and/or encrypted requests to the Authorization Server and maintain conformance to OAuth 2.0.

The following is a non-normative example of an OpenID Request Object before JWT encoding. 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": "n-0S6_WzA2Mj",
 "nonce": "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",
    "nonce":"n-0S6_WzA2Mj",
    "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.eyJyZXNwb25zZV90eXBlIjoiY29kZ
    SBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiO
    iJodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkI
    HByb2ZpbGUiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zI
    jp7Im5hbWUiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiO
    m51bGwsInZlcmlmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sI
    mZvcm1hdCI6InNpZ25lZCJ9LCJpZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvM
    jkxMTUiOiIyIn19.2OiqRgrbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY

The following is a non-normative example of an Authorization Request with the OpenID Request Method. 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
&nonce=n-0S6_WzA2Mj
&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY2
9kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiOi
JodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2
ZpbGUiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbW
UiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiOm51bGwsInZlcm
lmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ2
5lZCJ9LCJpZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqR
grbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY


 TOC 

4.3.1.2.1.  Client Sends a Request to the Authorization Server

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

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
&nonce=n-0S6_WzA2Mj
&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY2
9kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiOi
JodHRwczpcL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2
ZpbGUiLCJzdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbW
UiOm51bGwsIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiOm51bGwsInZlcm
lmaWVkIjpudWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ2
5lZCJ9LCJpZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqR
grbrHkA1FZ5p_7bc_RSdTbH-wo_Agk-ZRpD3wY


 TOC 

4.3.1.3.  Request File Method

The Request File Method differs from the other methods in that it uses a request file which contains a JSON encoded OpenID Request Object. It then sends the request file URL as part of the Authorization Request.

The Client prepares an Authorization Request using the desired HTTP "GET" or "POST" method. The Client SHOULD use the HTTP "GET" method, but MAY use the HTTP "POST" method. The scheme used in the Authorization URL MUST be HTTPS.

The Authorization Request MUST NOT include the request parameter. The Authorization Request MUST include the request_uri parameter which is a globally reachable URL. The contents of the URL is a JWT which is a OpenID Request Object.

All Authorization Request parameters that are part of the Authorization Request excluding the request parameter MUST also be JSON Serialized into the OpenID Request Object with the same values. This allows the client to send signed and/or encrypted requests to the Authorization Server and maintain conformance to OAuth 2.0. The OpenID Request Object MAY be 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:

{
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNwb25zZV90eXBlIjoiY29kZSBpZF9
0b2tlbiIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmVjdF91cmkiOiJodHRwczp
cL1wvY2xpZW50LmV4YW1wbGUuY29tXC9jYiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUiLCJ
zdGF0ZSI6ImFmMGlmanNsZGtqIiwidXNlcmluZm8iOnsiY2xhaW1zIjp7Im5hbWUiOm51bGw
sIm5pY2tuYW1lIjp7Im9wdGlvbmFsIjp0cnVlfSwiZW1haWwiOm51bGwsInZlcmlmaWVkIjp
udWxsLCJwaWN0dXJlIjp7Im9wdGlvbmFsIjp0cnVlfX0sImZvcm1hdCI6InNpZ25lZCJ9LCJ
pZF90b2tlbiI6eyJtYXhfYWdlIjo4NjQwMCwiaXNvMjkxMTUiOiIyIn19.2OiqRgrbrHkA1F
Z5p_7bc_RSdTbH-wo_Agk-ZRpD3wY
}


 TOC 

4.3.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.3.1.3.2.  Client Sends a Request to Authorization Server via HTTPS Redirect

The Client sends the Authorization Request to the Authorization Endpoint.

The entire URL MUST NOT exceed 512 bytes.

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&nonce=n-0S6_WzA2Mj&scope=openid


 TOC 

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

Note that the RP SHOULD use a unique URI for each request, or otherwise prevent the Authorization server from caching the request_uri.

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.3.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. An authentication user interface MAY be displayed by the Authorization Server depending on the authentication method used.

The Authorization Server MUST attempt to authenticate the user in the following cases:

The Authorization Server MUST NOT attempt authentication in the following cases:



 TOC 

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

The Authorization Server MUST attempt to request authorization from the user in the following cases:

The Authorization Server MUST NOT request user authorization in the following cases:



 TOC 

4.3.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.3.4.1.  End-User Grants Authorization

If the resource owner grants the access request, the Authorization Server issues an Authorization Response and delivers it to the client by adding the response parameters to redirection URI specified in the Authorization Request using the "application/x-www-form-urlencoded" format.

If the response_type parameter in the Authorization Request includes the string value "code", the following response parameters are included:

code
REQUIRED. The Authorization 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.

If the response_type parameter in the Authorization Request includes the string value "token", the following response parameters are included:

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,” September 2011.) [OAuth.2.0.Bearer] scheme. As such, this value MUST be set to "Bearer".
expires_in
OPTIONAL. The lifetime in seconds of the Access Token.
scope
OPTIONAL. The scopes of the issued Access Token.

If the response_type parameter in the Authorization Request includes the string value "id_token", the following response parameters are returned:

id_token
REQUIRED. The ID Token of the for the authentication session.

The response parameters MAY also be include:

state
REQUIRED if the state parameter is present in the Authorization Request. Set it to the exact value of the state parameter received from the client.

No other parameter SHOULD be returned.

If the response_type parameter in the Authorization Request includes the string value "token" or "id_token", all response parameters MUST be added to the fragment component of the redirection URI. Otherwise, the response parameters are added to the query component of the redirection URI.

The following are some non-normative examples. Line wraps are for display purpose only:

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

HTTP/1.1 302 Found
Location: https://client.example.com/cb#
token=jHkWEdUXMU1BwAsC4vtUsZwnNvTIxEl0z9K3vx5KF0Y
&token_type=Bearer
&state=af0ifjsldkj

HTTP/1.1 302 Found
Location: https://client.example.com/cb#
code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&token=jHkWEdUXMU1BwAsC4vtUsZwnNvTIxEl0z9K3vx5KF0Y
&token_type=Bearer
&state=af0ifjsldkj

HTTP/1.1 302 Found
Location: https://client.example.com/cb#
code=Qcb0Orv1zh30vL1MPRsbm-diHiMwcLyZvn1arpZv-Jxf_11jnpEX3Tgfvk
&token=jHkWEdUXMU1BwAsC4vtUsZwnNvTIxEl0z9K3vx5KF0Y
&token_type=Bearer
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9zZ
XJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMjQ4Mjg5NzYxMDAxIiwiYXVkIjoiaHR0c
DpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0vzDH3T1
G3liaTNOrfaeWYjuRCEPNXVtaazNQ
&state=af0ifjsldkj


 TOC 

4.3.4.2.  End-User Denies Authorization or Invalid Request

If the user denies the authorization or the user authentication fails, the authorization 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,” October 2011.) [OpenID.Messages]. The authorization server returns the client to the redirection URI specified in the authorization request with the appropriate error parameters. No other parameters SHOULD be returned.

The error response parameters are the following:

error
REQUIRED. The error code.
error_description
OPTIONAL. A human-readable UTF-8 encoded text description of the error.
error_uri
OPTIONAL. A URI to a web page that includes additional information about the error.
state
REQUIRED if the Authorization Request included the state parameter. Set to the exact value received from the client.

If the response_type parameter in the Authorization Request includes the string value "token" or "id_token", all error response parameters SHOULD be added to the fragment component of the redirection URI. Otherwise, the response parameters are added to the query component of the redirection URI.

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 

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,” October 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,” September 2011.) [OAuth.2.0].

Authorization servers MUST support the use of the HTTP "POST" method defined 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] at the Token Endpoint.

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 an 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 as specified in Section 4.1.3 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0]:

grant_type
REQUIRED. A string "authorization_code".
code
REQUIRED. The authorization code received from the authorization server.
redirect_uri
REQUIRED, if the redirect_uri parameter was included in the authorization request described in Section 4.1.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0], and their values MUST be identical.

If the client type is confidential or was issued client credentials (or assigned other authentication requirements), the client MUST authenticate with the authorization server as described in Section 3.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0].

The client MAY authenticate by sending the client_id and client_secret using the HTTP Basic authentication scheme as defined in RFC2617 (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) [RFC2617]. Alternatively, the client MAY send the following client credentials in the HTTP request-entity body:

client_id
REQUIRED. The client identifier of the client.
secret_type
OPTIONAL. Specifies the client authentication type which determines how the client_secret parameter is interpreted. It can be one of "basic" or "JWT". The defaults value is "basic". If the value is "basic", the client is performing symmetric key authentication as specified in OAuth 2.0. If the value is "JWT", the client is performing asymmetric key authentication.
client_secret
REQUIRED. The client secret. If the secret_type is "basic", the value is the pre-shared secret that was issued to the client during client registration. If the "secret_type" is "JWT", the value is the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] signature of a JSON object containing one of the following claims:
code
REQUIRED. The authorization code that was issued by the authorization server.
refresh_token
REQUIRED. The refresh token that was issued.

Authorization servers MUST support both forms of client authentication at the Token Endpoint.

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
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

The authorization server MUST:



 TOC 

5.1.2.  Access Token Response

Upon receipt of the Token Request, the Authorization Server MUST return either a Positive or a 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,” October 2011.) [OpenID.Messages].

The assertion is a JSON structure which contains the following values:

access_token
REQUIRED. The Access Token.
token_type
REQUIRED. Specifies the access token type. This specification only supports the "Bearer" token type.
id_token
REQUIRED if scope in the Authorization Request contains the value "openid". The ID Token associated with the authentication session.
refresh_token
OPTIONAL. The Refresh Token that can be used to obtain a new Access Token.
expires_in
OPTIONAL. The lifetime of the Access Token in seconds.
scope
OPTIONAL. The scope of the Access Token.

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.eyJpc3MiOiJodHRwOl
wvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMjQ4Mjg5NzYxMDAxIiwiYXVkIj
oiaHR0cDpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0
vzDH3T1G3liaTNOrfaeWYjuRCEPNXVtaazNQ"
}


 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,” October 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
OPTIONAL. The scope of the access request. If not omitted is treated as equal to the scope originally granted by the resource owner. If omitted or includes openid as one of the strings, an id_token is returned in addition to the access_token.

The Authorization Server MUST verify the validity of the refresh token.

If the client type is confidential or was issued client credentials (or assigned other authentication requirements), the client MUST authenticate with the authorization server as described in Section 3.2.1 of OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0].

The client MAY authenticate by sending the client_id and client_secret using the HTTP Basic authentication scheme as defined in RFC2617 (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) [RFC2617]. Alternatively, the client MAY send the following client credentials in the HTTP request-entity body:

client_id
REQUIRED. The client identifier of the client.
secret_type
OPTIONAL. Specifies the client authentication type which determines how the client_secret parameter is interpreted. It can be one of "basic" or "JWT". The defaults value is "basic". If the value is "basic", the client is performing symmetric key authentication as specified in OAuth 2.0. If the value is "JWT", the client is performing asymmetric key authentication.
client_secret
REQUIRED. The client secret. If the secret_type is "basic", the value is the pre-shared secret that was issued to the client during client registration. If the "secret_type" is "JWT", the value is the JWS (Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signatures,” April 2011.) [JWS] signature of a JSON object containing one of the following claims:
code
REQUIRED. The authorization code that was issued by the authorization server.
refresh_token
REQUIRED. The refresh token that was issued.

Authorization servers MUST support both forms of client authentication at the Token Endpoint.

The Authorization Server 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 Section 3.2.2 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,” October 2011.) [OpenID.Messages].

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 profile


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.eyJpc3MiOiJodHRwOl
wvXC9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMjQ4Mjg5NzYxMDAxIiwiYXVkIj
oiaHR0cDpcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0
vzDH3T1G3liaTNOrfaeWYjuRCEPNXVtaazNQ"
}


 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,” October 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.

Authorization servers MUST support the use of the HTTP "GET" and HTTP "POST" methods defined 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] at the UserInfo Endpoint.

Authorization servers MUST be able to accept Access Tokens via Bearer Tokens (Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” September 2011.) [OAuth.2.0.Bearer] specification.



 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,” October 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,” September 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,” September 2011.) [OAuth.2.0.Bearer]. If the client is using the HTTP GET method, it SHOULD send the Access Token in the authorization header. The access_token MAY alternatively be sent in the message body, as described in the OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.) [OAuth.2.0] specification.
schema
REQUIRED. The schema in which the data is to be returned. The only defined value is openid. If the value of this parameter is omitted, or not openid, 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,” October 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,” October 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 ID Endpoint

The Check ID 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 ID endpoint to validate and retrieve the claims associated with the ID Token in plain text JSON format.

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.

Authorization servers MUST support the use of the HTTP "GET" and HTTP "POST" methods defined 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] at the Check ID Endpoint.

Clients MAY use the HTTP "GET" or "POST" method to send the Authorization Request to the Authorization Server. If using the HTTP "GET" method, the request 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,” October 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 

7.1.  Check ID Requests

The client prepares a Check ID Endpoint Request to the Check ID Endpoint with the request parameters using the HTTP "GET" or "POST" method. The scheme used in the Authorization URL MUST be HTTPS.

The request parameters are as follows:

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

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

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9zZX
J2ZXIuZXhhbXBsZS5jb20iLCJ1c2VyX2lkIjoiMjQ4Mjg5NzYxMDAxIiwiYXVkIjoiaHR0cD
pcL1wvY2xpZW50LmV4YW1wbGUuY29tIiwiZXhwIjoxMzExMjgxOTcwfQ.eDesUD0vzDH3T1G
3liaTNOrfaeWYjuRCEPNXVtaazNQ


 TOC 

7.2.  Check ID Response

The Check ID Endpoint MUST return the JSON serialized claims associated with the ID Token as described in Check ID Response section of OpenID Messages (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” October 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 ID 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 ID 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,” October 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,” October 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,” September 2011.
[OAuth.2.0.Bearer] Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” September 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,” October 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.
[RESPONSE.TYPES] de Medeiros, B., Scurtescu, M., and P. Tarjan, “OAuth 2.0 Multiple Response Type Encoding Practices,” October 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).
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” RFC 2617, June 1999 (TXT, HTML, XML).
[RFC5246] Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT).


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

Copyright (c) 2011 The OpenID Foundation.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.



 TOC 

Appendix D.  Document History

[[ To be removed from the final specification ]]

-06

-05

-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