ACP client authentication overview

The purpose of this topic is to provide an overview of the OAuth client authentication process. It also lists client authentication methods supported by Authorization Control Plane.

Roles

There are two roles inside the client authentication flow:

  • Client is an application that requests access to protected resources from a resource server. It may be a third-party application, but it also can be an application being a part of the organization that owns the resources. In this case, this is an application that tries to authenticate.

  • Authorization server, in this case, Authorization Control Plane, is a server that authenticates the client trying to get access to the protected resources and issues access tokens.

Client authentication process description

Client authentication is a process allowing an authorization server (in this case, ACP) identify a client and either grant them a token (which can be used to access the resource server), or prevent from getting a token.

Below, you can find a diagram that illustrates when the client authentication process takes place, how does it work, what happens before, and what happens next after the client is authenticated.

Read more

To know more about OAuth flows, see the OAuth documentation.

Authentication Flow Process

Prerequisites

  1. The client is registered with a client authentication method of your choice in ACP.

Process

  1. The client sends a request to the token endpoint.

    Request example

    The example below provides a request example for client authentication using the client_secret_basic method and authorization_code OAuth grant flow.

    POST {tid}{aid/oauth2/token} HTTP/1.1
    User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
    Content-Type: application/json
    Authorization: Basic dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw==
    {
       "grant_type" : "authorization_code"
       "code" : "xxxxxxxxxxx"
    }
    
  2. ACP validates the request.

    • It checks for all required parameters, and if the grant type value is valid and has not expired.

    • ACP checks if the grant provided in the request is issued for the identified client.

    • ACP verifies if the redirect URI parameter matches the redirect URI that was used to request the grant.

  3. ACP generates an access token/ID token or both and provides them to the client.

    Response Example

    HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache
    
    {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"example",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "scope":"openid profile"
    }
    

    Result

    The client is authenticated. The application is now able to request data from the resource server (your API).

Supported client authentication methods

Authorization Control Plane supports the following authentication methods:

  • Client secret based authentication:

    • client_secret_basic

    • client_secret_post

    • client_secret_jwt

  • JSON Web Token based authentication:

    • private_key_jwt
  • Mutual Transport Layer Security (mTLS) based authentication:

    • tls_client_auth

    • self_signed_tls_client_auth

  • none authentication that elevates the use of Proof Key for Code Exchange (PKCE).

Note

The client MUST NOT use more than one authentication method in each request.

Enabling client authentication methods in ACP

To learn how to set up client authentication methods, see Enabling token endpoint authentication methods for your workspace documentation.