Definitive Guide

Authentication Callback


1. Target Readers

You need to implement your authentication callback endpoint (and so have to read this document) only if either or both of the following conditions meet.

  1. If you use the default implementation of authorization endpoint (/api/auth/authorization/direct/service-api-key) provided by Authlete, and if you want to authenticate your end-users by their ID and password at the authorization page.
  2. If you use the default implementation of token endpoint (/api/auth/token/direct/service-api-key) provided by Authlete, and if you want to support Resource Owner Password Credentials Grant, and if you want to authenticate your end-users by their ID and password.

Necessary To Read?

Even if you use the default implementations of authorization endpoint and token endpoint, you don't have to implement your authentication callback endpoint if you use only the API credentials of your service for end-user authentication.


As a special behavior, the default implementations accept the pair of API key & API secret of the corresponding service as if it were a valid pair of ID & password of an end-user. This is the reason you could get an access token by inputting the API key & the API secret of your first service into the login form of the authorization page while you went through Getting Started.


If you implement your authorization endpoint by yourself using Authlete Web APIs such as /api/auth/authorization, /api/auth/authorization/issue and /api/auth/authorization/fail, end-user authentication is completely under your management. In this case, you don't have to implement an authentication callback endpoint.


Likewise, even if you want to support Resource Owner Password Credentials Grant (= a flow to request an authorization server to issue an access token by presenting an end-user's ID and password to the server), end-user authentication is completely under your management if you implement your token endpoint by yourself using Authlete Web APIs such as /api/auth/token, /api/auth/token/issue and /api/auth/token/fail. In this case, you don't have to implement an authentication callback endpoint, either.


2. What Is Authentication Callback Endpoint?

Authentication callback is a Web API that you are required to implement to authenticate your end-users. Authlete calls the Web API when end-user authentication is needed.


3. Why Is Authentication Callback Endpoint Needed?

Authlete does NOT have any database table to manage end-user accounts, so Authlete cannot perform end-user authentication. This is by design. Therefore, Authlete delegates end-user authentication to your authentication callback endpoint.


4. Settings

Authlete needs to know the location of your authentication callback endpoint, so it is required to set necessary information via Service Owner Console. Please follow the steps below.

  1. Login Service Owner Console, and you will see the list of your services.
  2. Click Edit button of a service for which you are going to provide an authentication callback endpoint.
  3. Click "User Authentication" tab and you will find "Callback" at the top like below.
User Authentication / Callback

There are three configuration parameters.

Authentication Callback Endpoint The URL of your authentication callback endpoint. The location must be accessible from Authlete server. The URL should start https:// for security.
Authentication Callback API Key If these values are not empty, Authlete uses the values to add Authorization header for Basic Authentication when calling your authentication callback endpoint. You can ensure that authentication requests have come from Authlete by checking the API credentials.
Authentication Callback API Secret
  1. Input values for the configuration parameters properly.
  2. Click "Update" button to save the changes.

5. Authentication Callback Request

A request from Authlete to an authentication callback endpoint follows the specification described below.

5.1. HTTP method

POST method

5.2. Content-Type

application/json

5.3. Basic Authentication

If you set non-empty values to "Authentication Callback API Key" and "Authentication Callback API Secret" of the service using Service Owner Console, requests from Authlete contain Authorization header for Basic Authentication.

5.4. Data Format

The entity body of an authentication callback request is JSON. The JSON contains the properties listed in the table below (AuthenticationCallbackRequest.java in authlete-java-common is always the latest format).

Probably, the number of properties is much larger than you guessed. However, if you don't have a mind to support social login at the authorization page and don't have a mind to support OpenID Connect, properties you have to care about are just id and password.

Property Description
serviceApiKey

The API key of your service.

clientId

The ID of the client application which has triggered the authentication callback request.

id

When sns property is null, id is (1) the value that the end-user input to the "Login ID" field in the authorization UI displayed at the authorization endpoint, or (2) the value of username request parameter to the token endpoint. See "RFC 6749, 4.3. Resource Owner Password Credentials Grant" for username request parameter.

Otherwise, when sns property is not null, id is the value of the subject (= unique identifier) of the end-user in the SNS.

password

When sns property is null, password is (1) the value that the end-user input to the "Password" field in the authorization UI displayed at the authorization endpoint, or (2) the value of password request parameter to the token endpoint. See "RFC 6749, 4.3. Resource Owner Password Credentials Grant" for password request parameter.

Otherwise, when sns property is not null, password has no meaning.

claims

A string array which lists claim names (such as given_name) requested by an authorization request. 'Claim' is a piece of information about an end-user. Standard claim names are defined in "5.1. Standard Claims" in "OpenID Connect Core 1.0".

You can list up claim names you want to support in "Supported Claims" field in "ID Token" tab in Service Owner Console like below.

Supported Claims

Claims that are not listed in "Supported Claims" will never appear in claims property.

Note that claim names in the authentication callback request may be followed by a locale tag like given_name#ja. See "Claims Languages and Scripts" in "OpenID Connect Core 1.0".

claimsLocales

A string array which lists locale names. The values come from claims_locales request parameter contained in the authorization request which has triggered the authentication callback request. See "Claims Languages and Scripts" in "OpenID Connect" for details about claims_locales.

You can list up claim locales you want to support in "Supported Claim Locales" field in "ID Token" tab in Service Owner Console. Claims that are not listed in "Supported Claim Locales" will never appear in claimsLocales property.

sns

When the end-user performed social login at the authorization page, sns property holds the name of the SNS such as FACEBOOK.

sns property is always null unless you enable social login support in "User Authentication" tab.

accessToken

When the end-user performed social login at the authorization page, accessToken property holds the access token which was issued from the token endpoint of the SNS.

refreshToken

When the end-user performed social login at the authorization page, refreshToken property holds the refresh token which was issued from the token endpoint of the SNS. If the SNS has not issued a refresh token, this property is null.

expiresIn

When the end-user performed social login at the authorization page, expiresIn property holds the duration of the access token in seconds. If the SNS has not returned information about the duration, this property is 0.

rawTokenResponse

When the end-user performed social login at the authorization page, rawTokenResponse property holds the content of the response from the token endpoint of the SNS.

Correct implementations of token endpoints return application/json, so the content of rawTokenResponse property is formatted in JSON. However, note that the token endpoint of Facebook returns data in the format of application/x-www-url-encoded. This is a violation against RFC 6749 (OAuth 2.0).


6. Authentication Callback Response

An authentication callback endpoint is required to return a response that complies with the requirements described below.

6.1. Content-Type

application/json;charset=UTF-8

Cache-Control: no-store
Pragma: no-cache

6.3. Data Format

The entity body of an authentication callback response must be JSON. The properties expected to be contained in the JSON are listed in the table below (AuthenticationCallbackResponse.java in authlete-java-common is always the latest format).

If you don't have a mind to support OpenID Connect, you can always set null to claims property.

Property Description
authenticated

The result of authentication. Set true when the end-user was authenticated successfully.

subject

The unique identifier of the end-user in your service. It must consist of only printable ASCII letters and its length must not exceed 100.

Note that the value of subject property in the response does not have to be equal to the value of id property in the request. For example, if your service can identify an end-user by an email address, your service may look up an end-user by an email address when the given id looks like an email address. In such a case, the value of subject property in the response is different from id property in the request (unless your system uses email addresses as subjects of end-users).

When authenticated property is false, subject property may be null.

claims

A JSON string which contains pairs of claim name and claim value. The following is an example which contains two pairs.

{
  "given_name": "Takahiko",
  "gender": "male"
}

When a claim name is one of the standard claims, its value must follow the format defined in "5. Claims" in "OpenID Connect Core 1.0".

claims property in the request is a list of claim names. You are expected to collect values of the claims found in the list. However, if values of requested claims are not available in your system (although you have listed them in "Supported Claims") or if you don't want to provide claim values, claims property in the response may be null.

Claims returned from an authentication callback endpoint are embedded in an ID token which will be returned from the authorization endpoint to the client application that made the authorization request.


7. Sample Implementation

TBW