[keycloak-dev] Realm key rotation support

John Dennis jdennis at redhat.com
Fri Sep 23 11:53:39 EDT 2016

On 09/13/2016 09:29 AM, Stian Thorgersen wrote:
> To be able to gracefully rotate the realm keys periodically a realm
> needs to have more than one keypair. One keypair that is active and will
> be used to issue new cookies and tokens. Also, one or more keypairs that
> are inactive that can be used to verify old cookies and tokens.

> This is only for login cookie and OIDC protocol. Is it even necessary to
> have support for multiple certificates for SAML? SAML doesn't have a
> token introspection or refresh of the assertions right, so not sure it's
> needed.

SAML also needs multiple keys during the rotation period. Off the top of 
my head I do not recall if the realm key is used for signing or if an 
independent key is generated. Currently Keycloak does not support SAML 
encryption but when it does the same will apply to encryption keys as 
would currently apply to signing keys.

SAML metadata permits multiple keys to be defined. The current errata 
for SAML metadata (sstc-saml-metadata-errata-2.0-wd-05-diff.pdf) 
includes this edit:

      The inclusion of multiple <KeyDescriptor> elements with 

      the same use attribute (or no such attribute) indicates 

      that any of the included keys may be used by the 

      containing role or affiliation. A relying party SHOULD 

      allow for the use of any of the included keys. When 

      possible the signing or encrypting party SHOULD indicate 

      as specifically as possible which key it used to enable 

      more efficient processing.

This means there will need to be logic in the code that signs and 
verifies signatures to iterate over an (ordered) list of keys *and* in 
the code used to both generate and consume metadata to permit multiple keys.


More information about the keycloak-dev mailing list