OpenID Connect HTTP Redirect Binding 1.0

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 state between itself and the authorization server whereas the implicit grant flow is suitable for clients that cannot.

The authorization code protocol flow goes through the following steps. Client prepares an Authorization Request containing the desired request parameters. Client sends a request to the Authorization Server. Authorization Server Authenticates the End-User Authorization Server Obtains the End-User Consent/Authorization Authorization Server Sends the End-User back to the Client with an Authorization Code Client requests Assertion using the Authorization Code Client receives Assertion in the response body (OPTIONAL) Client accesses the UserInfo endpoint OpenID Connect UserInfo 1.0 (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 Core 1.0 and OpenID Connect Framework 1.0.

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 It MUST include code. Other required parameters in the request include the following: The client identifier. It MUST include openid as one of the strings. A redirection URI where the response will be sent. The request can contain the following optional parameters: An opaque value used to maintain state between the request and the callback. A JWT encoded OpenID Request Object. A URL that points to an OpenID Request Object. A string value that can be none, popup, or mobile. A space delimited list that can contain login, consent, and select_account. A random, unique string value. 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. Authorization servers MUST support the use of the HTTP "GET" method as define in RFC 2616 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 Core 1.0. 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 Client prepares an Authorization Request to the Authorization endpoint using the appropriate HTTP parameters 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:

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 HTTP GET method, but MAY send it via the HTTP POST if the authorization server supports it as defined in Following is a non-normative example using HTTP redirect. Note: Line wraps are for display purpose only.

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 section. The request parameter is a JWT encoded OpenID Request Object which specifies the content and format of the response returned from the UserInfo endpoint . The JWT object MAY be signed or signed and encrypted via JWS and 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:

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

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:

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 Following is a non-normative example using HTTP redirect. Note: Line wraps are for display purpose only.

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 Core 1.0 with a globally reachable URL. Optionally, the request may contain other extension parameters. It MAY be signed or signed and encrypted as in . If it is signed with an asymmetric key, then it may be possible to provide non-repudiation capability of the request. For signing, JWS MUST be used. For encryption, JWE MUST be used.

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

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.

The Client sends the user to the HTTPS End-User Authorization Endpoint through the HTTP 302 redirect with the following parameters REQUIRED. "code". REQUIRED. The Client Identifier. REQUIRED. The Request URI. 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

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

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:

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.

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 )

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

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

If the user denies the authorization or the user authentication fails, the server MUST return the negative authorization response as defined in OpenID Connect Core 1.0. No other parameter SHOULD be returned.

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

Upon receipt of the "code", the Client requests an Assertion that includes the "access_token" and other variables. To obtain the assertion, the client send the following parameters via HTTPS POST to the token endpoint using application/x-www-form-urlencoded format in the HTTP request entity-body: REQUIRED. A string "authorization_code". REQUIRED. The authorization code received from the authorization server. REQUIRED. The client_id of the RP. OPTIONAL. Specifies the client authentication type which determines how the client_secret parameter is interpreted. It can be one of "basic" or "JWT". Defaults to "basic". OPTIONAL. Client Secret. If the secret_type is "basic", send the pre-shared secret. If the secret_type is "JWT", send the compact serialization of the JWT Signature over the 'code'. TODO - we shouldn't constrain the authentication options here, but rather defer to OAuth 2.0 and applicable extensions.

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

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

A Positive Assertion response returns the "application/json" media type and the response body is the Access Token Response of the OpenID Connect Core 1.0. The assertion is a JSON structure which MUST contain the following values: The access token. 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, scope, and id_token values. The authorization server MUST include a HTTP Cache-Control response header field with a value of no-store in any response containing tokens, secrets, or other sensitive information.

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

If the Token Request is invalid or unauthorized, the Authorization Server constructs the response by returning the Token Error Response defined in OpenID Connect Core 1.0 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:

To obtain the additional attributes and tokens/assertions, the client makes a GET or POST request to the UserInfo Endpoint OpenID Connect UserInfo 1.0 as in OpenID Connect Core 1.0 and OpenID Connect Framework 1.0.

Client SHOULD send the UserInfo request defined in section 4.3.1 of the OpenID Connect Core 1.0 either in HTTP GET or POST request.

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

Upon receipt of the UserInfo request, the UserInfo endpoint MUST return the JSON Serialization of the UserInfo response as in in the HTTP response body.

Following is a non-normative example of such response:

When some error condition arises, the UserInfo endpoint returns the Error Response defined in section 4.3.3 of the OpenID Connect Core

The implicit grant flow follows the following steps: Client prepares an Authorization Request containing the desired request parameters. Client sends a request to the Authorization Server. Authorization Server Authenticates the End-User Authorization Server Obtains the End-User Consent/Authorization Authorization Server Sends the End-User back to the Client with an Access Token

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 Core 1.0. The scheme used in the Authorization URL MUST be HTTPS. This binding further constrains the following request parameters It MUST include token. The request MUST contain the other required parameters and MAY contain optional parameters as defined in the preparing an authorization request section.

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.

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

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 query component of the redirection URI using the "application/x-www-form-urlencoded" format: REQUIRED. The AccessToken REQUIRED if the "state" parameter in the request. Set to the exact value of the "state" parameter received from the client. 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:

Followings are the list of attack vectors and remedies that were considered for this specification. For details of the attack vector, see .

To mitigate this attack, there are two ways to mitigate it. The assertion may be digitally signed by the OP. The Relying Party SHOULD check the digital signature to verify that it was issued by a legitimate OP. The assertion may be sent over a protected channel such as TLS/SSL. In order to protect the integrity of assertions from malicious attack, the OP MUST be authenticated. In this specification, the assertion is always sent over TLS/SSL protected channel.

The Assertion disclosure can be mitigated in the following two ways. Assertion is sent over TLS/SSL protected channel, where RP is authenticated by "client_id" and "client_secret". Signed Assertion is encrypted by the RP's public key.

To mitigate this threat, the assertion may be digitally signed by the OP using a key that supports non-repudiation. The RP SHOULD check the digital signature to verify that it was issued by a legitimate OP.

To mitigate this threat, the assertion includes the identity of the RP for whom it was generated as "client_id". The RP verifies that incoming assertions include its identity as the recipient of the assertion.

The assertion includes a timestamp and a short lifetime of validity. The Relying Party checks the timestamp and lifetime values to ensure that the assertion is currently valid.

Due to the large entropy requirement of the Artifact ("code") and short life nature of its validity, the success probability of this attack is extremely low.

Secondary authenticator (="code") is transmitted only through HTTPS, thus it is protected between the OP and the User-Agent, and User-Agent and the RP. 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 malwares. However, it renders no usefulness as long as the profile in use either RP authentication or assertion encryption.

Responses to assertion requests is bound to the corresponding requests by message order in HTTP, as both assertions and requests are protected by TLS that can detect and disallow malicious reordering of packets.

If the authentication request is POSTed directly through a protected channel, it is not possible to disclose the authentication request. If the Request File is encrypted by the OP's public key, the authentication request will not be disclosed unless OP's private key gets compromised or the encryption algorithm becomes vulnerable.

Timing attack can be used to reduce the effective key length of the signature if the time required to return the response in case of a signature error and a correct signature differs. Care should be taken in the implementation to avoid this attack.

In the category of Authentication Process Threats, following threats exists. Online guessing Phishing Pharming Eavesdropping Replay Session hijack Man-in-the-middle Authentication process per se as described in NIST SP800-63-rev1 is out of scope for this protocol, but care SHOULD be taken to achieve appropriate protection.

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.