Skip to main content
For Authlete 2.x documentation, see 2.x version.

​
Preface

This article provides an overview of the fundamental aspects of configuring client authentication in Authlete.

​
How Client Authentication Works in Authlete

Authlete performs client authentication during token requests processing (POST /auth/token) by using both pre-configured information and information obtained at runtime.client-authentication-overview

​
Pre-configured Information

You will configure both an Authlete Service (an API instance acting as a backend of an authorization server) and a client in the service.
  • Authlete service
Specify which client authentication methods are enabled by the authorization server. You can enable multiple methods at the same time.
  • Client
Specify which one of the enabled methods is applicable for the client, registered in the service (i.e. establishing a connection with the authorization server). You may also configure information required for the authentication method (e.g. the client’s public key, subject name of the client’s certificate).

​
Information obtained at runtime

On receiving a token request from a client, an authorization server passes the content of the request to Authlete’s POST /auth/token API that processes it. Authlete parses the content, detects the identity of the client, determines the pre-specified authentication method, and fulfills client authentication. Some client authentication methods require additional information such as a value of Authorization header in HTTP request from the client to the authorization server, the client’s certificate used in mutual TLS connection between the parties. In such cases, the authorization server extracts those information from the HTTP request or the mutual TLS, and sends it to Authlete, along with the content of the token request.

​
Configuration example

This section shows an example to use CLIENT_SECRET_BASIC method to authenticate a client (ID: 1257…) and fulfill a token request.client-authentication-client-secret-basic

​
Service Settings

The following settings are done in the pre-configuration. To enable the CLIENT_SECRET_BASIC method in your service:
  1. Log in to the Authlete Management Console
  2. Click on your Organization name and choose your Service.
  3. Navigate to Service Settings > Endpoints > Token
  4. Under the Supported Client Authentication Methods section, select the CLIENT_SECRET_BASIC checkbox.
  5. Click Save Changes to apply the updates.
client-authentication_1

​
Client Settings

To enable the CLIENT_SECRET_BASIC method for your client:
  1. Navigate to Client Settings > Endpoints > Token > General
  2. Under the Client Authentication Method section, open the dropdown menu and select CLIENT_SECRET_BASIC
  3. Click Save Changes to apply the updates.
client-authentication_2

​
Client ID and Client Secret in Client Basic Settings

CLIENT_SECRET_BASIC requires only “client ID” and “client secret” to authenticate the client. In Authlete, these values are automatically generated (“1257…” and “gTyu…” respectively in this example). The client administrator sets the auto-generated values to the client. To view your Client ID and Client Secret in the Authlete Management Console:
  1. Log in to the Authlete Management Console
  2. Click on your Organization name and choose your Service.
  3. Navigate to Client Settings > Basic Settings > General

​
Client Request Flow from Start to Finish

Here are flows from a token request by the client to fulfillment by Authlete. Step 1 The client prepares a token request. The request will be sent to the authorization server with information needed for client authentication. In this case, the client sets its client ID (1257…) and secret (gTyu…) to Authorization header of the HTTP request. 
POST /token HTTP/1.1
Authorization: Basic base64(**1257...:gTyu...**)
Host: as.example.com
...
grant_type=authorization_code&
code=...&
redirect_uri=...
Step 2 The authorization server obtains the actual content of the token request (“grant_type=authorization_code&…” in this example) from body part of the HTTP request. The client’s ID and secret are also extracted from the Authorization in the HTTP header part at the same time.
ItemValue
Content of token requestgrant_type=authorization_code&code=...&redirect_uri=...
Client ID1257...
Client secretgTyu...
Step 3 The authorization server makes a request to Authlete’s POST /auth/token API. The request contains the values that have been obtained in the step 2; the content of the token request and the client’s ID and secret, as “parameters”, “clientId”, “clientSecret” respectively. 
POST /api/auth/token HTTP/1.1
Host: api.authlete.com
...

{
  "clientId":"1257...",
  "clientSecret":"gTyu...",
  "parameters":
    "grant_type=authorization_code
     &code=...&redirect_uri=..."}
Step 4 By using the client’s ID in the API request, Authlete determines the identity of the client that is the source of the token request. Authlete eventually recognizes that CLIENT_SECRET_BASIC is the method to authenticate the client, checks the value of the client’s secret, and decides if the authentication is successful or not.

​
Method Specific Configuration Tips

Both client information to be pre-configured in an Authlete service, and tasks to be done by an authorization server on receiving an token request, are different for each client authentication method. This table describes configuration tips for some of the methods supported by Authlete.
Authentication MethodClient BehaviorAuthlete SettingsAuthorization Server Settings
CLIENT_SECRET_BASICThe client sets its ID and secret in the Authorization header when sending a token request.No additional settings required; Authlete automatically generates and manages the client’s ID and secret.Extracts the client’s ID and secret and include them as parameters in the POST /auth/token
CLIENT_SECRET_POSTThe client includes its ID and secret as parameters in the token request.No additional settings required, similar to CLIENT_SECRET_BASIC.No additional operations needed; the client’s ID and secret are part of the token request content.
CLIENT_SECRET_JWTThe client generates a JWT assertion containing a MAC (message authentication code) calculated using the client’s secret and adds it as a parameter in the token request. For more details, see Client authentication using client_secret_jwt methodSpecify the “assertion signing algorithm” for the JWT assertion in Authlete. Authlete automatically generates and manages the client’s secret.No additional operations needed; the JWT assertion is part of the token request content.
PRIVATE_KEY_JWTThe client generates a digitally signed JWT assertion using public key cryptography and adds it as a parameter in the token request. For more details, see Client authentication using private_key_jwt methodYou have to Specify the “assertion signing algorithm” of the JWT assertion and register the client’s public key in Authlete.The server doesn’t have to do additional operations; the JWT assertion is part of the token request content.
TLS_CLIENT_AUTHThe client establishes a mutual TLS connection and is authenticated using the client’s certificate obtained from the connection. For more details, see Client authentication using tls_client_auth method.You have to specify the “subject name” of the client’s certificate in Authlete.Extracts the client’s certificate from the mutual TLS connection and includes it as a parameter in the POST /auth/token.