Purpose

This article explains OAuth client authentication methods with client secret.

Overview

A client secret is a secret known only to the OAuth application and the authorization server (in this case, Cloudentity). It is generated by Cloudentity during the process of application registration.

Cloudentity supports using client secrets as one of the methods for client authentication. A client has to provide its client secret to authorize itself and to be able to get a token. The client secret serves as a mean of confirming the client’s authenticity.

Authentication using client_secret_basic Method

client_secret_basic is the simplest method of client authentication using client secrets. It is a method where an application uses the HTTP Basic Authentication Scheme to authenticate with Cloudentity.

More detailed process description, without an actual authentication method used can be found in the Cloudentity client authentication documentation.

Prerequisites

• The client is registered with the client_secret_basic method as the token authentication method.

Process of Authentication with client_secret_basic

1. The client makes a request for an access token to the token endpoint.

   Example

   curl -X POST https://{tid}.authz.cloudentity.io/{tid}/{aid}/oauth2/token \
   --header 'Authorization: BASIC YzNyc3BkNzZmZGNtczNiMjhtdGc6UjctX1ZOVEZQaU92WWxCbHFBVjdpUXhFLXVTQzBfWjFqWE1fZS0tOEZZZw==' \
   --header "Content-Type: application/x-www-form-urlencoded" \
   --data-raw "grant_type=authorization_code&code=Xs01spaDxxx"
   

   Tip

   The {tid} parameter is for your tenant identifier. You can find it right at the beginning of your Cloudentity URL.

   The {aid} parameter is for your authorization server (workspace) identifier.

   Note

   For the client_secret_basic method, the Authorization header should be in the following format: Authorization: Basic encodedString, where the encodedString is a result of Base64 encoding of OAuth client’s clientID:clientSecret.

   Remember to include the OAuth grant flow type as the value of the grant_type parameter and to provide all required parameters for the flow of your choice. The example above uses the authorization code grant flow.

2. Cloudentity generates an access token and provides it to the client after a successful request validation.

Result

The client is authenticated using the client_secret_basic method.

Authentication with the client_secret_post Method

Another client authentication flow that uses client secrets is the client_secret_post method. Instead of providing client secret in the header, as in the previous process, the client authorizes itself providing the secret in the HTTP request body as a form parameter.

Prerequisites

• The client was registered with the client_secret_post method as the token authentication method.

Process of Authentication with client_secret_post

1. The client makes a request for an access token to the token endpoint.

   Example

   curl --request
   -F "grant_type=authorization_code"
   -F "code=Xs01spaDxxx"
   -F "client_id=YzEzMGdoMHJnOHBiOG1ibDhyNTA="
   -F "client_secret=dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
   -F "scope=introspect_tokens, revoke_tokens"
   POST \
   --url https://localhost:8443/{tid}/{aid}/oauth2/token \
   --header 'accept: application/x-www-form-urlencoded'
   

2. Cloudentity generates an access token and provides it to the client after a successful request validation.

Result

The client is authenticated using the client_secret_post method.

Authentication with the client_secret_jwt Method

client_secret_jwt is an authentication method that utilizes JSON Web Tokens.

In the client_secret_jwt method, instead of sending the client_secret directly, the client sends a symmetrical signed JWT using its client_secret to create the signature. In the client_secret_jwt method the token is signed using the client’s secret (with the HMAC algorithm).

Compared to client_secret_basic and client_secret_post, client_secret_jwt doesn’t require sending the actual secret over the network. This makes it more secure. If someone reads the request, it is impossible to just copy the secret and use it for another request.

Prerequisites

• The client is registered with the client_secret_jwt method as the token authentication method.

Process of Authentication with client_secret_jwt

1. The client creates a JWT.

   Prepared JSON Web Token is signed using the clien_secret symmetric key.

2. The client makes a request for an access token to the ‘token’ endpoint.

   Example

   Extra line breaks are added for display purposes.

   curl --request
   -F "grant_type=authorization_code"
   -F "client_id=YzEzMGdoMHJnOHBiOG1ibDhyNTA="
   -F "scope=introspect_tokens, revoke_tokens"
   -F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
   -F "client_assertion= eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
   eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
   U5FI6wQvbgUjuWvP6Ba_0KMMEa46Oni_xZaHgZfTAE8"
   POST \
   --url https://localhost:8443/{tid}/{aid}/oauth2/token \
   --header 'accept: application/x-www-form-urlencoded'
   

Result

The client is authenticated using the client_secret_jwt method.

When To Use Client Secret Authentication

Client secret methods are the most commonly used authentication mechanisms for regular server OAuth applications, daemons, machine-to-machine or regular web applications. In other words, client secret methods can be used by confidential applications. An application is confidential when it is able to store its client secret securely.

On the other hand, client secrets must not be used for public applications, like desktop or mobile apps, which are not able to store their client secrets securely. Users of such applications have direct access to the code of the app, therefore, it can be decompiled. This may lead to a situation that your client secret is compromised and not safe anymore. Such applications should use authentication set to None and elevate the use of Proof Key for Code Exchange (PKCE).

Client Secret Best Practices

Being aware of client secrets flaws gives you an opportunity to protect your secret from being compromised.

1. Do not store unencrypted client secrets in Git repositories. Git repositories should not be treated as safe vaults, where you can store your client secret. You can add files to the .gitignore file to prevent committing a file with a client secret by accident. You can use automatic repository scanning tools that detect any cases of your client secret being exposed.

2. Do not share your client secrets over messaging applications. Even if your messaging app is safe for communication, it is not designed to safely store your secrets.

3. Do not store your secrets in client-facing files. HTML and JavaScript files are easy to access. They should never be used to store your clients secrets.

4. Use Transport Layer Security (TLS) Mechanism. Use TLS as an additional security mechanism to send requests to an endpoint.

Read More

To learn more about TLS, see the mTLS-based client authentication documentation.