Skip to main content

How to Rotate Keycloak RSA Signing Keys

This guide explains how to manually rotate the RSA certificates used for signing tokens in Keycloak.

Background​

Keycloak uses RSA keys to sign JWTs (ID tokens, access tokens). Key rotation is important for security hygiene and may be required for compliance. Keycloak's key provider system supports seamless rotation without service interruption.

Admin Console Method​

  1. Log into the Keycloak Admin Console
  2. Navigate to Realm Settings → Keys tab
  3. Click on the Providers sub-tab
  4. Find your key provider (typically rsa-generated)

To Rotate Keys​

  1. Click Add provider → rsa-generated
  2. Configure the new provider:
    • Name: Give it a descriptive name (e.g., rsa-generated-2024)
    • Priority: Set higher than existing provider (e.g., if current is 100, set to 200)
    • Key size: 2048 or 4096 bits
    • Algorithm: RS256 (or RS384, RS512 as needed)
  3. Click Save

The new key with higher priority becomes active for signing. Old keys remain available for verification.

Cleanup Old Keys​

After the grace period (see best practices below):

  1. Go to Realm Settings → Keys → Providers
  2. Find the old key provider
  3. Click the trash icon to delete it

Admin REST API Method​

Prerequisites​

Obtain an admin access token:

ADMIN_TOKEN=$(curl -s -X POST "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=<admin-password>" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" | jq -r '.access_token')

View Current Keys​

curl -X GET "https://<keycloak-host>/admin/realms/<realm>/keys" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

List Key Providers (Components)​

curl -X GET "https://<keycloak-host>/admin/realms/<realm>/components?type=org.keycloak.keys.KeyProvider" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Create New RSA Key Provider​

curl -X POST "https://<keycloak-host>/admin/realms/<realm>/components" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rsa-generated-rotated",
    "providerId": "rsa-generated",
    "providerType": "org.keycloak.keys.KeyProvider",
    "config": {
      "priority": ["200"],
      "enabled": ["true"],
      "active": ["true"],
      "keySize": ["2048"],
      "algorithm": ["RS256"]
    }
  }'

Delete Old Key Provider​

First, get the component ID from the list providers response, then:

curl -X DELETE "https://<keycloak-host>/admin/realms/<realm>/components/<component-id>" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Rolling Back Keys​

If a key rotation causes issues, you can rollback to the previous key.

Admin Console Rollback​

  1. Navigate to Realm Settings → Keys → Providers
  2. Click on the new key provider (the one causing issues)
  3. Lower its priority below the old key (e.g., change from 200 to 50)
  4. Click Save

The old key with higher priority becomes active again for signing.

Alternatively, you can delete the problematic new key provider entirely:

  1. Navigate to Realm Settings → Keys → Providers
  2. Find the new key provider
  3. Click the trash icon to delete it

Admin REST API Rollback​

Option 1: Lower the New Key's Priority​

First, get the component ID of the new key provider:

curl -X GET "https://<keycloak-host>/admin/realms/<realm>/components?type=org.keycloak.keys.KeyProvider" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Then update the priority to be lower than the old key:

curl -X PUT "https://<keycloak-host>/admin/realms/<realm>/components/<new-key-component-id>" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<new-key-component-id>",
    "name": "rsa-generated-rotated",
    "providerId": "rsa-generated",
    "providerType": "org.keycloak.keys.KeyProvider",
    "parentId": "<realm-id>",
    "config": {
      "priority": ["50"],
      "enabled": ["true"],
      "active": ["true"],
      "keySize": ["2048"],
      "algorithm": ["RS256"]
    }
  }'

Option 2: Delete the New Key Provider​

curl -X DELETE "https://<keycloak-host>/admin/realms/<realm>/components/<new-key-component-id>" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Rollback Considerations​

  • Tokens signed with the new key: If you delete the new key provider, any tokens signed with that key will become invalid immediately. Users will need to re-authenticate.
  • Prefer priority adjustment: Lowering priority instead of deleting preserves both keys—new tokens use the old key, but tokens signed with the new key remain valid.
  • Client cache: Clients may have cached the JWKS. After rollback, clients fetching fresh keys will see the change. Cached keys may cause temporary validation issues until refreshed.
  • Force client refresh: If clients cache aggressively, you may need to restart client applications or wait for their cache TTL to expire.