Search

Chapter 8. Vault SPI

download PDF

8.1. Vault provider

You can use a vault SPI from org.keycloak.vault package to write custom extension for Red Hat build of Keycloak to connect to arbitrary vault implementation.

The built-in files-plaintext provider is an example of the implementation of this SPI. In general the following rules apply:

  • To prevent a secret from leaking across realms, you may want to isolate or limit the secrets that can be retrieved by a realm. In that case, your provider should take into account the realm name when looking up secrets, for example by prefixing entries with the realm name. For example, an expression ${vault.key} would then evaluate generally to different entry names, depending on whether it was used in a realm A or realm B. To differentiate between realms, the realm needs to be passed to the created VaultProvider instance from VaultProviderFactory.create() method where it is available from the KeycloakSession parameter.
  • The vault provider needs to implement a single method obtainSecret that returns a VaultRawSecret for the given secret name. That class holds the representation of the secret either in byte[] or ByteBuffer and is expected to convert between the two upon demand. Note that this buffer would be discarded after usage as explained below.

For details on how to package and deploy a custom provider refer to the Service Provider Interfaces chapter.

8.2. Consuming values from vault

The vault contains sensitive data and Red Hat build of Keycloak treats the secrets accordingly. When accessing a secret, the secret is obtained from the vault and retained in JVM memory only for the necessary time. Then all possible attempts to discard its content from JVM memory is done. This is achieved by using the vault secrets only within try-with-resources statement as outlined below:

    char[] c;
    try (VaultCharSecret cSecret = session.vault().getCharSecret(SECRET_NAME)) {
        // ... use cSecret
        c = cSecret.getAsArray().orElse(null);
        // if c != null, it now contains password
    }

    // if c != null, it now contains garbage

The example uses KeycloakSession.vault() as the entrypoint for accessing the secrets. Using the VaultProvider.obtainSecret method directly is indeed also possible. However the vault() method has the benefit of ability to interpret the raw secret (which is generally a byte array) as a character array (via vault().getCharSecret()) or a String (via vault().getStringSecret()) in addition to obtaining the original uninterpreted value (via vault().getRawSecret() method).

Note that since String objects are immutable, their content cannot be discarded by overriding with random garbage. Even though measures have been taken in the default VaultStringSecret implementation to prevent internalizing Strings, the secrets stored in String objects would live at least to the next GC round. Thus using plain byte and character arrays and buffers is preferable.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.