keycloak-scim/server_admin/topics/realms/keys.adoc

[[realm_keys]]
=== Configuring realm keys

The authentication protocols that are used by {project_name} require cryptographic signatures and sometimes
encryption.  {project_name} uses asymmetric key pairs, a private and public key, to accomplish this.

{project_name} has a single active keypair at a time, but can have several passive keys as well. The active keypair
is used to create new signatures, while the passive keypairs can be used to verify previous signatures. This makes it
possible to regularly rotate the keys without any downtime or interruption to users.

When a realm is created a key pair and a self-signed certificate is automatically generated.

.Procedure
. Select the realm in the Admin Console.
. Click *Realm settings*.
. Click *Keys*.
. Click *Passive* to view passive keys.
. Click *Disabled* to view disabled keys.

To view passive or disabled keys select `Passive` or `Disabled`.
A keypair can have the status `Active`, but still not be selected as the currently active keypair for the realm.
The selected active pair which is used for signatures is selected based on the first key provider sorted by priority
that is able to provide an active keypair.

==== Rotating keys

It's recommended to regularly rotate keys. To do so you should start by creating new keys with a higher priority than
the existing active keys. Or create new keys with the same priority and making the previous keys passive.

Once new keys are available all new tokens and cookies will be signed with the new keys. When a user authenticates to an
application the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are
signed with the new keys. This means that over time all cookies and tokens will use the new keys and after a while the
old keys can be removed.

How long you wait to delete old keys is a tradeoff between security and making sure all cookies and tokens are updated.
In general it should be acceptable to drop old keys after a few weeks. Users that have not been active in the period
between the new keys where added and the old keys removed will have to re-authenticate.

This also applies to offline tokens. To make sure they are updated the applications need to refresh the tokens before
the old keys are removed.

The frequency of deleting old keys is a tradeoff between security and making sure all cookies and tokens are updated. Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys. If a user was inactive in the period between the new keys being added and the old keys being removed, that user will have to re-authenticate.

Rotating keys also applies to offline tokens. To make sure they are updated, the applications need to refresh the tokens before the old keys are removed.

As a guideline, it may be a good idea to create new keys every 3-6 months and delete old keys 1-2 months after the new
keys were created.

==== Adding a generated keypair

.Procedure
. Select the realm in the Admin Console.
. Click *Realm settings*.
. Click the *Keys* tab.
. Click the *Providers* tab.
. Click *Add keystore* and select *rsa-generated*.
. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
. Select a value for *keysize*.
. Click *Save*.

Click `Save` to add the new keys. This will generated a new keypair including a self-signed certificate.

Changing the priority for a provider will not cause the keys to be re-generated, but if you want to change the keysize
you can edit the provider and new keys will be generated.

==== Adding an existing keypair and certificate

To add a keypair and certificate obtained elsewhere select `Providers` and choose `rsa` from the dropdown. You can change
the priority to make sure the new keypair becomes the active keypair.

.Prerequisites
* A private key file. The file must be PEM formatted.

.Procedure
. Select the realm in the Admin Console.
. Click *Realm settings*.
. Click the *Keys* tab.
. Click the *Providers* tab.
. Click *Add keystore* and select *rsa*.
. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
. Click *Select file* beside *Private RSA Key* to upload the private key file.
. If you have a signed certificate for your private key,  click *Select file* beside *X509 Certificate* to upload the certificate file. {project_name} autmatically generates a self-signed certificate if you do not upload a certificate.
. Click *Save*.

==== Loading keys from a Java Keystore

To add a keypair and certificate stored in a Java Keystore file on the host select `Providers` and choose `java-keystore`
from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.

.Procedure
. Select the realm in the Admin Console.
. Click *Realm settings*.
. Click the *Keys* tab.
. Click the *Providers* tab.
. Click *Add keystore* and select *java-keystore*.
. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
. Enter a value for *Keystore*.
. Enter a value for *Keystore Password*.
. Enter a value for *Key Alias*.
. Enter a value for *Key Password*.
. Click *Save*.

==== Making keys passive

.Procedure
. Select the realm in the Admin Console.
. Click Realm settings.
. Click the *Keys* tab.
. Click the *Active* tab.
. Click the provider of the key you want to make passive.
. Toggle *Active* to *OFF*.
. Click *Save*.

==== Disabling keys

.Procedure
. Select the realm in the Admin Console.
. Click Realm settings.
. Click the *Keys* tab.
. Click the *Active* tab.
. Click the provider of the key you want to make passive.
. Toggle *Enabled* to *OFF*.
. Click *Save*.

==== Compromised keys

{project_name} has the signing keys stored just locally and they are never shared with the client applications, users or other
entities. However, if you think that your realm signing key was compromised, you should first generate new keypair as described above and
then immediately remove the compromised keypair.

Alternatively, you can delete the provider from the `Providers` table.

.Procedure
. Click *Clients* in the menu.
. Click *security-admin-console*.
. Click the *Revocation* tab.
. Click *Set to now*.
. Click *Push*.

Pushing the not-before policy ensures that client applications do not accept the existing tokens signed by the compromised key. The client application is forced to download new key pairs from {project_name} also so the tokens signed by the compromised key will be invalid.

[NOTE]
====
REST and confidential clients must set *Admin URL* so {project_name} can send clients the pushed not-before policy request.
====