Table Of Contents
- What you need to implement
Authorization Endpoint (Spec)
Authorization Endpoint (Impl)
- Token Request
- Protected Resource
- Authentication Callback
- Developer Authentication Callback
- Extra Properties
- Purpose Of Authorization Endpoint
- Authentication Context Class Reference
- Maximum Authentication Age
- 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
- shows information about the client application and the requested permissions (scopes),
- provides a login form to authenticate the end-user, and
- 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.
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.
prompt Request Parameter
prompt request parameter specifies
"whether the Authorization Server prompts the End-User for
reauthentication and consent".
(OpenID Connect Core 1.0, 220.127.116.11. Authentication Request)
Its value is a space-delimited combination of
none, which must not be combined with other values.
The following table explains the requirements of the values.
The simplest implementation for a combination of
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,
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)
acr_values Request Parameter
An authorization request can have the
acr_values request parameter
(OpenID Connect Core 1.0, 18.104.22.168. 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.
acr Claim In
claims Request Parameter
There is another way to present a list of ACRs. It can be done by
acr claim in the value of the
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).
The requirement for ACR can be marked as "essential" only via the
claims request parameter.
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, 22.214.171.124. Requesting the
"acr" Claim for details.
acr Claim In ID Token
acr claim is an optional claim that may be embedded
in an ID token. See "OpenID Connect Core 1.0, 2. ID Token, acr"
3.4. Supported ACRs
"OpenID Connect Discovery 1.0, 3. OpenID Provider Metadata"
lists attributes of an OpenID provider. Among them, the
metadata contains a list of ACRs supported by the OpenID provider.
In Authlete, the equivalent is the
supportedAcrs property of
3.5. Default ACRs
"OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata"
lists attributes of a client application. Among them, the
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
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
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, 126.96.36.199. 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.
max_age Request Parameter
An authorization request can have the
parameter to specify the maximum authentication age.
4.2. Default Maximum Authentication Age
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
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
claims request parameter that contains the
sub claim with a value.
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, 188.8.131.52. Authentication Request Validation for details.
login_hint Request Parameter
A client application can give a hint about the login identifier to
the authorization endpoint by using the
request parameter. For example, an email address may be specified
as the value.
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
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
An authorization request with
prompt=none can be processed
successfully only when all the conditions listed below are satisfied.
- An end-user has already logged in.
If the maximum authentication age is specified by either the
max_agerequest parameter or the
default_max_ageproperty 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
subclaim in the value of the
claimsrequest parameter, the login ID of the end-user matches the subject.
acrclaim is marked as essential in the value of the
claimsrequest parameter, the authentication method satisfies one of the authentication context class references which are listed in the
valuesproperty of the
- If claims are requested, consent to them have been obtained in advance. (Means to obtain the consent are beyond the specification of OpenID Connect.)