Rotating Client Application Secret without Downtime

Knowledge Articles
, ,
1

Last Updated: Sep 24, 2024

Overview

The client secret for a client application needs to be rotated in a way that eliminates downtime for the impacted system.

Applies To

  • Client Application Secret Rotation

Solution

Instead of using the administration dashboard or the Management API endpoint to rotate the client secret, the client secret should be rotated by taking the following approach.

Pre-requisites:

  • The system relies on configuration to maintain either a list of client secrets or at least two separate configuration entries (CURRENT and NEXT) that represent client secrets.
  • By default, the system uses either the first client secret in the list or the CURRENT configuration entry; if an error is received during an exchange that requires client authentication and the error is known to be associated with a problem related to client credentials, the system should be capable of retrying the operation using the next secret in the list or the NEXT configuration entry.
  • If an event occurs that forces the system to attempt to use the next secret in the list or the NEXT configuration entry and the operation succeeds when using the new secret, the system should discard the old secret and update the configuration in a way that the next secret (the one that succeeded) is considered to be the default/current one going forward.

Rotate the secret:

  1. The system associated with the client application record generates a new value for the client secret; this value should have similar entropy to the client secret values generated by the Auth0 service itself.
  2. The system adds the newly generated secret to the system configuration as the next secret in the list or the respective entry if separate configuration entries are used.
  3. The system obtains a Management API access token capable of updating client applications and performs a client application update request where the only property updated is the client_secret and the value is the one that was generated in the first step.

Given the system is prepared to automatically fallback to use the next client secret as available in the system configuration, this process will allow rotating a secret without downtime because by the time the new secret takes effect in the Auth0 service, the system is already aware of that value and can automatically fallback and retry any operation that fails due to the old secret that got rotated.

An alternative to the process above that relies on the system itself providing an option for administrative users to rotate the secret through the system itself would be for a tenant admin to manually perform the three steps in question. In other words, a tenant admin would manually generate a new client secret value, update the system configuration with that value, and perform the client update outside of the system itself.

If there are considerations around how to generate a client secret with the sufficient entropy it is technically possible to use a temporary client application record in Auth0 as the sole means to generate client secrets to be used for rotation. In other words, the process could create a new client application record in Auth0, retrieve the secret from the new application, delete that application, and use that secret value in the context of the application that requires a rotation.