This document describes how to implement your developer authentication callback endpoint.

1. Target Readers

You need to implement your developer authentication callback endpoint (and so have to read this document) only if you want to let (third-party) developers use Developer Console.

Need to Read?As a special behavior, the login form of Developer Console accepts the pair of API key & API secret of the corresponding service as if it were a valid pair of ID & password of a developer. Therefore, if you are the only person who manages client applications for your service, you don’t have to implement a developer authentication callback endpoint. In this case, you don’t have to read this document.Authlete provides Web APIs to manage client applications such as /client/create. Using such Authlete Web APIs, you can build your own tools to manage client applications. If you do it, you don’t have to use Developer Console and so you don’t have to implement a developer authentication callback.

2. What is “Developer Authentication Callback Endpoint”?

Developer authentication callback is a Web API that you are required to implement to authenticate developers. Authlete calls the Web API when developer authentication is needed.

3. Why Is Developer Authentication Callback Endpoint Needed?

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

4. Settings

Authlete needs to know the location of your developer 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 a developer authentication callback endpoint.
Click “Developer Authentication” tab and you will find “Callback” at the top.
Input values for the configuration parameters properly.
Click “Update” button to save the changes.

parameters	description
Developer Authentication Callback Endpoint	The URL of your developer authentication callback endpoint. The location must be accessible from Authlete server. The URL should start `https://` for security.
Developer 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 developer authentication callback endpoint. You can ensure that developer authentication requests have come from Authlete by checking the API credentials.

5. Developer Authentication Callback Request

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

HTTP method

POST method

Content-Type

application/json

Basic Authentication

If you set non-empty values to “Developer Authentication Callback API Key” and “Developer 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 a developer authentication callback request is JSON. The JSON contains the properties listed in the table below (DeveloperAuthenticationCallbackRequest.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 login form of Developer Console, properties you have to care about are just id and password. (Social login for Developer Console is not supported yet.)

Property	Description
`serviceApiKey`	The API key of your service.
`id`	When sns property is null, id is the value that the developer input to the “Login ID” field in the login form of Developer Console. Otherwise, when sns property is not null, id is the value of the subject (= unique identifier) of the developer in the SNS.
`password`	When sns property is null, password is the value that the developer input to the “Password” field in the login form of Developer Console. Otherwise, when sns property is not null, password has no meaning.
`sns`	When the developer performed social login at the login page, sns property holds the name of the SNS such as FACEBOOK. sns property is always null unless you enable social login support in “Developer Authentication” tab.
`accessToken`	When the developer performed social login at the login page, accessToken property holds the access token which was issued from the token endpoint of the SNS.
`refreshToken`	When the developer performed social login at the login 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 developer performed social login at the login 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 developer performed social login at the login 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. Developer Authentication Callback Response

A developer 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 a developer authentication callback response must be JSON. The properties expected to be contained in the JSON are listed in the table below (DeveloperAuthenticationCallbackResponse.java in authlete-java-common is always the latest format).

Property	Description
`authenticated`	The result of authentication. Set `true` when the developer was authenticated successfully.
`subject`	The unique identifier of the developer 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 a developer by an email address, your service may look up a developer 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 developers). When `authenticated` property is `false`, `subject` property may be null.
`displayName`	The display name of the developer. May be null. Its length must not exceed 100.

7. Sample Implementation

TBW

Terraform

Self-Managed Deployment

Observability

Performance

Migration from Existing System

Networking

Integration with API Gateways

Operational Policies

Access Control

Developer Console

Service Owner Console

Developer Authentication Callback

1. Target Readers

2. What is “Developer Authentication Callback Endpoint”?

3. Why Is Developer Authentication Callback Endpoint Needed?

4. Settings

5. Developer Authentication Callback Request

HTTP method

Content-Type

Basic Authentication

Data Format

6. Developer Authentication Callback Response

Content-Type

Recommended HTTP headers

Data Format

7. Sample Implementation

​1. Target Readers

​2. What is “Developer Authentication Callback Endpoint”?

​3. Why Is Developer Authentication Callback Endpoint Needed?

​4. Settings

​5. Developer Authentication Callback Request

​HTTP method

​Content-Type

​Basic Authentication

​Data Format

​6. Developer Authentication Callback Response

​Content-Type

​Recommended HTTP headers

​Data Format

​7. Sample Implementation

1. Target Readers

2. What is “Developer Authentication Callback Endpoint”?

3. Why Is Developer Authentication Callback Endpoint Needed?

4. Settings

5. Developer Authentication Callback Request

HTTP method

Content-Type

Basic Authentication

Data Format

6. Developer Authentication Callback Response

Content-Type

Recommended HTTP headers

Data Format

7. Sample Implementation