OAuth Client Secret Authentication

Authenticate client applications using client secret based OAuth client authentication methods.

What Client Secret Is

A client secret is a secret known only to the OAuth application and the authorization server. It is generated by the authorization server during the process of application registration.

A client has to provide its client secret to authenticate itself to the authorization server and to be able to get a token. The client secret, along the client identifier, serves as a mean of confirming the client's authenticity.

Prerequisites to Client Secret Based Authentication

client_secret_basic

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 the authorization server.

The client makes a request for an access token to the token endpoint.
Example CURL:
```
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"
```
For the client_secret_basic method, the Authorization header must be in the Authorization: Basic encodedString format, 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.
The authorization server generates an access token and provides it to the client after a successful request validation.

client_secret_post

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.

The client makes a request for an access token to the token endpoint and includes the client credentials in the request body parameters.

Example CURL:

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'

The authorization server generates an access token and provides it to the client after a successful request validation.

client_secret_jwt

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.

The client creates a JWT.
Prepared JSON Web Token is signed using the clien_secret symmetric key.

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

Example CURL with 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'

The authorization server generates an access token and provides it to the client after a successful request validation.

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.

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.
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.
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.
Use Transport Layer Security (TLS) Mechanism. Use TLS as an additional security mechanism to send requests to an endpoint.

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

In this section: