Client Secrets
OAuth client applications receive a pair of client credentials, comprising a unique client identifier and a robust client secret. Clients capable of securely storing these secrets can leverage them to authenticate with the SecureAuth authorization server reliably. Ensure that your secrets are safeguarded with utmost diligence to maintain optimal security!
Client Secrets Overview
Client secrets are a crucial part of the client application credentials. It is a secret known only to SecureAuth and the client application. They are used, for example, along with the client identifier, to provide client credentials to authenticate the application to SecureAuth in order to get an access token.
To illustrate what client secrets are and why they are used, lets look at the following example. A client application is registered in the SecureAuth platform. It has its credentials defined. The application wants to access the APIs of another web application in a machine-to-machine environment. The application is configured to use the client credentials OAuth grant flow. To get a token, the client application presents its credentials - a client identifier and a client secret. SecureAuth verifies if the credentials from the request match the credentials of the registered client application to prevent the situation that an unauthorized malicious application would get an access token by, for example, impersonating other client application.
Security Considerations
It is crucial for client secrets to store and manage them secure enough to prevent unauthorized access to APIs, because they are used to get access tokens that allow applications to access APIs. Client secrets must be sufficiently random so they cannot be guessed. They should not be stored in distributed native applications and single-page JavaScript applications (as they can be decompiled and the client secret may become exposed).
Since client secrets may become exposed, it's a good practice to keep them short-lived. To enhance security, you can rotate client secrets and store them as a one-way hash for safer storage.
Client Secret Rotation
When you rotate a secret, a new secret is created for your application and the previous one is added to the list of rotated client secrets. Such a list can store only one rotated client secret (by default). If the list already contains a client secret when you rotate secrets, the previous rotated client secret is revoked and the new rotated client secret is added.
Note
For on-premise deployments, it is possible to configure how many rotated client secrets are stored. To change it, provide the number of your choice as the value for the max_number_of_client_rotated_secrets limit in your SecureAuth platform configuration file (config/config.yaml).
Rotated client secrets are still active and valid. If you wish, you can revoke them. Revoking a secret means that it is not possible to use them anymore. The developer must update the client secret in the application before the application can access the APIs. You can revoke all rotated secrets either in the Viev previously used secrets modal in your application settings or by using the SecureAuth revoke client secrets Admin API.
One-way Hash Secrets
One-way hashing of client secrets provides additional security when it comes to storage of the secrets. Hashing a secret hides the plaintext OAuth credential value and makes it impossible to be read both in the interface and the database.
 |
Client secrets are hashed using the SHA256 algorithm. There are only two situations when the client secret can be read:
During the creation of a client (either in the UI or in the request response if using API)
When you rotate a secret (either in the UI or in the request response if using API)
Tip
If you are using UI, for both cases you are reminded to either copy or download your client secret, as you won't be able to view it again.
One-way hashing is currently available only for the customers who deploy their SecureAuth platform on premise. To enable one-way hashing of client secrets, you need to set the client_secrets_stored_as_one_way_hash feature flag to true in your configuration settings.
On-way Hashing Impact on Authorizers
Every time you create an authorizer, a corresponding client application is created for your authorizer in your System workspace. For multi-tenant authorizers, it is created within the system tenant's System workspace. For single-tenant authorizers, the client is created within the system workspace for your tenant.
When you are using one-way hashing for secrets:
It is not possible to display a plaintext secret for your authorizer's client application
The logic responsible for generating the configuration for your authorizer is not able to fetch the secret, as it is hashed. For example, if you are using Istio Authorizer, your configuration file would look like the following:
resources: - manifest.yaml secretGenerator: - name: istio-authorizer-secrets namespace: acp-system literals: - CLIENT_ID=c5fk2d1ngvl012k9noog - CLIENT_SECRET=
To be able to configure your authorizers and enable them to enforce access control, you must rotate the client secret for your authorizer's client application. Then, copy/download the secret and use it in your authorizer's configuration.