Token Signing Key Rotation

LoginRadius supports rotating the cryptographic keys used to sign OAuth/OIDC access token and ID token JWTs, and revoking a key immediately if it's ever compromised. Rotation and revocation are triggered from the Admin Console on whatever schedule fits your security policy. This page explains why keys should be rotated, how it affects token verification, and how applications should consume the JSON Web Key Set (JWKS) so verification never breaks during a rotation.

1. Why You Should Rotate Signing Keys

Rotating signing keys on a regular schedule is a standard cryptographic hygiene practice, not just a response to an incident:

Limits key exposure. The longer a signing key is in use, the larger the window for it to be leaked, stolen, or brute-forced. Rotating on a schedule bounds that window.
Follows industry guidance. Security standards such as NIST and OWASP recommend rotating signing keys roughly every 3-6 months.
Avoids indefinite reliance on one key. No single key or algorithm is trusted forever, which matters if cryptographic assumptions weaken over time.

Key revocation is different from rotation - it's an emergency action used when a key is known or suspected to be compromised, when regulatory obligations (e.g., PCI-DSS, HIPAA, GDPR) require immediate invalidation, or when an application/tenant is decommissioned. Revocation immediately invalidates a key for both signing and verification; anything signed by it stops validating right away.

2. Key Lifecycle

Every signing key moves through a small set of states, shown in the Admin Console as the key's status:

State	Meaning
Currently used	Actively signing new tokens.
Next in queue	Pre-generated and scheduled to become the active signing key at the next rotation.
Verification only	No longer used to sign new tokens, but still published for a 60-day grace period so tokens signed before the rotation keep verifying until they expire or the grace period ends.
Revoked	Permanently invalid for both signing and verification - either because the grace period elapsed or the key was manually revoked.

This lifecycle is what makes rotation "zero-downtime": a token signed just before a rotation still verifies successfully afterward, because its key stays published as Verification Only for a 60-day grace period.

3. The JWKS Endpoint

A JWKS (JSON Web Key Set) is a JSON document publishing the public keys relying parties use to verify JWT signatures, per RFC 7517 and the OpenID Connect Core 1.0 specification. LoginRadius exposes the tenant's key set for your application at:

https://<HD or CD>/service/oidc/{OAuthClientName}/jwks

Where:

HD (Hosted Domain): your tenant's default domain, <TenantName>.hub.loginradius.com.
CD (Custom Domain): a custom domain configured for your tenant, if applicable.
OAuthClientName: the name of your OAuth/OIDC application.

Algorithm: all signing key pairs are generated using RS256 (RSA, 2048-bit). Every key published in the JWKS is an RS256 public key - clients should reject any token whose header claims a different algorithm (e.g., none, or HS256 with the public key reused as a symmetric secret), since that pattern is a known algorithm-confusion attack rather than a valid LoginRadius-issued token.

What's published: the JWKS response includes every key marked Currently used or Verification only. Keys marked Next in queue or Revoked are never published, so a client can never be handed a key that isn't yet - or is no longer - trusted.

4. How Clients Should Verify Tokens

Fetch the JWKS from the endpoint above rather than hardcoding a public key or certificate - this is what allows your integration to survive rotation with zero code changes.
Every JWT header includes a kid (Key ID) claim. Use it to select the matching key from the JWKS response rather than assuming a single fixed key.
Cache the JWKS response locally to avoid a network round trip per verification, but respect a reasonable TTL (or your library's default) so a rotation is picked up promptly rather than being missed for an extended period.
Reject any token whose kid doesn't match a key currently published in the JWKS - this is the correct behavior once a key has moved out of the grace period and been revoked.
Enforce the expected algorithm (RS256) in your verification call rather than trusting the alg in the token header, so a maliciously modified header can't downgrade verification.

Example: Verifying a Token (Node.js)

const jwt = require("jsonwebtoken");
const jwksClient = require("jwks-rsa");

const client = jwksClient({
  jwksUri: "https://<HD or CD>/service/oidc/{OAuthClientName}/jwks",
});

function getSigningKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    if (err) return callback(err);
    callback(null, key.getPublicKey());
  });
}

jwt.verify(token, getSigningKey, { algorithms: ["RS256"] }, (err, decoded) => {
  if (err) {
    // Fails here if: the kid isn't in the JWKS (rotated out and revoked,
    // or unrecognized), the token is expired, or the algorithm doesn't match.
    throw err;
  }
  // `decoded` is the verified token payload.
});

getSigningKey fetches and caches the JWKS automatically, resolves the correct public key by kid, and refreshes its cache when it encounters a kid it doesn't recognize - so this same code keeps working across rotations without changes.

5. Managing Keys in the Admin Console

Tenant administrators manage signing keys from Tenant Settings > Signing Keys:

Rotate Signing Key - rotates only the currently used signing key. All tokens signed with it continue to be valid; it moves to Verification Only status and the next-in-queue key becomes the currently used key.
Rotate & Revoke Signing Key - rotates and additionally revokes the currently used signing key. All tokens signed with it will no longer be valid. This is the break-glass action for a suspected compromise, and it forces affected users/clients to re-authenticate.
Valid Keys - lists each key's ID alongside its status: Currently used, Next in queue, or Verification only.
Revoked Keys - lists the last 3 revoked keys for the tenant, retained for 90 days, with the date each was revoked and its Key ID.
Viewing keys requires configuration-read access; rotating or revoking requires a higher-privileged admin permission, consistent with least-privilege access control.

Signing Certificate Actions

Each valid signing key's Actions menu offers three options - Copy, View, and Download Signing Certificate - for integrations that require direct access to the public signing certificate instead of relying solely on the JWKS endpoint.

The Download action provides the certificate as a standalone file for systems that require manual certificate configuration, while Copy makes it easy to use the certificate directly. The View action displays certificate details, including its Fingerprint and Thumbprint, which can help with verification, troubleshooting, and auditing.

For most integrations, the JWKS endpoint remains the recommended approach for JWT signature verification, as it enables dynamic key discovery and allows integrations to handle signing key rotations automatically. The certificate actions provide flexibility for systems that require a more manual or fixed certificate setup.

6. Security Recommendations

Rotate on a fixed schedule (3-6 months) rather than only reactively.
Treat Rotate & Revoke as an incident-response action: notify downstream relying parties where feasible, since it forces tenant-wide re-authentication.
Always verify via the published JWKS and kid - never pin a single certificate or key in your integration.
Ensure your token validation library rejects deprecated or weak algorithms (e.g., refuses alg: none) rather than trusting whatever the token header claims.