Definitive Guide

Authorization interaction

  1. Purpose Of Authorization Endpoint
  2. prompt Request Parameter
  3. Authentication Context Class Reference
    1. 3.1. acr_values Request Parameter
    2. 3.2. acr Claim In claims Request Parameter
    3. 3.3. acr Claim In ID Token
    4. 3.4. Supported ACRs
    5. 3.5. Default ACRs
  4. Maximum Authentication Age
    1. 4.1. max_age Request Parameter
    2. 4.2. Default Maximum Authentication Age
  5. sub Claim
  6. login_hint Request Parameter
  7. id_token_hint Request Parameter
  8. No 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.

Example Client is requesting permissions.

  1. public_profile
  2. public_actions
  3. user_friends
  • Login ID :
  • Password :

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.

Values For The prompt Request Parameter
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.)