libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

Documentation for RHSSO-107 Realm key rotation

Browse source
This commit is contained in:
Stian Thorgersen 2016-10-14 10:34:47 +02:00
parent 0c73ab6c8f
commit 03604724b2
2 changed files with 78 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
SUMMARY.adoc
View file

@ -10,7 +10,6 @@
.. link:topics/realms/master.adoc[The Master Realm]
.. link:topics/realms/create.adoc[Creating a New Realm]
.. link:topics/realms/ssl.adoc[Realm SSL Mode]
.. link:topics/realms/keys.adoc[Realm Key Pairs]
.. link:topics/realms/cache.adoc[Clearing Server Caches]
.. link:topics/realms/email.adoc[Email Settings]
.. link:topics/realms/themes.adoc[Themes and Internationalization]
@ -59,6 +58,7 @@
. link:topics/admin-console-permissions.adoc[Admin Console Access Control and Permissions]
.. link:topics/admin-console-permissions/master-realm.adoc[Master Realm]
.. link:topics/admin-console-permissions/per-realm.adoc[Dedicated Realm Admin Consoles]
. link:topics/realms/keys.adoc[Realm Keys]
. link:topics/identity-broker.adoc[Identity Brokering]
.. link:topics/identity-broker/overview.adoc[Brokering Overview]
.. link:topics/identity-broker/default-provider.adoc[Default Provider]

87
topics/realms/keys.adoc
View file

@ -1,16 +1,83 @@
=== Realm Key Pairs
=== Realm Keys
The authentication protocols that are used by {{book.project.name}} require cryptographic signatures and sometimes even
encryption. {{book.project.name}} uses an asymmetric key pair, a private and public key to accomplish this. When a realm
is created a key pair is automatically generated. It is recommended that you cycle this key pair occasionally. How often
you do this is dependent on your organizational needs and security requirements as you have to make sure every application
that needs the public key or certificate of your realm gets this updated. This can be a lot of work!
The authentication protocols that are used by {{book.project.name}} require cryptographic signatures and sometimes
encryption. {{book.project.name}} uses asymmetric key pairs, a private and public key, to accomplish this.
To cycle a key pair click on the `Realm Settings` left menu item, go to the `Keys` tab, and push the `Generate new keys` button.
{{book.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.
.Keys tab
image:../../{{book.images}}/keys-tab.png[]
When a realm is created a key pair and a self-signed certificate is automatically generated.
This will create a brand new key pair for your realm.
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. {{book.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 all available keys select `All`. This will show all active, passive and disabled keys. 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 the first key provider sorted by priority that is able to provide an
active keypair.
==== Rotation 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 where 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 a 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` or `All` 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` or `All` 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 active and can only be used for verifying signatures.
Alternatively, you can delete the provider from the `Providers` table.