1.69.0 Key Configuration Migration Guide

FusionAuth 1.69.0 tightens the restrictions around when keys are allowed to be used to verify JWTs and SAML payloads. Generally, if you don't rotate signing keys often or at all, then you are unlikely to be affected. You must update your configuration before upgrading to 1.69.0 if your instance meets any of the following criteria:

• you have recently rotated JWT signing keys according to the key rotation documentation
• you use an external SAML or JWT Identity Provider (IdP) that rotates signing keys
• you use FusionAuth as a SAML IdP with required signing of authentication or logout requests and have rotated keys recently

For each criteria that your FusionAuth instance meets, complete the corresponding fix in the sections below.

Required Key Configuration Updates#

Rotated JWT Signing Keys#

Before the Upgrade#

Before upgrading to 1.69.0, find all old keys that are present and still must be trusted for JWT signing. You can find these keys in Key Master (Settings -> Key Master ) or using the API. Look for keys that meet the following criteria:

• previously configured as the Access token signing key or Id token signing key on the tenant or application
• rotated out in favor of a new key
• used with an access token TTL larger than the time since the rotation: that is, some JWTs signed by that key could still be valid (e.g. a key rotated 5 days ago used with an access token TTL of 7)

Create a mapping of keys to Tenants and Applications, noting whether each token is used for access or Id tokens:

Once you finish mapping your keys, you're ready to update to 1.69.0.

After the Upgrade#

For each key mapping you recorded in the previous step, add the key in the Tenant or Application settings:

1. In the Admin UI, visit Tenants or Applications .
2. For the corresponding Tenant or Application, select Edit from the action menu.
3. Select the JWT tab.
4. Add the key to the Access token signing keys or Id token signing keys lists as appropriate.

Alternatively, use the API to update a Tenant or update an Application.

External SAML IdPs#

If the IDP has not recently rotated its keys, you can safely upgrade to 1.69.0 without completing 'Before the Upgrade' or 'After the Upgrade' steps in this section of the guide. Consult the specific IDP in use or the key rotation processes your organization uses to determine if and how the IDP rotates its keys. Regardless, after upgrading, you must update your key rotation processes to trust both keys during changeover. Change your key rotation processes to use the following new fields:

• identityProvider.keyId -> identityProvider.verificationKeyIds

Before the Upgrade#

Before upgrading to 1.69.0, find all keys that must be trusted for signing requests from external SAML Identity Providers (IdPs). You can find these keys in Key Master (Settings -> Key Master ) or using the API.

Create a mapping of keys to IdP:

After the upgrade#

For each key mapping you recorded in the previous step, add the key in the IdP settings:

1. In the Admin UI, visit Settings -> Identity Providers .
2. For each IdP, select Edit from the action menu.
3. Add the key to the Verification keys list.

Alternatively, use the IdP API.

External JWT IdPs#

Before the Upgrade#

FusionAuth 1.69.0 requires a Default verification key to be configured on the JWT tab to indicate which External IDP JWTs should be considered trusted.

To prevent downtime, set a value for this now by:

1. In the Admin UI, visit Settings -> Identity Providers .
2. For each IdP, select Edit from the action menu.
3. Select the JWT tab.
4. Configure a Default verification key that matches the key the IDP uses to sign JWTs.

After the upgrade#

If your External JWT IDP rotates its keys, you must update your key rotation processes to trust both keys during changeover. Change your key rotation processes to use the following new fields:

• identityProvider.defaultKeyId -> identityProvider.verificationKeyIds

FusionAuth as a SAML IdP#

Pre-upgrade or immediate post-upgrade changes are only necessary if both of these are true:

1. Your FusionAuth application's SAML configuration requires signing of authentication or logout requests.
2. The SAML Service Provider (SP) that creates Authentication Requests for your FusionAuth Application has recently rotated keys. Consult the specific SP in use or the key rotation processes your organization uses to determine if that is the case.

If neither of these are true, you can safely upgrade to 1.69.0 without completing 'Before the Upgrade' or 'After the Upgrade' steps in this section of the guide. However, after upgrading, you must update your key rotation processes to trust both keys during changeover. Change your key rotation processes to use the following new fields:

• application.samlv2Configuration.defaultVerificationKeyId -> application.samlv2Configuration.verificationKeyIds

Before the Upgrade#

If you have recently rotated keys, before upgrading to 1.69.0, find all keys that must be trusted for signing requests from the SAML Service Provider (SP) that creates Authentication Requests for your FusionAuth Application. You can find these keys in Key Master (Settings -> Key Master ) or using the API.

Create a mapping of keys to IdP:

After the upgrade#

If you do rotate keys, ensure that during changeover, both keys are trusted. In 1.69.0, use application.samlv2Configuration.verificationKeyIds (in the Admin UI, Verification key ids) instead of application.samlv2Configuration.defaultVerificationKeyId.

For more information, see the key rotation documentation.