Definitive Guide

Authorization request

  1. Path
  2. Security
  3. HTTP methods
  4. Request Parameters

This chapter and the following two chapters describe 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.

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.

Request Parameters For The Authorization Endpoint In RFC 6749
No. Name Requirement Description
1 response_type REQUIRED

code for Authorization Code Grant and token for Implicit Grant.

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

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

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

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

Request Parameters For The Authorization Endpoint In OpenID Connect
No. Name Requirement Description
1 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.

2 client_id REQUIRED

The same requirement as RFC 6749.

3 redirect_uri REQUIRED

In RFC 6749, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED.

4 scope REQUIRED

In RFC 6749, this request parameter is OPTIONAL. But in OpenID Connect, it is REQUIRED and must contain openid.

5 state RECOMMENDED

The same requirement as RFC 6749.

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

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

8 display OPTIONAL

A new request parameter to specify how the user interface should be displayed to the end-user.

9 prompt OPTIONAL

A new request parameter to specify whether the service should prompt the end-user for re-authentication and consent.

10 max_age OPTIONAL

A new request parameter to specify the maximum authentication age.

11 ui_locales OPTIONAL

A new request parameter to specify preferred languages and scripts for the user interface.

12 id_token_hint OPTIONAL

A new request parameter to specify the ID token previously issued by the service.

13 login_hint OPTIONAL

A new request parameter to specify a hint about the login identifier that the end-user may use.

14 acr_values OPTIONAL

A new request parameter to specify ACRs (Authentication Context Class References) one of which the client application requests to be satisfied.

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

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

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

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

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

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

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