mp.integrations.hcv.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2021, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= HashiCorp Vault
:description: Helidon HashiCorp Vault integration
:keywords: vault, hashicorp
:feature-name: HashiCorp Vault
:rootdir: {docdir}/../..
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
HashiCorp Vault is a commonly used Vault in many microservices. The APIs are REST-based and Helidon implements them using
xref:{webclient-page}[WebClient].
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.integrations.vault
helidon-integrations-vault-cdi
----
The following is a list of maven coordinates of all Vault modules available:
[source,xml]
----
io.helidon.integrations.vault.auths
helidon-integrations-vault-auths-token
io.helidon.integrations.vault.auths
helidon-integrations-vault-auths-approle
io.helidon.integrations.vault.auths
helidon-integrations-vault-auths-k8s
io.helidon.integrations.vault.secrets
helidon-integrations-vault-secrets-kv1
io.helidon.integrations.vault.secrets
helidon-integrations-vault-secrets-kv2
io.helidon.integrations.vault.secrets
helidon-integrations-vault-secrets-cubbyhole
io.helidon.integrations.vault.secrets
helidon-integrations-vault-secrets-transit
io.helidon.integrations.vault.secrets
helidon-integrations-vault-secrets-database
io.helidon.integrations.vault.sys
helidon-integrations-vault-sys
----
== Usage
Vault integration supports the following:
* *Secret Engines*: Key/Value version 2, Key/Value version 1, Cubbyhole, PKI, Transit, Database
* *Authentication Methods*: Token, Kubernetes (k8s), AppRole
* *Other Sys Operations and Configurations*
Each of these features is implemented as a separate module, with the Vault class binding them together. In Helidon MP, with injection, this binding is done automatically, and you can simply inject your favorite secret engine.
The following classes can be injected into any CDI bean (if appropriate module is on the classpath):
* Kv2Secrets - Key/Value Version 2 Secrets (versioned secrets, default)
* Kv1Secrets - Key/Value Version 1 Secrets (un-versioned secrets, legacy)
* CubbyholeSecrets - Cubbyhole secrets (token bound secrets)
* DbSecrets - Database secrets (for generating temporary DB credentials)
* PkiSecrets - PKI secrets (for generating keys and X.509 certificates)
* TransitSecrets - Transit operations (encryption, signatures, HMAC)
* AppRoleAuth - AppRole authentication method (management operations)
* K8sAuth - Kubernetes authentication method (management operations)
* TokenAuth - Token authentication method (management operations)
* Sys - System operations (management of Vault - enabling/disabling secret engines and authentication methods)
In addition to these features, Vault itself can be authenticated as follows:
* Token authentication - token is configured when connecting to Vault
[source,properties]
----
vault.address=http://localhost:8200
vault.token=my-token
----
* AppRole authentication - AppRole ID and secret ID are configured, integration exchanges these for a temporary token that is used to connect to Vault
[source,properties]
----
vault.auth.app-role.role-id=app-role-id
vault.auth.app-role.secret-id=app-role-secret-id
----
* K8s authentication - the k8s JWT token is discovered on current node and used to obtain a temporary token that is used to connect to Vault
[source,properties]
----
vault.auth.k8s.token-role=my-role <1>
----
<1> The token role must be configured in Vault
=== Extensibility
New secret engines and authentication methods can be implemented quite easily, as the integration is based on service providers (using ServiceLoader). This gives us (or you, as the users) the option to add new secret engines and/or authentication methods without adding a plethora of methods to the Vault class.
See the following SPIs:
[source,listing]
----
io.helidon.integrations.vault.spi.AuthMethodProvider
io.helidon.integrations.vault.spi.SecretsEngineProvider
io.helidon.integrations.vault.spi.SysProvider
io.helidon.integrations.vault.spi.VaultAuth
io.helidon.integrations.vault.spi.InjectionProvider
----
== Examples
The following example shows usage of Vault to encrypt a secret using the default Vault configuration (in a JAX-RS resource):
[source,java]
----
include::{sourcedir}/mp/integrations/HcvSnippets.java[tag=snippet_1, indent=0]
----
=== Cubbyhole secrets
Cubbyhole example:
[source,java]
----
include::{sourcedir}/mp/integrations/HcvSnippets.java[tag=snippet_2, indent=0]
----
<1> Create a secret from request entity, the name of the value is `secret`.
<2> Delete the secret on a specified path.
<3> Get the secret on a specified path.
=== KV1 secrets
Key/Value version 1 secrets engine operations:
[source,java]
----
include::{sourcedir}/mp/integrations/HcvSnippets.java[tag=snippet_3, indent=0]
----
<1> Enable the secrets engine on the default path.
<2> Disable the secrets engine on the default path.
<3> Create a secret from request entity, the name of the value is `secret`.
<4> Delete the secret on a specified path.
<5> Get the secret on a specified path.
=== KV2 secrets
Key/Value version 2 secrets engine operations:
[source,java]
----
include::{sourcedir}/mp/integrations/HcvSnippets.java[tag=snippet_4, indent=0]
----
<1> Create a secret from request entity, the name of the value is `secret`.
<2> Delete the secret on a specified path.
<3> Get the secret on a specified path.
=== Transit secrets
Transit secrets engine operations:
[source,java]
----
include::{sourcedir}/mp/integrations/HcvSnippets.java[tag=snippet_5, indent=0]
----
<1> Enable the secrets engine on the default path.
<2> Disable the secrets engine on the default path.
<3> Create the encrypting and signature keys.
<4> Delete the encryption and signature keys.
<5> Encrypt a secret.
<6> Decrypt a secret.
<7> Create an HMAC for text.
<8> Create a signature for text.
<9> Verify HMAC.
<10> Verify signature.
== Local Testing [[Local-Testing]]
Vault is available as a docker image, so to test locally, you can simply:
[source,bash]
----
docker run -e VAULT_DEV_ROOT_TOKEN_ID=my-token -d --name=vault -p8200:8200 vault
----
This will create a Vault docker image, run it in background and open it on `localhost:8200` with a custom root token my-token, using name vault. This is of course only suitable for local testing, as the root token has too many rights, but it can be easily used with the examples below.
== References
* link:{helidon-github-tree-url}/examples/integrations/vault[Hashicorp Vault Usage Examples]
© 2015 - 2025 Weber Informatics LLC | Privacy Policy