Signing Key Rotation
On this page
FusionAuth signs JWTs with keys stored in Key Master. Your applications verify the signature to confirm that FusionAuth issued the token. FusionAuth also signs SAML responses and webhook events with Key Master keys. To rotate a signing key, create a new key, switch your configuration to the new key, and keep the old key for verification until the tokens the old key signed expire.
For API keys, see API Key Rotation. For more information about JWT signing, see Tokens.
Find Keys Due for Rotation#
Since 1.45.0, the Key Search API accepts a wildcard search ordered by expiration. A script can then find every key that expires within a set period.
The following script uses jq and bash to list the keys that expire in the next 30 days. The script is in the FusionAuth example scripts GitHub repository.
#!/bin/bash
API_KEY=...
FA_HOSTNAME=http://localhost:9011
# default to 30 days out. any keys expiring before this will be printed
DAYS_TILL_EXPIRATION=30
# finds current unix timestamp (the %s format works the same on GNU and BSD/macOS date)
curdate=`date +%s`
curdateinmillis=$(($curdate * 1000))
expdatemillis=$(($DAYS_TILL_EXPIRATION * 24 * 60 * 60 * 1000))
targetdateinmillis=$(($curdateinmillis + $expdatemillis))
start=0
increment=25
total=`curl -s -H "Authorization: $API_KEY" $FA_HOSTNAME'/api/key/search?orderBy=expiration%20ASC' | jq '.total'`
keysdata=""
# loop over requests to FusionAuth key search API
while [[ $start -lt $total ]]; do
res=`curl -s -H "Authorization: $API_KEY" $FA_HOSTNAME'/api/key/search?orderBy=expiration%20ASC&startRow='$start'&numberOfResults='$increment | jq -r '.keys[]| select(.expirationInstant != null) |[.expirationInstant,.id]|@csv'`
# for each set of results, loop over them and grab the expiration instant
for row in $res; do
exp=`echo $row|awk -F, '{print $1}'`
if [[ $exp -gt $targetdateinmillis ]]; then
# seen key far enough in the future, bail
exit 0
fi
echo $row
done
# if we get here, there are more rows to pull and keys are still before our DAYS_TILL_EXPIRATION value
start=$(($start + $increment))
done
exitRun the script on a schedule, such as a cron job, then rotate the returned keys.
Before 1.45.0, the Key Search API doesn't exist. Retrieve every key with the Retrieve a Key API, then filter the response on expirationInstant. HMAC keys have no expiration, so track the age of an HMAC key with insertInstant.
Rotate a Signing Key#
Suppose FusionAuth signs JWTs with key JS1. To rotate key JS1:
- Create key
JS2in Key Master. Use the same algorithm and key length as keyJS1. - Switch every Tenant and Application that signs with key
JS1to keyJS2. At the same time, add keyJS1to Access token verification keys, Id token verification keys, or both. Make the change at the Tenant level, or at the Application level when the Application overrides the JWT settings. FusionAuth1.69.0and later support verification keys. - Wait until every token signed by key
JS1expires. The wait depends on the JWT lifetime. For example, with a five-minute JWT lifetime, wait ten minutes to allow for clock skew. - Delete key
JS1.
The steps assume that only FusionAuth uses keys JS1 and JS2. When another system holds the private key, such as an externally managed RSA key, import key JS2 instead of creating key JS2. Then update the other system to use key JS2 before you delete key JS1.
Find Every Use of a Key#
To switch every configuration to the new key, retrieve each object and look for the Id of the old key. Check the following fields:
- JWT configuration
tenant.jwtConfiguration.accessTokenKeyIdtenant.jwtConfiguration.accessTokenVerificationKeyIdstenant.jwtConfiguration.idTokenKeyIdtenant.jwtConfiguration.idTokenVerificationKeyIdsapplication.jwtConfiguration.accessTokenKeyIdapplication.jwtConfiguration.accessTokenVerificationKeyIdsapplication.jwtConfiguration.idTokenKeyIdapplication.jwtConfiguration.idTokenVerificationKeyIds
- Entity TypeA category of Entity that defines the Permissions available to Entities of that type. JWT configuration
entityType.jwtConfiguration.accessTokenKeyId
- External JWT IdP
identityProvider.defaultKeyIdidentityProvider.verificationKeyIds
- Application SAML v2
application.samlv2Configuration.assertionEncryptionConfiguration.keyTransportEncryptionKeyIdapplication.samlv2Configuration.defaultVerificationKeyIdapplication.samlv2Configuration.keyIdapplication.samlv2Configuration.logout.defaultVerificationKeyIdapplication.samlv2Configuration.logout.singleLogout.keyIdapplication.samlv2Configuration.logout.keyIdapplication.samlv2Configuration.logout.verificationKeyIdsapplication.samlv2Configuration.verificationKeyIds
- SAML v2 IdP
identityProvider.keyIdidentityProvider.requestSigningKeyIdidentityProvider.verificationKeyIds
- Webhook signature
webhook.signatureConfiguration.signingKeyId
Confirm the Rotation#
Log in to an Application that used key JS1. Decode the new access token, and confirm that the kid header matches the Kid of key JS2 in Key Master.
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 client secret of a FusionAuth Application or Entity.
This is a reference for all of the current password hashing algorithms support by FusionAuth out of the box.