Table of Contents
This document describes how to implement your developer authentication callback endpoint.
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.
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.
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.
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.
| 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. |
A request from Authlete to a developer authentication callback endpoint follows the specification described below.
POST method
application/json
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.
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). |
A developer authentication callback endpoint is required to return a response that complies with the requirements described below.
application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
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. |
TBW