Table of Contents

This document describes how to implement your authentication callback endpoint.

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.

If you use the default implementation of authorization endpoint (/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.
If you use the default implementation of token endpoint (/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.

Need 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 /auth/authorization, /auth/authorization/issue and /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 Authlete Web APIstoken endpoint by yourself using Authlete Web APIs such as /auth/token, /auth/token/issue and /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?

Since Authlete does NOT have any database table to manage end-user accounts, 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.

Login Service Owner Console, and you will see the list of your services.
Click Edit button of a service for which you are going to provide an authentication callback endpoint.
Click “User Authentication” tab and you will find “Callback” at the top like below.
Input values for the configuration parameters properly.
Click “Update” button to save the changes.

There are three configuration parameters.

parameters	description
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 & Secret	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.

5. Authentication Callback Request

HTTP method

POST method

Content-Type

application/json

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.

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. 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 Core 1.0” 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.

Content-Type

application/json; charset=UTF-8

Recommended HTTP headers

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

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