Table of Contents

OAuth 2.0 and OpenID Connect Authorization Endpoints

OAuth 2.0 and OpenID Connect each specify requirements that an authorization endpoint must satisfy to interoperate with client applications. This document explains those requirements, focusing on the differences between the two specifications.

If you are familiar with the specifications, you can jump straight to Implementing an Authorization Endpoint with Authlete.

1. Path

The only constraint imposed by the OAuth 2.0 specfication on the authorization endpoint’s URL path is that “The endpoint URI MUST NOT include a fragment component”. (see 3.1 Authorization Endpoint). As long as this requirement is satisfied, a service can name its authorization endpoint freely. For instance, /auth/authorization is a valid authorization endpoint path. An example of an entire URI with the path is https://example.com/auth/authorization.

2. Security

OAuth 2.0 requires that the authorization endpoint use TLS (Transport Layer Security).

3. HTTP methods

According to section 3.1. Authorization Endpoint of the OAuth 2.0 specification, the authorization endpoint must support the HTTP GET method; the HTTP POST method is optional. However, OpenID Connect Core 1.0, 3.1.2.1. Authentication Request requires that the authorization endpoint supports the HTTP POST method. In the case of POST, the request parameters must be formatted as application/x-www-form-urlencoded.

Authorization Endpoint HTTP Methods

HTTP method	OAuth 2.0	OpenID Connect
GET	MUST	MUST
POST	MAY	MUST

4. Authorization Request Parameters

OAuth 2.0 defines 4 grant types (flows to get an access token) in 1.3. Authorization Grant. Among the four, Authorization Code Grant (a.k.a. Authorization Code Flow) and Implicit Grant (a.k.a. Implicit Flow) access the authorization endpoint. Both grant types take the same request parameters, shown in the table below:

OAuth 2.0 Authorization Request Parameters

Name	Requirement	Description
`response_type`	REQUIRED	`code` for Authorization Code Grant and `token` for Implicit Grant.
`client_id`	REQUIRED	The client ID of the client application making the authorization request. A client ID is an opaque number or string issued by a service.
`redirect_uri`	OPTIONAL	The URL to which the client application requests the result of the authorization request to be reported. If the client application has registered multiple redirect URIs or has not registered any redirect URI (this is allowed when the client type of the client application is “confidential”), this request parameter is REQUIRED.
`scope`	OPTIONAL	A space-delimited list of scopes (permissions) that the client application requires. The service defines a set of valid scope values. Some implementations of OAuth 2.0 (e.g. Facebook) do not correctly implement the specification, requiring a comma-delimited list.
`state`	RECOMMENDED	An opaque value that the client application may use. If this request parameter is contained in the authorization request, it is returned to the redirect URI as a query parameter.

OpenID Connect adds many more authorization request parameters and values to the set defined by OAuth 2.0. Most of them are described in OpenID Connect Core 1.0, 3.1.2.1. Authentication Request. Here is a combined list of the request parameters defined in OAuth 2.0, OpenID Connect and other specifications.

OpenID Connect Request Parameters

Name	Requirement	Description
`response_type`	REQUIRED	OAuth 2.0 defined only two values for this parameter: `code` and `token`. OpenID Connect also allows `none` and combinations of `code`, `id_token` and `token`. As a result, the complete set of valid values is: `none` `code` `token` `id_token` `code token` `code id_token` `id_token token` `code id_token token` See OAuth 2.0 Multiple Response Type Encoding Practices for details.
`client_id`	REQUIRED	The same requirement as OAuth 2.0.
`redirect_uri`	REQUIRED	In OAuth 2.0, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED.
`scope`	REQUIRED	In OAuth 2.0, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED and must include `openid`.
`state`	RECOMMENDED	The same requirement as OAuth 2.0.
`response_mode`	OPTIONAL	A new request parameter defined in OAuth 2.0 Multiple Response Type Encoding Practices. This request parameter specifies how the result of the authorization request should be formatted.
`nonce`	OPTIONAL	A new request parameter. An opaque string value that will be embedded in an ID token. If `response_type` request parameter contains `id_token` (meaning that an ID token is issued using Implicit Flow), `nonce` is REQUIRED.
`display`	OPTIONAL	A new request parameter to specify how the user interface should be displayed to the end-user.
`prompt`	OPTIONAL	A new request parameter to specify whether the service should prompt the end-user for re-authentication and consent.
`max_age`	OPTIONAL	A new request parameter to specify the maximum authentication age.
`ui_locales`	OPTIONAL	A new request parameter to specify preferred languages and scripts for the user interface.
`id_token_hint`	OPTIONAL	A new request parameter to specify the ID token previously issued by the service.
`login_hint`	OPTIONAL	A new request parameter to specify a hint about the login identifier that the end-user may use.
`acr_values`	OPTIONAL	A new request parameter to specify ACRs (Authentication Context Class References) one of which the client application requests to be satisfied.
`claims_locales`	OPTIONAL	A new request parameter to specify the end-user’s preferred locales for ID token claims. This request parameter is defined in OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts.
`claims`	OPTIONAL	A new request parameter to specify specific claims that the client application requests to be embedded in the ID token returned. This request parameter is defined in OpenID Connect Core 1.0, 5.5. Requesting Claims using the “claims” Request Parameter.
`request`	OPTIONAL	A new request parameter to specify a request object, which is a JWT packing other request parameters and being signed and optionally encrypted. This request parameter is defined in OpenID Connect Core 1.0, 6. Passing Request Parameters as JWTs.
`request_uri`	OPTIONAL	A new request parameter to specify the location of a request object. This request parameter is defined in OpenID Connect Core 1.0, 6. Passing Request Parameters as JWTs.
`registration`	OPTIONAL	A new request parameter to provide additional registration information about the client application itself. This request parameter is defined in OpenID Connect Core 1.0, 7.2.1. Providing Information with the “registration” Request Parameter.
`code_challenge`	CONDITIONALLY REQUIRED	A new request parameter to specify a code challenge as a countermeasure against the code interception attack. This request parameter is defined in RFC 7636 (Proof Key for Code Exchange by OAuth Public Clients). Authorization server implementations may always require this parameter for authorization requests using Authorization Code Flow. See “Proof Key for Code Exchange (RFC 7636)” for details.
`code_challenge_method`	OPTIONAL	A new request parameter to tell the method used to generate a code challenge. This request parameter is defined in RFC 7636 (Proof Key for Code Exchange by OAuth Public Clients). Valid values are `plain` (default) and `S256`. See “Proof Key for Code Exchange (RFC 7636)” for details.

Authorization Response

1. Response Parameters

OAuth 2.0 specifies that a successful authorization results in the authorization endpoint issuing either an authorization code or an access token.

OpenID Connect adds another parameter that may be returned from the authorization endpoint (and/or the token endpoint): the ID token. OpenID Connect Core 1.0 explains, “The primary extension that OpenID Connect makes to OAuth 2.0 to enable End-Users to be Authenticated is the ID Token data structure.” (see “OpenID Connect Core 1.0, 2. ID Token”).

Authorization Response Parameters

Parameter	Description
Authorization Code	An opaque string to be exchanged for an access token at the token endpoint. The authorization code is valid for a short period of time.
—	—
Access Token	An opaque string, issued by the authorization endpoint, representing the end-user and the permissions (scopes) they granted to a particular client application. (Note that an access token issued using Client Credentials Flow contains no information about the end-user.)
—	—
ID Token	A JSON Web Token (JWT) containing information about the end-user.

Before OpenID Connect, the authorization endpoint could return either an authorization code or an access token, but not both. However, with OpenID Connect, the authorization endpoint can return all three objects depending on the value of the response_type request parameter:

response_type and Response Parameters

response_type	Returned Objects
response_type	Authorization Code	Access Token	ID Token
`none`
`code`
`token`
`id_token`
`code token`
`code id_token`
`id_token token`
`code id_token token`

In a response from the authorization endpoint, an authorization code, an access token and an ID token are embedded using the code key, access_token key and id_token key, respectively. For example, code=SplxlOBe in a response means that the value of the authorization code is SplxlOBe.

The following response parameters may be returned from the authorization endpoint:

Authorization Endpoint Response Parameters

Name	Description
`code`	An authorization code issued to the client application. This is contained in a successful response when the `response_type` request parameter of the authorization request contained `code`.
`access_token`	An access token issued to the client application. This is contained in a successful response when the `response_type` request parameter of the authorization request contained `token`.
`id_token`	An ID token issued to the client application. This is contained in a successful response when the `response_type` request parameter of the authorization request contained `id_token`.
`state`	When an authorization request contains the `state` request parameter, the authorization endpoint includes this parameter in the authorization response with the same value provided by the client.
`error`	An error code. This is contained in a response when an error occurred.
`error_description`	The short description of the error which happened. This may be contained in a response when an error occurred.
`error_uri`	The URI where the detailed description of the error can be found. This may be contained in a response when an error occurred.
`token_type`	The token type of the access token. This is contained in a successful response when the `response_type` request parameter of the authorization request contained `token`.
`expires_in`	The lifetime of the access token in seconds. This may be contained in a successful response when the `response_type` request parameter of the authorization request contained `token`.
`scope`	A space-delimited scope list of the access token. This may be contained in a successful response when the `response_type` request parameter of the authorization request contained `token`.

2. Response Format

For both Authorization Code Flow and Implicit Flow, OAuth 2.0 specifies that a successful response from the authorization endpoint is HTTP status “302 Found”, redirecting the user agent (the end-user’s web browser) to another location. In OAuth 2.0, the destination location is called redirect URI.

Response parameters are returned to the client application as a part of the redirect URI. For example, for an Authorization Code Flow with redirect URI https://client.example.org/callback and authorization code ap8uacb2, the response from the authorization endpoint to the client application will look like:

HTTP/1.1 302 Found
Location: https://client.example.org/callback?code=ap8uacb2
Cache-Control: no-store
Pragma: no-cache

If the flow is Implicit Flow, on the other hand, and the value of the access token is pqb8u3t, the response will look like:

HTTP/1.1 302 Found
Location: https://client.example.org/callback#access_token=pqb8u3t
                                             &token_type=Bearer
                                             &expires_in=3600
Cache-Control: no-store
Pragma: no-cache

(Line breaks added for clarity)

You might have noticed that the response parameters in the Authorization Code Flow are embedded in the query component (the part after ‘?’) but those in Implicit Flow are embedded in the fragment component (the part after ‘#’). This difference is a requirement of the OAuth 2.0 specification. In either case, “302 Found” is used. The following table summarizes the relationship between response_type and the response parameters’ location.

response_type And Response Parameter Location

response_type	HTTP Status	Response Parameter Location
code	302 Found	Embedded in the query component of the redirect URI in the Location header.
token	302 Found	Embedded in the fragment component of the redirect URI in the Location header.

OpenID Connect, specifically the OAuth 2.0 Form Post Response Mode, is more complex. It introduces a mechanism to control the response format and adds “200 OK” with an HTML as a new response format. This format is used when an authorization request includes the response_mode parameter with a value of form_post. Here’s an example from the specification (line breaks added for clarity).

HTTP/1.1 200 OK
Content-Type: text/html;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

<html>
  <head><title>Submit This Form</title></head>
  <body onload="javascript:document.forms[0].submit()">
    <form method="post" action="https://client.example.org/callback">
      <input type="hidden" name="state" value="DcP7csa3hMlvybERqcieLHrRzKBra"/>
      <input type="hidden" name="id_token"
        value="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiw
        iYXVkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLC
        Jpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5M
        DMxMTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1B
        SnllRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0F
        NTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2Mz
        kwMDg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqq
        wwq-Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fk
        IufbGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcq
        XVEKhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_h
        nrQ5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc
        0uVAwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA"/>
    </form>
  </body>
</html>

In the HTML above, the redirect URI is the value of the action attribute in the form tag; the response parameters are included in the form as hidden fields, state and id_token. (In this example, neither code nor access_token is embedded.)

After the HTML above is loaded by the user agent, the JavaScript written in the onload attribute of the body tag is executed. As a result, the browser is redirected to the redirect URI.

The table below illustrates the relationship between combinations of response_type & response_mode and the HTTP status & response parameters’ location. Note that the query component is not usable when an access token and/or an ID token are contained in the response.

response_type/response_mode Combinations And HTTP Status/Response Parameters' Location

`response_type`	`response_mode`
	(default)	`query`	`fragment`	`form_post`
	`302 Found`			`200 OK`
`none`	Query component	Query component	Fragment component	Hidden parameters
`code`	Query component	Query component	Fragment component	Hidden parameters
`token`	Fragment component	NOT ALLOWED	Fragment component	Hidden parameters
`id_token`
`code token`
`code id_token`
`id_token token`
`code id_token token`

3. Error Response

When an error occurs while a service is processing an authorization request, the service returns an error response to the client application. If the redirect URI to which the error should be reported had been determined before the error occurred, the redirect URI can be used.

When a redirect URI can be used, the error response parameter is always embedded. In addition, the error_description response parameter and the error_uri response parameter may optionally be embedded. For example, an error response looks like the following:

HTTP/1.1 302 Found
Location: https://client.example.org/callback?
  error=access_denied&
  error_description=The%20end-user%20denied%20the%20authorization%20request.
Cache-Control: no-store
Pragma: no-cache

(line breaks added for clarity)

OAuth 2.0 defines error response parameter values which may be returned from the authorization endpoint in 4.1.2.1. Error Response (for Authorization Code Flow) and in 4.2.2.1. Error Response (for Implicit Flow). OpenID Connect Core 1.0 adds values in 3.1.2.6. Authentication Error Response. The table below collects the error codes in alphabetical order.

Authorization Endpoint Error Values

Value	RFC 6749	OpenID Connect
`access_denied`
`account_selection_required`
`consent_required`
`interaction_required`
`invalid_request`
`invalid_request_object`
`invalid_request_uri`
`invalid_scope`
`login_required`
`registration_not_supported`
`request_not_supported`
`request_uri_not_supported`
`server_error`
`temporarily_unavailable`
`unauthorized_client`
`unsupported_response_type`

4. Returning Errors when the Redirect URI is Unavailable

Errors may occur before the redirect URI is determined. For example, if the specified client ID (client_id) is invalid, it is impossible to check whether the specified redirect URI (redirect_uri) has been registered or not, so the error cannot be reported to the redirect URI.

Section 3.1.2.4. Invalid Endpoint of the OAuth 2.0 specification says:

If an authorization request fails validation due to a missing, invalid, or mismatching redirection URI, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.

but the mechanism with which to inform the resource owner (end-user) of the error is not described anywhere. The authorization endpoint behavior is, therefore, determined by its implementer. Some candidate response formats:

HTTP Status	Content-Type	Comment
400 Bad Request	`text/html`	The error is described in HTML format and shown in the user agent. This is friendly to end-users and testers.
400 Bad Request	`application/json`	The error is described in JSON format in the same way as it is for token endpoint (OAuth 2.0, section 5.2. Error Response). This is friendly to client application developers.

Considering that OpenID Connect has added a use case (prompt=none) where no user interaction is performed, application/json might be better.

Authorization Interaction

1. Purpose Of Authorization Endpoint

The primary task of an authorization endpoint is to let an end-user grant authorization to a client application. In the normal case, this is achieved by displaying one or more HTML pages that

Show information about the client application and the requested permissions (scopes).
Provide a login form to authenticate the end-user.
Include buttons for the end-user to decide to “authorize” or “deny” the authorization request.

Here is a typical minimum set of UI components that an authorization endpoint can display:

Remember, OAuth 2.0 is a framework for authorization, not for authentication. As stated in section 3.1. Authorization Endpoint of the specification, “The way in which the authorization server authenticates the resource owner (e.g., username and password login, session cookies) is beyond the scope of [OAuth 2.0]”. Be that as it may, the end-user must be authenticated at the authorization endpoint because an access token must be associated with a resource owner (except the case of Client Credentials Grant).

Since OAuth 2.0 makes almost no mention of end-user authentication, implementers have implemented it as they liked. However, OpenID Connect adds mechanisms to control end-user authentication.

2. `prompt` Request Parameter

The optional prompt request parameter specifies “whether the Authorization Server prompts the End-User for reauthentication and consent”. (OpenID Connect Core 1.0, 3.1.2.1. Authentication Request)

Its value none or a space-delimited combination of login, consent and select_account:

Value	Description
`login`	When `prompt` contains `login`, the end-user must be authenticated even when they have already logged in.
`consent`	When `prompt` contains `consent`, consent must be obtained from the end-user even when the authorization endpoint implementation knows that the consent was obtained in the past.
`select_account`	When `prompt` contains `select_account`, the authorization endpoint implementation should prompt the end-user to select a user account.
`none`	When `prompt` is `none`, the authorization endpoint implementation must process the authorization request without displaying any UI (i.e., without user interaction).

The simplest implementation for a combination of login, consent and select_account is to always display a form having input fields for login ID and password. However, this is not appropriate if the authentication method at the authorization endpoint is different from the typical ID & password mechanism, for example, biometric authentication by fingerprints.

3. Authentication Context Class Reference

Authentication Context Class Reference, which is also referred to as ACR in OpenID Connect specifications, is a string representing a set of context, level and/or other attributes of an authentication method. For example, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport represents the authentication method which is performed by presenting a password over a protected (i.e. TLS) session. (This example is an excerpt from Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0.)

OpenID Connect Core 1.0 does not specify any concrete ACR values other than “0”. Instead, it just states that parties using ACR values (i.e. the OAuth server and the client application) “need to agree upon the meanings of the values used”. (OpenID Connect Core 1.0, 2. ID Token, acr)

3.1 `acr_values` Request Parameter

An authorization request can include the acr_values request parameter (OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, acr_values) to specify a list of ACRs in a preferred order. When this request parameter is present, the authorization endpoint implementation should satisfy one of them in authenticating the end-user.

3.2 `acr` Claim In `claims` Request Parameter

Another way to present a list of ACRs is by including the acr claim in the value of the claims request parameter. The following JSON is an example of a value of the claims request parameter (excerpt from OpenID Connect Core 1.0, 5.5. Requesting Claims using the “claims” Request Parameter):

{
  "userinfo":
    {
      "given_name": {"essential": true},
      "nickname": null,
      "email": {"essential": true},
      "email_verified": {"essential": true},
      "picture": null,
      "http://example.info/claims/groups": null
    },
  "id_token":
    {
      "auth_time": {"essential": true},
      "acr": {"values": ["urn:mace:incommon:iap:silver"] }
    }
}

The requirement for ACR can be marked as “essential” only via the claims request parameter.

{
  "id_token":
    {
      "acr":
        {
          "essential": true,
          "values": ["urn:mace:incommon:iap:silver"]
        }
    }
}

If the acr claim is requested as essential, one of the ACRs listed in values must be satisfied. If none of them can be satisfied, the authorization endpoint implementation must return an error response to the client application. See OpenID Connect Core 1.0, 5.5.1.1. Requesting the “acr” Claim for details.

3.3 `acr` Claim In ID Token

The acr claim is an optional claim that may be embedded in an ID token. See “OpenID Connect Core 1.0, 2. ID Token, acr” for details.

3.4 Supported ACRs

“OpenID Connect Discovery 1.0, 3. OpenID Provider Metadata” lists attributes of an OpenID provider. Among them, the acr_values_supported metadata contains a list of ACRs supported by the OpenID provider. In Authlete, the equivalent is the supportedAcrs property of Service.

3.5 Default ACRs

“OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata” lists attributes of a client application. Among them, the default_acr_values metadata contains a list of the default ACRs of the client application that should be used when an authorization request from the client application does not have ACR values explicitly (by the acr_values request parameter or by the values of the acr claim in the claims request parameter). In Authlete, the equivalent is the defaultAcrs property of Client.

4 Maximum Authentication Age

Maximum Authentication Age is “the allowable elapsed time in seconds since the last time the End-User was actively authenticated” (OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, max_age). If the elapsed time is greater than the maximum authentication age, the end-user must be re-authenticated even if he/she has already logged in.

4.1 `max_age` Request Parameter

An authorization request can include the max_age request parameter to specify the maximum authentication age.

4.2 Default Maximum Authentication Age

The default_max_age attribute listed in “OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata” is the maximum authentication age which is used when an authorization request from the client application does not have the max_age request parameter. In Authlete, the equivalent is the defaultMaxAge property of Client.

5. `sub` claim

A client application can request a specific subject (an end-user identifier assigned by the service) from whom the client application wants to be granted authorization by specifying the value for the sub claim. The following is an example of a value of the claims request parameter that contains the sub claim with a value:

{
  "id_token":
    {
      "sub": {"value": "248289761001"}
    }
}

When an authorization request specifies a subject, the corresponding end-user must be authenticated. If this is not satisfied, the authorization endpoint implementation must return an error response to the client application. See OpenID Connect Core 1.0, 3.1.2.2. Authentication Request Validation for details.

6. `login_hint` Request Parameter

A client application can give a hint about the login identifier to the authorization endpoint by using the login_hint request parameter. For example, an email address may be specified as the value.

7. `id_token_hint` Request Parameter

A client application can make an authorization request with the id_token_hint request parameter whose value is the ID token previously issued by the authorization server. The authorization server should return an error response when the end-user identified by the ID token is different from the end-user who is authenticated already or as a result of the request.

8. No Interaction

OpenID Connect introduced a mechanism for the authorization endpoint to return a response without user interaction. A client application can request it by including prompt=none in the authorization request.

An authorization request with prompt=none can be processed successfully only when all the following conditions are satisfied:

The end-user has already logged in.
If the maximum authentication age is specified by either the max_age request parameter or the default_max_age property of the client metadata, the elapsed time since the last authentication of the end-user does not exceed the maximum authentication age.
If a specific subject is requested by the sub claim in the value of the claims request parameter, the login ID of the end-user matches the subject.
If the acr claim is marked as essential in the value of the claims request parameter, the authentication method satisfies one of the authentication context class references which are listed in the values property of the acr claim).
If claims are requested, the end-user has consented to them in advance. (Means to obtain consent are beyond the specification of OpenID Connect.)