Definitive Guide

Developer Authentication Callback


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.

Necessary 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 /api/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?

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

  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 a developer authentication callback endpoint.
  3. Click "Developer Authentication" tab and you will find "Callback" at the top like below.
Developer Authentication / Callback

There are three configuration parameters.

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 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.
Developer Authentication Callback API Secret
  1. Input values for the configuration parameters properly.
  2. Click "Update" button to save the changes.

5. Developer Authentication Callback Request

A request from Authlete to a developer 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 "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.

5.4. 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.

6.1. Content-Type

application/json;charset=UTF-8

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

6.3. 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