Client Secret Rotation

On this page

Confidential OAuth clients authenticate to FusionAuth with a client secret during grants such as the authorization code grantAn OAuth 2.0 grant type in which a client exchanges an authorization code for tokens. and the client credentials grantAn OAuth 2.0 grant type in which a client uses its own credentials to obtain an access token for itself.. FusionAuth can also sign an id_token with the client secret. To rotate a client secret, generate a new secret, then update FusionAuth and every client that uses the secret.

For the other kinds of secrets, see Key Rotation.

Plan for a Single Secret#

An Application or Entity has one client secret at a time. FusionAuth rejects the old secret as soon as you save the new secret, so clients fail until they switch. For a feature request to support a grace period for client secrets, see issue 1361.

To avoid failed requests during the switch, build each client to accept several secrets and try each secret in turn. Alternatively, rotate during a maintenance window.

Rotate a Client Secret#

Suppose an Application uses client secret A. To rotate client secret A:

  1. Generate a new random string, B. Make B long and high entropy, because FusionAuth can sign an id_token with the client secret. For more information, see the OIDC specification.
  2. Store B in your secrets manager, and record when you put B into service.
  3. Give B to every web application, mobile application, and script that uses client secret A. A client that accepts several secrets keeps A until FusionAuth switches.
  4. Set the client secret of the Application to B. With the Applications API, send a PATCH or PUT request that updates application.oauthConfiguration.clientSecret. For an Entity, use the Entities API or Entity Management -> Entities in the Admin UI.
  5. Remove A from every client.

Confirm the Rotation#

Complete a login or a client credentials grant with client secret B, and confirm that FusionAuth returns tokens. Then confirm that the same request with client secret A fails.