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 thetoken
authentication method.
Process of Authentication with client_secret_basic
-
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, theAuthorization
header should be in the following format:Authorization: Basic encodedString
, where theencodedString
is a result of Base64 encoding of OAuth client’sclientID: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. -
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 thetoken
authentication method.
Process of Authentication with client_secret_post
-
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'
-
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 thetoken
authentication method.
Process of Authentication with client_secret_jwt
-
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
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.
-
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.
Read More
To learn more about TLS, see the mTLS-based client authentication documentation.