keycloak-scim/server_development/topics/vault.adoc

[[_vault-spi]]
== Vault SPI

=== Vault provider

You can use a vault SPI from `org.keycloak.vault` package to write custom extension for {project_name} 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 mey want to isolate or limit what secrets 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.secret-id}` would then evaluate generally
  to different values of a secret `secret-id`, 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 its 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 <<_providers,Service Provider Interfaces>> chapter.

=== Consuming values from vault

The vault contains sensitive data and {project_name} 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:

[source,java]
----
    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 ``String``s, 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 preferrable.