Documentation

Note: In the description below, "authorization server" is always used even where "OpenID provider" should be used.

Authlete's /api/auth/authorization API returns JSON which can be mapped to this class. The authorization server implementation should retrieve the value of the action response parameter (which can be obtained by getAction() method) from the response and take the following steps according to the value.

When the value returned from getAction() method is AuthorizationAction::$INTERNAL_SERVER_ERROR, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with the HTTP status of 500 Internal Server Error. Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable.

In this case, getResponseContent() method returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

When the value returned from getAction() method is AuthorizationAction::$BAD_REQUEST, it means that the request from the client application was invalid. The HTTP status of the response returned to the client application should be 400 Bad Request and Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable.

In this case, getResponseContent() method returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

When the value returned from getAction() method is AuthorizationAction::$LOCATION, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined. The HTTP status of the response returned to the client application should be 302 Found and the Location header must have a redirect URI with an error response parameter.

In this case, getResponseContent() method returns the redirect URI which has the error response parameter, so it can be used as the value of Location header. The following illustrates the response which the authorization server implementation should generate and return to the client application.

HTTP/1.1 302 Found
Location: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is AuthorizationAction::$FORM, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined, and that the request contains response_mode=form_post as is defined in OAuth 2.0 Form Post Response Mode. The HTTP status of the response returned to the client application should be 200 OK and the content type should be text/html;charset=UTF-8.

In this case, getResponseContent() method returns an HTML which satisfies the requirements of response_mode=form_post, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.

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

(The value returned from getResponseContent())

When the value returned from getAction() method is AuthorizationAction::$NO_INTERACTION, it means that the request from the client application has no problem and requires the authorization server to process the request without displaying any user interface for authentication and/or consent. This happens when the request contains prompt=none.

In this case, the authorization server implementation should follow the steps below.

• [END-USER AUTHENTICATION]

  Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX AGE]). Otherwise, call Authlete's /api/auth/authorization/fail API with reason=NOT_LOGGED_IN and use the response from the API to generate a response to the client application.

Get the value of the max age by `getMaxAge()` method. The value
represents the maximum authentication age which has come from the
`max_age` request parameter or the `default_max_age` configuration
parameter of the client application. If the value is 0, go to the
next step (**[SUBJECT]**). Otherwise, follow the sub steps described
below.

1. Get the time at which the end-user was authenticated. Note that
   this value is not managed by Authlete, meaning that it is expected
   that the authorization server implementation manages the value.
   If the authorization server implementation does not manage
   authentication time of end-users, call Authlete's
   `/api/auth/authorization/fail` API with
   `reason=MAX_AGE_NOT_SUPPORTED` and use the response from the API
   to generate a response to the client application.

2. Add the value of the maximum authentication age (which is
   represented in seconds to the authentication time.

3. Check whether the calculated value is equal to or greater than
   the current time. If this condition is satisfied, go to the next
   step (**[SUBJECT]**). Otherwise, call Authlete's
   `/api/auth/authorization/fail` API with `reason=EXCEEDS_MAX_AGE`
   and use the response from the API to generate a response to the
   client application.

Get the value of the requested subject by `getSubject()` method.
The value represents an end-user who the client application expects
to grant authorization. If the value is `null`, go to the next step
(**[ACRs]**). Otherwise, follow the sub steps described below.

1. Compare the value of the requested subject to the subject (=
   unique user ID) of the current end-user.

2. If they are equal, go to the next step (**[ACRs]**).

3. If they are not equal, call Authlete's `/api/auth/authorization/fail`
   API with `reason=DIFFERENT_SUBJECT` and use the response from the
   API to generate a response to the client application.

Get the value of ACRs (Authentication Context Class References) by
`getAcrs()` method. The value has come from (1) the `acr` claim in
the `claims` request parameter, (2) the `acr_values` request parameter,
or (3) the `default_acr_values` configuration parameter of the client
application.

It is ensured that all the ACRs returned by `getAcrs()` method are
supported by the authorization server implementation. In other words,
it is ensured that all the ACRs are listed in the
`acr_values_supported` configuration parameter of the authorization
server.

If the value of ACRs is `null`, go to the next step (**[SCOPES]**).
Otherwise, follow the sub steps described below.

1. Get the ACR performed for the authentication of the current
   end-user. Note that this value is managed not by Authlete but by
   the authorization server implementation. (If the authorization
   server implementation cannot handle ACRs, it should not have
   listed ACRs in the `acr_values_supported` configuration parameter.)

2. Compare the ACR value obtained in the above step to each element
   in the ACR array obtained by `getAcrs()` method in the listed
   order. If the ACR value was found in the array, go to the next
   step (**[SCOPES]**).

3. If the ACR value was not found in the ACR array (= if the ACR
   performed for the authentication of the current end-user did not
   match any one of the ACRs requested by the client application),
   check whether one of the requested ACRs must be satisfied or not
   by calling `isAcrEssential()` method. If `isAcrEssential()`
   returns `true`, call Authlete's `/api/auth/authorization/fail`
   API with `reason=ACR_NOT_SATISFIED` and use the response from
   the API to generate a response to the client application.
   Otherwise, go to the next step (**[SCOPES]**).

Get the scopes by `getScopes()` method. If the array contains one or
more scopes which have not been granted to the client application by
the end-user in the past, call Authlete's
`/api/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and
use the response from the API to generate a response to the client
application. Otherwise, go to the next step (**[ISSUE]**).

Note that Authlete provides APIs to manage records of granted scopes
(`/api/client/granted_scopes/*` APIs), but the APIs work only in the
case the Authlete server you use is a dedicated Authlete server
(contact [sales@authlete.com](mailto:sales@authlete.com) for details).
In other words, the APIs of the shared Authlete server are disabled
intentionally (in order to prevent garbage data from being accumulated)
and they return `403 Forbidden`.

If all the above steps succeeded, the last step is to issue an
authorization code, an ID token and/or an access token
(`response_type=none` is a special case where nothing is issued).
The last step can be performed by calling Authlete's
`/api/auth/authorization/issue` API. The API requires the following
parameters, which are represented as properties of the
`AuthorizationIssueRequest` class. Prepare these parameters and call
the `/api/auth/authorization/issue` API.

* `ticket` (required): This parameter represents a ticket which is
  exchanged with tokens at the `/api/auth/authorization/issue` API.
  Use the value returned from `getTicket()` method as it is.

* `subject` (required): This parameter represents the unique identifier
  of the current end-user. It is often called "User ID" and it may or
  may not be visible to the end-user. In any case, it is a number or a
  string assigned to the end-user by your service. Authlete does not
  care about the format of the value of the subject, but it must
  consist of only ASCII letters and its length must be equal to or less
  than 100.

  When `getSubject()` method of `AuthorizationResponse` class
  returns a non-null value, the value of `subject` request parameter
  to `/api/auth/authorization/issue` API is necessarily identical.

  The value of this request parameter will be embedded in an ID token
  as the value of the `sub` claim. When the value of the `subject_type`
  configuration parameter of the client is `PAIRWISE`, the value of the
  `sub` claim is different from the value specified here, but `PAIRWISE`
  is not supported by Authlete yet. See
  [8. Subject Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes)
  of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
  for details about subject types.

  You can use the `sub` request parameter to adjust the value of the
  `sub` claim in an ID token. See the description of the `sub` request
  parameter for details.

* `authTime` (optional): This parameter represents the time when the
  end-user authentication occurred. Its value is the number of seconds
  since the Unix epoch (1970-Jan-1). The value of this parameter will
  be embedded in an ID token as the value of the `auth_time` claim.

* `acr` (optional): This parameter represents the ACR (Authentication
  Context Class Reference) which the authentication of the end-user
  satisifes. When `getAcrs()` method returns a non-empty array and
  `isAcrEssential()` method returns `true`, the value of this parameter
  must be one of the array elements. Otherwise, even `null` is allowed.
  The value of this parameter will be embedded in an ID token as the
  value of the `acr` claim.

* `claims` (optional): This parameter represents claims of the end-user.
  "Claims" here are pieces of information about the end-user such as
  `name`, `email` and `birthdate`. The authorization server
  implementation is required to gather claims of the end-user, format
  the claim values into JSON and set the JSON string as the value of
  this parameter.

  The claims which the authorization server implementation is required
  to gather can be obtained by `getClaims()` method.

  For example, if `getClaims()` method returns an array which contains
  `name`, `email` and `birthdate`, the value of this parameter should
  look like the following.

  ```
  {
      "name": "John Smith",
      "email": "john@example.com",
      "birthdate": "1974-05-06"
  }
  ```

  `getClaimsLocales()` methods lists the end-user's preferred languages
  and scripts for claim values, ordered by preference. When
  `getClaimsLocales()` method returns a non-empty array, its elements
  should be taken into consideration when the authorization server
  implementation gathers claim values. Especially, note the excerpt
  below from
  [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)
  of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html).

  > *"When the OP determines, either through the `claims_locales`
  > parameter, or by other means, that End-User and Client are
  > requesting Claims in only one set of languages and scripts,
  > it is RECOMMENDED that OPs return Claims without language
  > tags when they employ this language and script. It is also
  > RECOMMENDED that Clients be written in a manner that they
  > can handle and utilize Claims using language tags."*

  If `getClaims()` method returns `null` or an empty array, the value
  of this parameter should be `null`.

  See [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)
  of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
  for claim names and their value formats. Note (1) that the
  authorization server implementation may support its special claims
  ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims))
  and (2) that claim names may be followed by a language tag
  ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)).
  Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
  for details.

  The claim values in this parameter will be embedded in an ID token.

  `getIdTokenClaims()` is available since version 1.7. The method
  returns the value of the `id_token` property in the `claims`
  request parameter or in the `claims` property in a request object.
  The value returned from the method should be considered when you
  prepare claim values. See the description of the method for details.

* `properties` (optional): Extra properties to be associated with an
  access token and/or an authorization code that may be issued from
  the Authlete API. Note that the `properties` request parameter is
  accepted only when `Content-Type` of the request to Authlete's
  `/api/auth/authorization/issue` API is `application/json`, so don't
  use `application/x-www-form-urlencoded` if you want to use this
  request parameter.

* `scopes` (optional): Scopes to be associated with an access token
  and/or an authorization code. If this parameter is `null`, the
  scopes specified in the original authorization request from the
  client application are used. In other cases, the specified scopes
  by this parameter will replace the scopes contained in the original
  authorization request.

  Even scopes that are not included in the original authorization
  request can be specified. However, as an exception, the `openid`
  scope is ignored on Authlete server side if it is not included in
  the original request. It is because the existence of the `openid`
  scope considerably changes the validation steps and because adding
  `openid` triggers generation of an ID token (although the client
  application has not requested it) and the behavior is a major
  violation against the specification.

  If you add the `offline_access` scope although it is not included
  in the original request, keep in mind that the specification
  requires explicit consent from the end-user for the scope
  ([11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)
  of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)).
  When `offline_access` is included in the original authorization
  request, the current implementation of Authlete's
  `/api/auth/authorization` API checks whether the authorization
  request has come along with the `prompt` request parameter and its
  value includes `consent`. However, note that the implementation of
  Authlete's `/api/auth/authorization/issue` API does not perform the
  same validation even if the `offline_access` scope is added via this
  `scopes` parameter.

* `sub` (optional): The value of the `sub` claim in an ID token which
  may be issued. If the value of this request parameter is not empty,
  it is used as the value of the `sub` claim. Otherwise, the value of
  the `subject` request parameter is used as the value of the `sub`
  claim. The main purpose of this parameter is to hide the actual
  value of the subject from client applications.

`/api/auth/authorization/issue` API returns a response in JSON format
which can be mapped to `AuthorizationIssueResponse`. Use the response
from the API to generate a response to the client application. See the
description of `AuthorizationIssueResponse` for details.

When the value returned from getAction() method is AuthorizationAction::$INTERACTION, it means that the request from the client application has no problem and requires the authorization server to process the request with user interaction by an HTML form.

The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to a client application. The items described below are some points which the authorization server implementation should take into consideration when it builds the UI.

• [DISPLAY MODE]

  AuthorizationResponse contains display parameter. The value can be obtained by getDisplay() method and it is one of PAGE (default), POPUP, TOUCH and WAP. The meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Basically, the authorization server implementation should display the UI which is suitable for the display mode, but it is okay for the authorization server implementation to "attempt to detect the capabilities of the User Agent and present an appropriate display."

  It is ensured that the value returned from getDisplay() method is one of the supported display values which are specified by the display_values_supported configuration parameter of the authorization server.

`AuthorizationResponse` contains `ui_locales` parameter. The value can
be obtained by `getUiLocales()` method and it is an array of language
tag values (such as `fr-CA` and `en`) ordered by preference. The
authorization server implementation should display the UI in one of
the languages listed in the `ui_locales` parameter when possible.

It is ensured that language tags returned from `getUiLocales()`
method are contained in the list of supported UI locales which are
specified by the `ui_locales_supported` configuration parameter of
the authorization server.

The authorization server implementation should show the end-user
information about the client application. The information can be
obtained by `getClient()` method.

A client application requires authorization for specific permissions.
In OAuth 2.0 specification, *"scope"* is a technical term which
represents a permission. `getScopes()` method returns scopes
requested by the client application. The authorization server
implementation should show the end-user the scopes.

The authorization server implementation may choose not to show scopes
to which the end-user has given consent in the past. To put it the
other way around, the authorization server implementation may show
only the scopes to which the end-user has not given consent yet.
However, if the value returned from `getPrompts()` method contains
`Prompt::$CONSENT`, the authorization server implementation has to
obtain explicit consent from the end-user even if the end-user has
given consent to all the requested scopes in the past.

Note that Authlete provides APIs to manage records of granted scopes
(`/api/client/granted_scopes/*` APIs), but the APIs work only in the
case the Authlete server you use is a dedicated Authlete server
(contact [sales@authlete.com](mailto:sales@authlete.com) for details).
In other words, the APIs of the shared Authlete server are disabled
intentionally (in order to prevent garbage data from being accumulated)
and they return `403 Forbidden`.

It is ensured that scopes returned from `getScopes()` method are
contained in the list of supported scopes parameter of the
authorization server.

Necessarily, the end-user must be authenticated (= must login your
service) before granting authorization to the client application.
Simply put, a login form is expected to be displayed for end-user
authentication. The authorization server implementation must follow
the steps described below to comply with OpenID Connect. (Or just
always show a login form if it's too much of a bother to follow the
steps below).

1. Get the value from `getPrompts()` method. It corresponds to the
   value of the `prompt` request parameter. Details of the request
   parameter are described in
   [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
   of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html).

2. If the value returned from `getPrompts()` method contains
   `Prompt::$SELECT_ACCOUNT`, display a form to urge the end-user
   to select one of his/her accounts for login. If `getSubject()`
   method returns a non-null value, it is the end-user ID that the
   client application expects, so the value should be used to
   determine the value of the login ID. Note that a subject and a
   login ID are not necessarily equal. If `getSubject()` method
   returns `null`, the value returned from `getLoginHint()` method
   should be referred to as a hint to determine the value of the
   login ID. `getLoginHint()` method simply returns the value of
   the `login_hint` request parameter.

3. If the value returned from `getPrompts()` method contains
   `Prompt::$LOGIN`, display a form to urge the end-user to login
   even if the end-user has already logged in. If `getSubject()`
   method returns a non-null value, it is the end-user ID that the
   client application expects, so the value should be used to
   determine the value of the login ID. Note that a subject and a
   login ID are not necessarily equal. If `getSubject()` method
   returns `null`, the value returned from `getLoginHint()` should
   be referred to as a hint to determine the value of the login ID.
   `getLoginHint()` method simply returns the value of the
   `login_hint` request parameter.

4. If the value returned from `getPrompts()` method does not contain
   `Prompt::$LOGIN`, the authorization server implementation does not
   have to authenticate the end-user if all the conditions described
   below are satisfied. If any one of the condisionts is not satisfied,
   show a login form to authenticate the end-user.

   * An end-user has already logged in your service.

   * The login ID of the current end-user matches the value returned
     from the `getSubject()` method. This check is required only when
     the `getSubject()` method returns a non-null value.

   * The max age, which is the number of seconds obtained by
     `getMaxAge()` method, has not passed since the current end-user
     logged in your service. This check is required only when
     `getMaxAge()` method returns a non-zero value.

     If the authorization server implementation does not manage
     authentication time of end-users (= if the authorization server
     implementation cannot know when end-users logged in) and if
     `getMaxAge()` method returns a non-zero value, a login form
     should be displayed.

   * The ACR (Authentication Context Class Reference) of the
     authentication performed for the current end-user satisfies one
     of the ACRs listed in the value returned from `getAcrs()` method.
     This check is required only when `getAcrs()` method returns a
     non-empty array.

In every case, the end-user authentication must satisfy one of the ACRs
listed in the value returned from `getAcrs()` method when the method
returns a non-empty array and `isAcrEssential()` method returns `true`.

The end-user is supposed to choose either (1) to grant authorization
to the client application or (2) to deny the authorization request.
The UI must have UI components to accept the decision by the end-user.
Usually, a button to grant authorization and a button to deny the
request are provided.

The end-user will choose either (1) to grant authorization to the client application or (2) to deny the authorization request. When the end-user chose to deny the authorization request, call Authlete's /api/auth/authorization/fail API with reason=DENIED and use the response from the API to generate a response to the client application.

When the end-user chose to grant authorization to the client application, the authorization server implementation has to issue an authorization code, an ID token, and/or an access token to the client application (response_type=none is a special case where nothing is issued). Issuing the tokens can be performed by calling Authlete's /api/auth/authorization/issue API. Read [ISSUE] written above in the description for the case of action=NO_INTERACTION.