Skip to main content

Signing keys

Logto OIDC signing keys, as known as "OIDC private keys" and "OIDC cookie keys", are the signing keys used to sign JWT tokens (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 token (access token or ID token), the token is signed with the private key. In the meantime, any client application that receives a JWT token 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 JWT tokens, 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 > Signing keys. 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. Note: You can delete the previous key, but you cannot delete the current one.

    StatusDescription
    CurrentThis indicates that this key is currently in active use within your applications and APIs.
    PreviousIt refers to a key that was previously used but has been rotated out. Existing tokens with this signing key remain valid.

Please remember that rotation involves the following three actions:

  1. Creating a new signing key: This will require all your applications and APIs to adopt the new signing key.
  2. Rotating the current key: The existing key will be designated as "previous" after the rotation and will not be utilized by newly created applications and APIs. However, tokens signed with this key will still remain valid.
  3. Removing your previous key: Keys labeled as "previous" will be revoked and removed from the table.
warning

Never rotate signing keys consecutively (two or more times), as this may invalidate ALL issued tokens.

  • For OSS users, after rotating the signing key, a Logto instance restart is required for the new signing key to take effect.
  • For Cloud users, the new signing key takes effect immediately after rotation, but please make sure not to rotate the signing key multiple times consecutively.