[keycloak-dev] Public key rotation in adapters

Marek Posolda mposolda at redhat.com
Mon Sep 12 15:49:21 EDT 2016

I've sent PR https://github.com/keycloak/keycloak/pull/3228 for the 
above. There are no changes on Keycloak auth-server side, just the 
adapter is now able to retrieve the new realm public key always when new 
keypair for the realm was generated or uploaded.

Summary of changes:
* Adapters don't use our proprietary endpoint for retrieve realm 
public-key, but they instead use the OIDC standard jwks_url, which 
Keycloak server already publish.

* The adapter option "realm-public-key" in keycloak.json is not 
recommended now and I removed it from examples and some tests. The 
reason is, that if you have hardcoded "realm-public-key" in 
keycloak.json, then your adapter will always use this public key and it 
won't try to download new public key in case that new keypair was 
generated for the realm. In other words, application will be unusable if 
realm public key is changed. Still this option is kept in case that 
someone really wants hardcoded public key and never to download it from 

* If "realm-public-key" is not in keycloak.json (new recommended default 
behaviour), then adapter will always try to download new public key from 
realm when it sees the token with unknown "kid" in JWS header. So it's 
not just first request to the app (which we had until now), but always 
when new key is generated, adapter will download it. Adapter has support 
for store more public keys with different "kid", as this is needed for 
transition when tokens signed by both "old" and "new" key are sent to 
the REST app endpoint. There is plan to support more keypairs for the 
single realm too.

* There is some minimum time between requests (10 seconds by default), 
so it's not possible to easily DoS in case that attacker will send lots 
of request to the app with bad "kid" or if lots of request singed by 
outdated "kid" happen. New adapter option added for it.

I have still the docs to do and possibly also update quickstarts and 
remove "realm-public-key" from them?

Next step is to implement something similar for clients and 
identityProviders. The JIRAS are 
https://issues.jboss.org/browse/KEYCLOAK-3493 and 
https://issues.jboss.org/browse/KEYCLOAK-3532 . So the keycloak server 
will be able to download new keypairs in case that keys under "jwks_url" 
of identityProvider (or client) are changed. That's for OIDC 
identityProviders and also for clients using authentication with singed 
JWT . It's needed for OIDC certification.


More information about the keycloak-dev mailing list