> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> ### Authlete versions
> Authlete 3.0 is the current version. Unless the user says they use another version, answer for Authlete 3.0 using the 3.x documentation.
> Documentation for Authlete 2.x (pages under `/v2/` and `/ja/v2/`) is for the legacy version. Refer to it only when the user is on Authlete 2.x.
>
> ### Authlete architecture
> Authlete is a backend engine for OAuth 2.0 and OpenID Connect processing. End users and client applications do not call it directly; the service provider's authorization server and API server call Authlete's APIs. Authlete handles protocol processing and token, client, and service management, while the service provider owns the OAuth/OIDC endpoints and user authentication.
> See [Architecture](https://developers.authlete.com/get-started/introduction-to-authlete/architecture.md).
>
> ### Concepts
> If the user is new to Authlete, read these pages first:
> - [Request and Response](https://developers.authlete.com/get-started/concepts/request-and-response.md): Core API requests pass the client's request parameters as-is, and responses return `resultCode`, `action`, and `responseContent`.
> - [Action Handling](https://developers.authlete.com/get-started/concepts/action-handling.md): Branch on `action`, never on `resultCode`, and map each action to the HTTP response your server returns.
> - [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md): Actions such as `INTERACTION` are completed with a second call (`/auth/authorization/issue` or `/auth/authorization/fail`) linked by a `ticket`.
> - [Management API Overview](https://developers.authlete.com/get-started/concepts/overview.md): The Management API configures services, manages clients, and operates issued tokens, separately from the protocol flows handled by the Core API.
> - [API Authentication](https://developers.authlete.com/get-started/concepts/authentication.md): Authlete APIs use bearer tokens: a Service Access Token (one service) or an Organization Token (the whole organization).

# Authentication Callback Endpoint

> Learn how to implement your authentication callback endpoint using Authlete's default authorization and token endpoint implementations.

If you intend to have end users authenticate via Authlete's default user interface, you must provide an **authentication callback endpoint** so that Authlete can validate the end user's credentials. Use this document to learn whether you need to implement an authentication callback endpoint, and how to do so if you do.

# 1. Deciding Whether to Implement an Authentication Callback Endpoint

You need to implement an authentication callback endpoint only if one or more of the following conditions are true:

1. You intend to use Authlete's default [authorization endpoint](https://tools.ietf.org/html/rfc6749#section-3.1) (`/auth/authorization/direct/service-api-key`) implementation and you want your end users to provide their ID and password at the Authlete authorization page.
2. You intend to use Authlete's default [token endpoint](https://tools.ietf.org/html/rfc6749#section-3.2) (`/auth/token/direct/service-api-key`) implementation and you want to support [Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) to authenticate your end users via their ID and password.

In both of these cases, Authlete needs to be able to validate the user's ID and password.

> [!NOTE]
>
> **When is an authentication callback not required?**
>
> You don't need to implement an authentication callback endpoint if your service authenticates end users itself and uses its Authlete API credentials to authenticate to Authlete and assert the end user's identity.
>
> For example, if you are using the [Authlete Web APIs](https://docs.authlete.com) such as `/auth/authorization` and `/auth/authorization/issue`, then end-user authentication is completely under your control and there is no need to provide an authentication callback endpoint.
>
> Likewise, if you intend to support the OAuth 2.0 [Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) (where the client obtains the end user's ID and password and supplies it to the authorization server), you can manage end-user authentication and implement your own token endpoint using [Authlete Web APIs](https://docs.authlete.com) such as `/auth/token` and `/auth/token/issue`.
>
> Finally, for the purpose of demonstrating the authorization flow, the default implementations accept a service's Authlete API key & secret of the corresponding service as if it were the ID & password of an end-user. This is how you obtained an access token using your service's API key and secret in the authorization page of the [Getting Started](https://developers.authlete.com/get-started/quickstarts/getting-started.md) experience. There is no need for an authentication callback endpoint, since Authlete can validate the service credentials directly.

# 2. What is an Authentication Callback Endpoint?

Authentication callback is a Web API that validates an end-user's credentials. Authlete calls the Web API when it needs to authenticate an end-user via their ID and password.

# 3. Why Is an Authentication Callback Endpoint Needed?

By design, Authlete does not manage end-user accounts and credentials, and cannot perform end-user authentication. Therefore, Authlete delegates end-user authentication to your authentication callback endpoint. As mentioned above, if your service itself authenticates users and provides their ID via the Authlete Web APIs, you do not need an authentication callback endpoint.

# 4. Settings

You must provide the location of your authentication callback endpoint in the Authlete [Service Owner Console](https://so.authlete.com/):

1. Login to the [Service Owner Console](https://so.authlete.com/). You will see a list of your services.
2. Click the **Edit** button of the relevant service.
3. Click the **User Authentication** tab.
4. Enter the Authentication Callback parameters described below.
5. Click the **Update** button to save the changes.

Authentication Callback parameters:

| parameters | description |
| - | - |
| Authentication Callback Endpoint | The URL of your authentication callback endpoint. The location must be accessible from the Authlete server. The URL should start with `https://` for security. |
| Authentication Callback API Key & Secret | If these values are not empty, Authlete uses the values to add an 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](https://so.authlete.com/), requests from Authlete contain `Authorization` header for Basic Authentication.

## Data Format

The authentication callback request body is in JSON format, and contains the properties listed in the table below ([AuthenticationCallbackRequest.java](https://github.com/authlete/authlete-java-common/blob/master/src/main/java/com/authlete/common/dto/AuthenticationCallbackRequest.java) in [authlete-java-common](https://github.com/authlete/authlete-java-common) corresponds to the current list of properties).

There are probably many more properties than you might expect. However, unless you plan to support social login at the authorization page, or OpenID Connect, you only need to care about `id` and `password`.

| property | description |
| - | - |
| `serviceApiKey` | The API key of your service. |
| `clientId` | The ID of the client application which triggered the authentication callback request. |
| `id` | When the `sns` property is null, `id` is (1) the value that the end-user supplied in the "Login ID" field in the authorization UI displayed at the authorization endpoint, or (2) the value of the `username` request parameter sent to the token endpoint. See [RFC 6749, 4.3. Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) for details of the `username` request parameter.  Otherwise, when the `sns` property is not null, `id` is the value of the subject (unique identifier of the end-user) in the SNS. |
| `password` | When the `sns` property is null, `password` is (1) the value that the end-user supplied in the "Password" field in the authorization UI displayed at the authorization endpoint, or (2) the value of the `password` request parameter to the token endpoint. See "[RFC 6749, 4.3. Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3)" for details of the `password` request parameter.  Otherwise, when the `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. A 'claim' is a piece of information about an end-user. Standard claim names are defined in [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html).  You can specify the claim names you wish to support in the "Supported Claims" field in the "ID Token" tab in the [Service Owner Console](https://so.authlete.com/).  Claims that are not listed in "Supported Claims" will never appear in the claims property.  Note that claim names in the authentication callback request may be followed by a locale tag, for example: `given_name#ja`. See [Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html). |
| `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](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)" in "[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)" for details about `claims_locales`.  You can specify claim locales you want to support in the "Supported Claim Locales" field in the "ID Token" tab in the [Service Owner Console](https://so.authlete.com/). Claims that are not listed in "Supported Claim Locales" will never appear in the `claimsLocales` property. |
| `sns` | When the end-user performed social login at the authorization page, the `sns` property holds the name of the social networking service (SNS); for example: `FACEBOOK`.  The `sns` property is always null unless you enable social login support in the "User Authentication" tab. |
| `accessToken` | When the end-user performed social login at the authorization page, the `accessToken` property holds the access token issued by the token endpoint of the SNS. |
| `refreshToken` | When the end-user performed social login at the authorization page, the `refreshToken` property holds the refresh token which was issued by 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, the `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, the `rawTokenResponse` property holds the content of the response from the token endpoint of the SNS.  Correct implementations of token endpoints return `application/json`, so, in these cases, the content of `rawTokenResponse` property is formatted in JSON. Note, however, that Facebook's token endpoint returns data in `application/x-www-url-encoded` format, violating [RFC 6749](https://tools.ietf.org/html/rfc6749) (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 body of an authentication callback response must be formatted as JSON. The expected properties are listed in the table below ([AuthenticationCallbackResponse.java](https://github.com/authlete/authlete-java-common/blob/master/src/main/java/com/authlete/common/dto/AuthenticationCallbackResponse.java) in [authlete-java-common](https://github.com/authlete/authlete-java-common) corresponds to the current list of properties).

If you do not plan to support [OpenID Connect](https://openid.net/connect/), you can set the `claims` property to `null`.

| Property | Description | | | |
| - | - | - | - | - |
| | | | `authenticated` | `true` when the end-user was authenticated successfully, `false` otherwise. |
| `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 characters.  Note that the value of the `subject` property in the response does not have to be equal to the value of the `id` property in the request. For example, your service might be able to identify an end-user by an email address, but use a username as the subject. Your service would look up an end-user by an email address when the given `id` is a well-formatted email address. In such a case, the value of the `subject` property in the response would be different from the `id` property in the request. When the `authenticated` property is `false`, the `subject` property may be null. |   | `claims` | A JSON string which contains claims as name-value pairs. The following is an example which contains two pairs. `text<br />{<br />"given_name": "Takahiko",<br />"gender": "male"<br />}<br />`When a claim name is one of the [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims), its value must follow the format defined in the [Claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims) section of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html). |

You are expected to collect values for each claim listed in the `claims` property of the request. However, if values of requested claims are not available in your system (even though you have configured them as "Supported Claims") or if you don't want to provide claim values, the `claims` property in the response may be null.

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

# 7. Sample Implementation

TBW


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.