Tenant Signing Key Rotation

Knowledge Articles
, , , , , ,
1

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:

Screen Shot 2022-02-03 at 09.19.55
Screen Shot 2022-02-03 at 09.19.551339Ă—496 49.8 KB

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. Auth0 provides the next, last, and current signing keys for your tenant. You can use this information to rotate signing keys without downtime if your SAML SP partners support multiple signing certificates:

  1. Navigate to Dashboard > Settings > Signing Keys. Under List of Valid Keys, note the Key ID of the Next in Queue key
  2. Navigate to:

https://tenant.{us/eu/au}.auth0.com/.well-known/jwks.json, Substituting your tenant name and region as appropriate

  1. In the array of keys, locate the key object with the kid property matching the Key ID you noted in step 1
  2. Copy the x5c property of the key object you located in step 3
  3. The x5t you just copied is an x.509 certificate and contains the key that will be used to sign SAML responses after the tenant signing key is rotated.

From here you you need to get the certificate into an appropriate format to share with your SAML SP partners. PEM format is most common. You can use a tool like this one to convert the x5t from step 5 into a PEM formatted certificate (the tool doesn’t change anything except add the BEGIN/END lines and line breaks). Your partners may require formats other than PEM–conversion to other formats is beyond the scope of this document but relatively easy starting from PEM.

Provide the new certificate to your partners prior to rotating the tenant signing key. They should configure their SAML SP to accept signatures from keys in the current and new certificates (that is, they should not overwrite the current certificate). If they configure their SAML SPs correctly, they will be able to validate SAML responses as soon as you rotate the key. The SP should accept signatures from both keys until all responses signed by the old key have expired (e.g. if your responses have a validity period of one hour, the SP should accept responses signed with either key for 61 minutes). Let your partners know when they should remove the old certificate from their configuration.

If your partner’s SAML SP does not support multiple signing certificates, the general procedure is:

  1. Provide the certificate to your partner prior to rotation
  2. Schedule the rotation with your partner(s) for a specific time. Instruct them to update the signing certificate at that time. This may result in brief downtime where validation of SAML responses fails.

Supporting Documentation:

Documentation:
Rotate Signing Keys
Revoke Signing Keys
JWKS discovery

1 Like