95 lines
5.8 KiB
Text
95 lines
5.8 KiB
Text
[[realm_keys]]
|
|
=== 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.
|
|
|
|
To view the active keys for a realm select the realm in the admin console click on `Realm settings` then `Keys`. This
|
|
will show the currently active keys for the realm. {project_name} currently only supports RSA signatures so there
|
|
is only one active keypair. In the future as more signature algorithms are added there will be more active keypairs.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
To add a new generated keypair select `Providers` and choose `rsa-generated` from the dropdown. You can change the priority
|
|
to make sure the new keypair becomes the active keypair. You can also change the `keysize` if you want smaller or larger keys (default is 2048,
|
|
supported values are 1024, 2048 and 4096).
|
|
|
|
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.
|
|
|
|
Click on `Select file` for `Private RSA Key` to upload your private key. The file should be encoded in PEM format. You
|
|
don't need to upload the public key as it is automatically extracted from the private key.
|
|
|
|
If you have a signed certificate for the keys click on `Select file` next to `X509 Certificate`. If you don't have one
|
|
you can skip this and a self-signed certificate will be generated.
|
|
|
|
==== 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.
|
|
|
|
Fill in the values for `Keystore`, `Keystore Password`, `Key Alias` and `Key Password` and click on `Save`.
|
|
|
|
==== Making keys passive
|
|
|
|
Locate the keypair in `Active` then click on the provider in the `Provider` column. This will take you to the
|
|
configuration screen for the key provider for the keys. Click on `Active` to turn it `OFF`, then click on `Save`. The
|
|
keys will no longer be active and can only be used for verifying signatures.
|
|
|
|
==== Disabling keys
|
|
|
|
Locate the keypair in `Active` then click on the provider in the `Provider` column. This will take you to the
|
|
configuration screen for the key provider for the keys. Click on `Enabled` to turn it `OFF`, then click on `Save`. The
|
|
keys will no longer be enabled.
|
|
|
|
Alternatively, you can delete the provider from the `Providers` table.
|
|
|
|
==== 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.
|
|
|
|
Then to ensure that client applications won't accept the tokens signed by the compromised key, you should update and push not-before policy for
|
|
the realm, which is doable from the admin console. Pushing new policy will ensure that client applications won't accept the existing
|
|
tokens signed by the compromised key, but also the client application will be forced to download new keypair from the {project_name}, hence
|
|
the tokens signed by the compromised key won't be valid anymore. Note that your REST and confidential clients must have set `Admin URL`, so that
|
|
{project_name} is able to send them the request about pushed not-before policy.
|