Tenant Signing Key Rotation

Question: What is signing key rotation? How does it work? Will there be downtime?

Answer:

Most of this document applies to JWTs using OIDC flows. There are special considerations for SAML flows. See the end of the document for more information.

Rotating your tenant keys changes the public/private keypair used to sign and verify responses from your tenant.

The normal state for your tenant is to publish the public keys for two keypairs, the current one and the next one. It looks like this in your jwks.json:

{"keys": [
        {
            "alg": "RS256",
            "kty": "RSA",
            "use": "sig",
            "n": "zNZzv6CF85j...F8KwmGRw",
            "e": "AQAB",
            "kid": "PG_mWAHUTqPtBBuyEzCYY",
            "x5t": "hFfzVxGj5YGHbeizzvMGeZv6KZg",
            "x5c": [
                "MIIDBzCCAe+gAw...qSwYZV10="
            ]
        },
        {
            ...
            "n": "s71KiW2D1vz...A8HG3Dw",
            "e": "AQAB",
            "kid": "6kwPY_s1TCwoF-BEjwl-e",
            "x5t": "gcv06ANqvkXFH6m57Qy4PIE8e40",
            "x5c": [
                "MIIDBzCCAe+g...QY9Rf43M="
            ]
        }
    ]
}

You can see your own tenant keys with this URL pattern:

https://tenant.{us/eu/au}.auth0.com/.well-known/jwks.json

Your tenant will only sign tokens using one private key at a time, but a conforming client will try to use any public key in jwks.json to verify the signature.

If you click “Rotate Key” (found in Tenant Settings > Signing Keys) then a third key will be added to jwks.json. Now you have previous, current, and next keys. Your jwks.json looks like this:

{
    "keys": [
        {
            "alg": "RS256",
            "kty": "RSA",
            "use": "sig",
            "n": "s71KiW2D1vzrp9...A8HG3Dw",
            "e": "AQAB",
            "kid": "6kwPY_s1TCwoF-BEjwl-e",
            "x5t": "gcv06ANqvkXFH6m57Qy4PIE8e40",
            "x5c": [
                "MIIDBz...hEfQY9Rf43M="
            ]
        },
        {
            ...
            "n": "zNZzv6CF85jTQ42...s_F8KwmGRw",
            "e": "AQAB",
            "kid": "PG_mWAHUTqPtBBuyEzCYY",
            "x5t": "hFfzVxGj5YGHbeizzvMGeZv6KZg",
            "x5c": [
                "MIIDBzCCAe+gAw...SwYZV10="
            ]
        },
        {
            ...
            "n": "3Ix3hNYj...ow0AvQtQ",
            "e": "AQAB",
            "kid": "kZAnpDlypHH2YMb6d5LOY",
            "x5t": "3qO8coa9mSzWvbW00qBK8pfcvdk",
            "x5c": [
                "MIIDBzCCAe+gAwIBAgIJf...MVVWZXzdzXQ0E="
            ]
        }
    ]
}

The Key IDs (“kid”) correspond to the IDs in your dashboard (found in Tenant settings > Signing Keys). You can manually revoke the previous key in the dashboard as shown below:

A typical scheduled tenant signing key procedure looks like this:

  1. Click “Rotate Key” in the Auth0 dashboard. In the first jwks.json example above, this makes Key ID PG_mWAHUTqPtBBuyEzCYY the previous signing key, and 6kwPY_s1TCwoF-BEjwl-e the current signing key. Since both keys are included in jwks.json (see second example above), a client can verify “old” tokens with the previous key, and “new” tokens with the current key. This step will be transparent to any conforming client.

  2. Most clients cache jwks.json for some period of time. We recommend waiting at least 24 hours, before revoking the previous signing key (see screenshot above). When you do this, the previous key (PG_mWAHUTqPtBBuyEzCYY above) will be removed from jwks.json. All clients should have the new signing key at this point, and this step should be transparent as well. Note if you issue tokens with long expirations you may want to wait until all previously issued tokens have expired as those tokens will become invalid once the previous key is revoked.

  3. If you wanted to rotate keys again for some reason, wait at least 24 hours so any clients can cache the next key.

The red “Rotate & Revoke Key” button will immediately start signing with a new key, and remove the previous key from jwks.json. This will prevent applications from verifying any old tokens using the previous key. Note clients which cache jwks.json will still be able to verify tokens until the cache is refreshed.

Special Considerations for SAML Flows

SAML Connections that sign requests

This applies in the following scenario:

  • You have a SAML connection and have enabled the option to sign SAML requests

Your tenant uses a different key for signing SAML requests. Rotating the tenant signing key will not affect SAML connections that sign requests. The key for signing SAML requests cannot be rotated. The public certificate for verifying signed SAML requests can be downloaded from:

https://tenant.{us/eu/au}.auth0.com/pem?cert=connection

This section does not apply if you have a SAML IdP (“SAML2 Add On” configured). See the following section for this case.

SAML IdPs (“SAML2 Add On” configured)

This applies in the following scenario:

  • You have a SAML IdP (“SAML2 Add On” configured)

Your tenant uses the same keypair for signing JWTs and SAML responses (when Auth0 is the SAML IdP). Rotating the signing key will affect SAML responses. Unfortunately, Auth0 doesn’t have good support for SAML signing key rotation. If you have one of the use cases above, there is additional work and planning for your SAML integrations. This process will involve brief downtime.

  1. Coordinate a time with your partners to rotate the signing key
  2. Immediately after you rotate the signing key, download the new tenant certificate from:

https://tenant.{us/eu/au}.auth0.com/pem

  1. Provide the certificate to your partners with SAML Service Providers.

Supporting Documentation:

Documentation:
Rotate Signing Keys
Revoke Signing Keys
JWKS discovery

1 Like