Keycloak

Keycloak is an open source identity and access management (IAM) solution. As part of this, Keycloak signs tokens (such as JWTs and SAML assertions) that are verified by the services that rely on Keycloak for delegating authentication.

The Keycloak Securosys HSM Provider enables Keycloak to use a Securosys Primus HSM to securely generate, use, and store the signing keys that protect these tokens.

Why This Matters

Keycloak supports a wide range of protocols, including OpenID Connect, OAuth 2.0, and SAML. All of these protocols have the concept of an Identity Provider (IdP) and a Relying Party (RP) (also called Service Provider (SP)). Keycloak is the IdP. Whenever a user logs in, Keycloak issues a signed token. A RP then verifies the token signature, thereby delegating identity and access management to Keycloak. This requires an existing trust relationship between the RP and the IdP, usually by manually sharing the public key with the RP.

By default, Keycloak stores the private signing keys in its database (PostgreSQL, MariaDB, ...). This exposes the risk of someone getting access to the database, and issuing tokens for any account. For example, the signing key can sign a JWT impersonating an admin, the CEO or a service account. It can grant it different roles and expiry dates, and the Relying Parties will trust it. Similarly, they can bypass SAML assertion, as it can sign assertion for any SAML-federated app.

Ultimately, as the signing key is realm wide, once the key is leaked, every account in the realm is now considered compromised. The only remedy in this situation is to rotate the signing key, forcing every Relying Party to refresh the pinned IdP public keys, and forcing every account to log in again.

If the signing key is generated and stored inside the boundaries of a Primus HSM, this risk is reduced. An attacker cannot obtain a copy of the private key, making it harder to sign malicious tokens that grant unauthorized access.

Architecture

Keycloak is built on a Service Provider Interface (SPI) architecture, which allows the change, customization and configuration of different aspects of Keycloak. One such aspect is key storage. The Keycloak Securosys HSM Provider plugs into this architecture. It enables Keycloak to delegate key generation, usage, and storage to a Primus HSM or CloudHSM.

After configuring your realms to connect to your HSM Partition, the signing requests will be offloaded to the HSM. Currently, the provider supports signing JWTs and SAML assertions. Relying Parties continue to verify signatures locally using the public key.

The provider is part of realm export and import. This is particularly useful during migrations, maintenance and expansion of the environment.

Getting Started

Follow the installation guide to learn how to set up the Keycloak Provider together with a Primus HSM.