Configuring client authentication

Table of Contents

Configuring client authentication

Preface

This article describes basics of client authentication configuration in Authlete.

How client authentication works in Authlete

Authlete fulfills client authentication on processing token requests (/auth/token API ) based on both pre-configured information and other 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 /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

The following settings are done in the pre-configuration (Step 0 ).

  • An service administrator logs in to Authlete’s service owner console, chooses the particular service (“Service A” in this example), and enables support of CLIENT_SECRET_BASIC in Supported Client Authentication Methods setting.

    client-authentication_1

  • On the other side, an client administrator logs in to Authlete’s developer console of the service and specifies CLIENT SECRET_BASIC as the client authentication method for the particular client.

    client-authentication_2

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

    client-authentication_3

Here are flows from a token request by the client to fulfillment by Authlete (Step 1~4).

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

Item Value
Content of token request 
grant_type=authorization_code&
code=…&
redirect_uri=…
Client ID 
1257…
Client secret 
gTyu…
  • Step 3

The authorization server makes a request to Authlete’s /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 section describes configuration tips for some of the methods supported by Authlete.

CLIENT_SECRET_BASIC

As introduced in the previous section, a client is to set its ID and secret to Authorization header on sending a token request.

  • Authlete settings

    • You don’t have to configure any additional settings because Authlete automatically generates and manages the client’s ID and secret, which are required for this client authentication method.

  • Authorization server settings

    • The server is expected to extract the client’s ID and secret and set them as specific parameters in a request to /auth/token API .

CLIENT_SECRET_POST

A client is to add its ID and secret to a token request as its parameters.

  • Authlete settings

    • You don’t have to configure any additional settings, as in the case of CLIENT_SECRET_BASIC above.

  • Authorization server settings

    • The server doesn’t have to do any additional operations in terms of the client’s ID and secret because these values are part of the content of the token request.

 CLIENT_SECRET_JWT

A client is to generate a JWT assertion that contains a MAC (message authentication code) calculated using the client’s secret, and add it to a token request as its parameters.

  • Authlete settings

    • While Authlete automatically generates and manages the client’s secret, you have to additionally specify “assertion signing algorithm” of the JWT assertion, as the client’s information in Authlete.

  • Authorization server settings

    • The server doesn’t have to do any additional operations in terms of the JWT assertion because the value is part of the content of the token request.

Read the article “Client authentication using client_secret_jwt method ” for more details.

PRIVATE_KEY_JWT

A client is to generate a digitally signed JWT assertion using public key cryptography, and add it to a token request as its parameters.

  • Authlete settings

    • You have to specify “assertion signing algorithm” of the JWT assertion, as the client’s information in Authlete. The client’s public key also must be registered in advance.

  • Authorization server settings

    • The server doesn’t have to do any additional operations in terms of the JWT assertion because the value is part of the content of the token request.

Read the article “Client authentication using private_key_jwt method ” for more details.

TLS_CLIENT_AUTH

A client is to establish a mutual TLS connection with an authorization server and be authenticated using the client’s certificate obtained from the connection.

  • Authlete settings

    • You have to specify “subject name” of the client’s certificate, as the client’s information in Authlete.

  • Authorization server settings

    • The server has to extract the client’s certificate from the mutual TLS connection and add it as one of request parameters to /auth/token API .

Read the article “Client authentication using tls_client_auth method ” for more details.