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:
- Generate a new random string,
B. MakeBlong and high entropy, because FusionAuth can sign anid_tokenwith the client secret. For more information, see the OIDC specification. - Store
Bin your secrets manager, and record when you putBinto service. - Give
Bto every web application, mobile application, and script that uses client secretA. A client that accepts several secrets keepsAuntil FusionAuth switches. - Set the client secret of the Application to
B. With the Applications API, send aPATCHorPUTrequest that updatesapplication.oauthConfiguration.clientSecret. For an Entity, use the Entities API or Entity Management -> Entities in the Admin UI. - Remove
Afrom 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.
Related
Learn about the keys and secrets FusionAuth uses, and how rotation differs for each one.
Learn how to rotate FusionAuth API keys without interrupting the scripts and servers that use them.
Learn how to rotate the keys FusionAuth uses to sign JWTs, SAML responses, and webhook events.
Learn how to protect user accounts, credentials, and tokens in applications that use FusionAuth.