Skip to main content

Rotate signing keys (OSS)

note:

If you're using Logto Cloud, you can rotate signing keys in the Console UI, please refer to this tutorial.

Logto OSS has supported rotating signing keys since v1.8.

Logto OIDC signing keys, also known as “OIDC private keys” and “OIDC cookie keys”, are the signing keys used to sign JWTs (access tokens and ID tokens) and browser cookies in Logto sign-in sessions.

Rotating your signing keys regularly can reduce the risks of potential key compromise. Logto recommends you to rotate your signing keys at least once a year.

Rotate OIDC private signing keys​

Use the CLI command below to generate a new OIDC private signing key. By default, the new key takes effect immediately. To stage the rotation and give clients time to refresh JWKS before the new key signs JWTs, configure a grace period.

Available options:

--type          (Optional) The signing key algorithm for your JWTs.
                Values are "rsa" or "ec". Defaults to "ec".
--gracePeriod   (Optional) Grace period in seconds for staged private key rotation.
                Defaults to the PRIVATE_KEY_ROTATION_GRACE_PERIOD environment variable, or 0 if unset.
logto db config rotate oidc.privateKeys --type rsa

For example, to stage the new private key for 4 hours before it becomes active:

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

You can also set the default grace period for private key rotation with an environment variable:

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

Set this environment variable on the Logto service when rotating through Admin Console or Management API, or in the shell where you run the CLI command when rotating through CLI.

Use the CLI command below to generate a new OIDC cookie key. Cookie key rotation does not support a grace period.

logto db config rotate oidc.cookieKeys

What about the previous keys?​

For OIDC private keys, Logto keeps up to three keys during staged rotation:

  • Next: The new key waiting for the grace period to end.
  • Current: The key currently used to sign newly issued JWTs.
  • Previous: The most recently rotated-out key, kept so existing JWTs can remain valid.

After the grace period, the Next key becomes Current, the old Current key becomes Previous, and the oldest Previous key is removed.

For cookie keys, Logto keeps the current and previous key. Be cautious when deleting previous keys, as it may cause unexpected issues. It is recommended to keep the previous key until you are confident that all existing sessions or tokens signed with it have expired.

Troubleshooting​

Using Logto as OIDC Provider in Cloudflare Zero Trust​

If you intend to use Logto as an OIDC provider with Cloudflare Zero Trust, please note that it does not support OIDC providers using ECDSA algorithms. When rotating OIDC private signing keys, ensure you use the RSA algorithm by specifying --type rsa in the rotation command:

logto db config rotate oidc.privateKeys --type rsa