Authorization Endpoint (Spec)

Authorization Request

This part describes requirements for the authorization endpoint, mainly focusing on the differences between RFC 6749 and OpenID Connect. If you are familiar with the specifications, you can skip this chapter and jump to Authorization Endpoint Implementation.

1. Path

As to the path of the authorization endpoint, only one requirement by RFC 6749 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 path of an authorization endpoint. An example of an entire URI with the path is https://example.com/auth/authorization.

2. Security

RFC 6749 requires that the authorization endpoint use TLS (Transport Layer Security).

3. HTTP methods

According to RFC 6749, 3.1. Authorization Endpoint, the authorization endpoint must support HTTP GET method, and HTTP POST method is optional. However, OpenID Connect Core 1.0, 3.1.2.1. Authentication Request requires that the authorization endpoint support HTTP POST method. In the case of POST, the request parameters must be formatted in application/x-www-form-urlencoded.

Table. HTTP Methods Of The Authorization Endpoint

HTTP method RFC 6749 OpenID Connect
GET  MUST MUST
POST MAY MUST

4. Request Parameters

RFC 6749 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 as shown in the table below.

Table. Request Parameters For The Authorization Endpoint In RFC 6749

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 which is 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. Valid scope values are defined by a service.
Some implementations of OAuth 2.0 (e.g. Facebook) require a comma-delimited list, but it is just a violation against the specification.
state RECOMMENDED An opaque value that the client application may use. If this request parameter is contained in the authorization request, it is passed to the redirect URI.

One of the biggest impacts introduced by OpenID Connect into OAuth 2.0 is the additions of request parameters and request parameter values to the authorization endpoint. Most of them are described in OpenID Connect Core 1.0, 3.1.2.1. Authentication Request. The following table is an aggregated list of request parameters defined in RFC 6749, OpenID Connect and other specifications.

Table. Request Parameters For The Authorization Endpoint In OpenID Connect

Name Requirement Description
response_type REQUIRED In RFC 6749, the valid values of this request parameter are just two, namely, code and token. However, OpenID Connect has extended them to combinations of code, id_token and token, or none. As a result, the valid values are as follows.
  1. none
  2. code
  3. token
  4. id_token
  5. code token
  6. code id_token
  7. id_token token
  8. code id_token token
See OAuth 2.0 Multiple Response Type Encoding Practices for details.
client_id REQUIRED The same requirement as RFC 6749.
redirect_uri REQUIRED In RFC 6749, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED.
scope REQUIRED In RFC 6749, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED and must contain openid.
state RECOMMENDED The same requirement as RFC 6749.
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

According to RFC 6749, on success, the authorization endpoint issues either an authorization code or an access token.

OpenID Connect has added another object which may be returned from the authorization endpoint (and/or the token endpoint). It is an ID token. OpenID Connect Core 1.0 says “The primary extension that OpenID Connect makes to OAuth 2.0 to enable End-Users to be Authenticated is the ID Token data structure.” (an excerpt from “OpenID Connect Core 1.0, 2. ID Token”).

Short summaries of the objects are as follows.

Table. Obejects Returned from the Authorizatoin Endpoint

Authorization Code Access Token ID Token
An opaque string or number which is a kind of short-lived ticket to be exchanged with an access token at the token endpoint. An opaque string or number which denotes who (end-user) has granted what permissions (scopes) to which client application.
(An access token issued using Client Credentials Flow has no information about who.)
A JWT which contains pieces of information about the end-user.

Before OpenID Connect, it was a simple world where the authorization endpoint returned either an authorization code or an access token. Not both. However, after OpenID Connect, the authorization endpoint returns at maximum all the three objects depending on the value of the response_type request parameter. The following table illustrates the relationship between response_type and returned objects.

Table. The Relationship Between response_type and Returned Objects

response_type Returned Objects
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 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.

Response parameters that may be returned from the authorization endpoint are as follows.

Table. Response Parameters From The Authorization Endpoint

No. Name Description
1 code

An authorization code issued to the client application. This is contained in a successful response when response_type request parameter of the authorization request contained code.

2 access_token

An access token issued to the client application. This is contained in a successful response when response_type request parameter of the authorization request contained token.

3 id_token

An ID token issued to the client application. This is contained in a successful response when response_type request parameter of the authorization request contained id_token.

4 state

When an authorization request contains state request parameter, the authorization endpoint includes the parameter in the authorization response without changing the value.

5 error

An error code. This is contained in a response when an error occurred.

6 error_description

The short description of the error which happened. This may be contained in a response when an error occurred.

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

8 token_type

The token type of the access token. This is contained in a successful response when response_type request parameter of the authorization request contained token.

9 expires_in

The lifetime in seconds of the access token. This may be contained in a successful response when response_type request parameter of the authorization request contained token.

10 scope

A space-delimited scope list of the access token. This may be contained in a successful response when response_type request parameter of the authorization request contained token.

2. Response Format

According to RFC 6749, in both Authorization Code Flow and Implicit Flow, the HTTP status of a successful response from the authorization endpoint is “302 Found”, which triggers the user agent (= the web browser the end-user is using) to be redirected to another location from the authorization endpoint. 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, if (1) the flow is Authorization Code Flow, (2) the redirect URI is https://client.example.org/callback, and (3) the value of the authorization code is ap8uacb2, the response from the authorization endpoint to the client application will look like the following.

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

Another example. If the flow is Implicit Flow and the value of the access token is pqb8u3t, the response will look like the following (with extra line breaks for display purposes only).

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

You might have noticed that the response parameters in 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 by RFC 6749. In either case, “302 Found” is used. The following table summarizes the relationship between response_type and response parameters’ location.

Table. Relationship Between response_type And Response Parameter's Location

response_type HTTP status Response Parameters’ 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.

However, OpenID Connect, to be exact, OAuth 2.0 Form Post Response Mode, has added some complexities here. It has introduced a mechanism to control the response format and added “200 OK” with an HTML as a new response format. This format is used when an authorization request comes along with response_mode=form_post. The following is an excerpt from the specification (with extra line breaks for display purposes only).

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 set as the value of action attribute of the form tag and response parameters as hidden parameters. You can find two response parameters, namely, 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, redirection to the redirect URI is performed.

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.

Table. Relationship Between 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
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 be optionally embedded. For example, an error response looks like the following. (extra line breaks for display purposes only)

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

[RFC 6749]() defines values of error response parameter 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 added values in 3.1.2.6. Authentication Error Response. The table below aggregates the error codes in alphabetical order.

Table. Values of error from the Authorization Endpoint

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

RFC 6749, 3.1.2.4. Invalid Endpoint 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 means about how to inform the resource owner (= end-user) of the error is not described anywhere. Therefore, the authorization endpoint has to decide its way. The following are some candidates of 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 the token endpoint does (RFC 6749, 5.2. Error Response). This is friendly to developers of client applications.

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 an HTML page which

  1. shows information about the client application and the requested permissions (scopes),
  2. provides a login form to authenticate the end-user, and
  3. two buttons for the end-user to decide “authorize” or “deny” the authorization request.

The following form shows a typical minimum set of UI components that an authorization endpoint displays.

editing token supported scopes

OAuth is a framework for authorization, but not for authentication. As stated in RFC 6749, 3.1. Authorization Endpoint, “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. Be that as it may, it is sure that 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 RFC 6749 mentions almost nothing about end-user authentication, implementors have implemented it as they liked. However, OpenID Connect has added some mechanisms to control end-user authentication. The following subsections describe them.

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 is a space-delimited combination of login, consent and select_account or none, which must not be combined with other values. The following table explains the requirements of the values.

Value Description
login When prompt contains login, the end-user must be authenticated even when he/she has 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 (= 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. But, this is not the case if the authentication method at the authorization endpoint is different from the typical one by ID & password (e.g. in the case of 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 which represents 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 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 show any concrete ACR values other than “0”. Instead, it just says 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 have 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 the preferred order. When the request parameter is contained, the authorization endpoint implementation should satisfy one of them for end-user authentication.

3.2 acr Claim In claims Request Parameter

There is another way to present a list of ACRs. It can be done 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 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 have 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 requests a specific subject, end-user authentication must be performed for the subject. 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 has introduced a means to perform the task at the authorization endpoint 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 conditions listed below are satisfied.

  1. An end-user has already logged in.
  2. 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.
  3. 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.
  4. 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).
  5. If claims are requested, consent to them have been obtained in advance. (Means to obtain the consent are beyond the specification of OpenID Connect.)