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:- You intend to use Authlete’s default authorization endpoint (
/auth/authorization/direct/service-api-key) implementation and you want your end users to provide their ID and password at the Authlete authorization page. - You intend to use Authlete’s default token endpoint (
/auth/token/direct/service-api-key) implementation and you want to support Resource Owner Password Credentials Grant to authenticate your end users via their ID and password.
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 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 (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 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 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:- Login to the Service Owner Console. You will see a list of your services.
- Click the Edit button of the relevant service.
- Click the User Authentication tab.
- Enter the Authentication Callback parameters described below.
- Click the Update button to save the changes.
| 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, requests from Authlete containAuthorization 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 in 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 aboutid 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 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” 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 in OpenID Connect Core 1.0. 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. 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 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 specify claim locales you want to support in the “Supported Claim Locales” field in the “ID Token” tab in the Service Owner Console. 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 (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 in authlete-java-common corresponds to the current list of properties). If you do not plan to support OpenID Connect, you can set theclaims 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, its value must follow the format defined in the Claims section of OpenID Connect Core 1.0. |
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. |