Signing keys

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. These signing keys are generated when seeding Logto database (open-source) or creating a new tenant (Cloud) and can be managed through CLI (open-source), Management APIs or Console UI.

By default, Logto uses the elliptic curve (EC) algorithm to generate digital signatures. However, considering that users often need to verify JWT signatures and many older tools do not support the EC algorithm (only supporting RSA), we have implemented the functionality to rotate private keys and allow users to choose the signature algorithm (including both RSA and EC). This ensures compatibility with services that use outdated signature verification tools.

note:

Theoretically, signing keys should not be leaked and do not have an expiration time, meaning there's no need to rotate them. However, periodically rotating the signing key after a certain period can enhance security.

How it works?

• OIDC private key When initializing a Logto instance, a pair of public key and private key are automatically generated and are registered in the underlying OIDC provider. Thereby, when Logto issues a new JWT (access token or ID token), the token is signed with the private key. In the meantime, any client application that receives a JWT can use the paired public key to verify the token signature, in order to ensure the token is not tampered by any third-party. The private key is protected on the Logto server. The public key, however, as the name suggests, are public to everyone, and can be accessed through the /oidc/jwks interface of the OIDC endpoint. A signing key algorithm can be specified when generating the private key, and Logto uses EC (Elliptic Curve) algorithm by default. The admin users can change the default algorithm to RSA (Rivest-Shamir-Adleman) by rotating the private keys.
• OIDC cookie key When user initiate a sign-in or sign-up flow, an "OIDC session" will be created on the server, as well as a set of browser cookies. With these cookies, browser can request Logto Experience API to perform a series of interactions on behalf of the user, such as sign-in, sign-up, and reset password. However, unlike the JWTs, the cookies are only signed and verified by Logto OIDC service itself, asymmetric cryptography measures are not required. Thus we don't have paired public keys for cookie signing keys, nor asymmetric encryption algorithms.

Rotate signing keys from Console UI

Logto introduces a "Signing Keys Rotation" feature, which allows you to create a new OIDC private key and cookie key in your tenant.

1. Navigate to Console > Tenant settings > OIDC configs. From there, you can manage both OIDC private keys and OIDC cookie keys.

2. To rotate the signing key, click the "Rotate private keys" or "Rotate cookie keys" button. When rotating private keys, you have the option to change the signing algorithm.

3. And you'll find a table that lists all the signing keys in use. For OIDC private keys, you can delete the previous key, but you cannot delete the current or next key. For OIDC cookie keys, you can delete the previous key, but you cannot delete the current key.

   Status	Description
   Next	This status is used for staged OIDC private key rotation. The key has been created, but Logto will not use it to sign new JWTs until the grace period ends and the key becomes effective.
   Current	This indicates that this key is currently used by Logto to sign newly issued JWTs or cookies.
   Previous	It refers to a key that was previously used but has been rotated out. Existing JWTs or cookies signed with this key remain valid until they expire or the key is deleted.

Please remember that rotation involves the following three actions:

1. Creating a new signing key: For OIDC private keys, Logto can stage the new key as "Next" first so your applications and APIs have time to refresh the public key from the /oidc/jwks endpoint before the new key is used for signing.
2. Rotating the current key: When the rotation becomes effective, the "Next" key becomes "Current", and the existing "Current" key becomes "Previous". Tokens signed with the previous key will still remain valid.
3. Removing the oldest previous key: Logto keeps at most one "Previous" private key. If a previous private key already exists when the staged key becomes current, the older previous key will be removed.

For Logto Cloud, OIDC private key rotation takes effect after a 4-hour grace period. During this period, the new key is prepared and exposed through JWKS before Logto starts signing newly issued JWTs with it. In the Console table, the Effective at column shows when a staged "Next" key will become "Current".

For self-hosted OSS deployments, the default private key rotation grace period is 0 seconds, which means the rotation is immediate. To use staged rotation, set the PRIVATE_KEY_ROTATION_GRACE_PERIOD environment variable on the Logto service, or pass an explicit rotationGracePeriod value in the request body when calling the Management API endpoint POST /api/configs/oidc/private-keys/rotate.

warning:

Avoid rotating signing keys repeatedly before the pending rotation becomes effective unless you intentionally want to replace the staged "Next" key.

Deleting the only "Previous" key too early may invalidate existing JWTs or cookies that were signed with that key.

Related resources

Introduction to EC and RSA signing algorithms in JWT