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 method is allowed by the authorization server.
-
The client is configured to use given client secret based method as the token authentication method.
Enable Apps To Authenticate with Client Secret
Cloudentity comes with multi-tenant authorization server as a service.
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.
Read More
To learn more about TLS, see the mTLS-based client authentication documentation.