HashiCorp Vault credential store integration in WildFly

Table of Contents

Prerequisites
About HashiCorp Vault Integration
Quick Start
Configure the HashiCorp Vault Credential Store
Using Credential Store References
- Example: Using with LDAP
Vault Expressions
What’s next?
References

In this guide, you will provision WildFly with the HashiCorp Vault subsystem, configure a Vault-backed credential store, store and read secrets, and reference them from other subsystems.

WildFly includes support for using HashiCorp Vault as a credential store through a dedicated subsystem and feature-pack. The HashiCorp Vault feature-pack is published to Maven Central and is also available as the hashicorp-vault Galleon layer since WildFly 40 Beta release.

Prerequisites

To complete this guide, you need:

Roughly 15 minutes
JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.9+
HashiCorp Vault server running
Galleon provisioning tools
WildFly server

About HashiCorp Vault Integration

The HashiCorp Vault feature-pack provides a dedicated WildFly subsystem for managing HashiCorp Vault credential stores. This integration currently allows you to:

Store/retrieve credentials in HashiCorp Vault
Reference Vault secrets from other subsystems using standard credential-reference attributes
Usage of Vault secrets using ${HC_VAULT::credential-store-name:alias} expressions
Manage credentials through WildFly management operations (add-alias, remove-alias, read-aliases)

Note: The HashiCorp Vault layer is planned to be moved under the wildfly-ee feature-pack in the upcoming WildFly release. So usage of dedicated feature-pack will be deprecated.

Quick Start

Start HashiCorp Vault (Development Mode)

To try it out, you need a running HashiCorp Vault server. For testing purposes, you can start Vault with Docker:

docker run -p 8200:8200 -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' hashicorp/vault

This starts Vault in development mode with an HTTP endpoint at http://localhost:8200 and root token myroot.

For production, use a properly configured Vault server with TLS and secure token management.

Step 1: Provision WildFly with the Feature-Pack

Download the Galleon provisioning tools and use them to provision a WildFly server with the HashiCorp Vault subsystem. Run the following command, substituting the version with the latest version in Maven Central:

galleon.sh install org.wildfly.security.vault:wildfly-vault-feature-pack:${version} \
  --layers=hashicorp-vault \
  --dir=wildfly

This command creates a wildfly directory with a minimal WildFly server that contains the HashiCorp Vault subsystem for experimentation.

Alternatively, when provisioning a recent WildFly Beta distribution, you can include the hashicorp-vault layer from the wildfly-galleon-pack feature-pack.

Step 2: Start WildFly with Community Stability

Start WildFly with the community stability flag:

./wildfly/bin/standalone.sh --stability=community

Step 3: Configure a Credential Store and Store a Secret

In another terminal, connect to the CLI and add a credential store that points at your Vault instance:

$WILDFLY_HOME/bin/jboss-cli.sh --connect

/subsystem=hashicorp-vault/credential-store=my-vault:add(
    host-address="http://localhost:8200",
    credential-reference={clear-text="myroot"}
)

Store a secret in Vault through the subsystem (this creates the password key at path secret/demo):

/subsystem=hashicorp-vault/credential-store=my-vault:add-alias(
    alias="secret/demo.password",
    secret-value="demo"
)

List aliases under the secret path:

/subsystem=hashicorp-vault/credential-store=my-vault:read-aliases(
    path="secret",
    recursive=true
)

You should see secret/demo.password in the result. Returned aliases use the same path.key format described above.

Alias Format

Aliases map WildFly credential references to Vault secrets. The alias uses a dot: the segment before the dot is the Vault path, and the segment after is the secret key.

Format: <vault-path>.<key> (exactly one dot)
Example: secret/myapp.database_password maps to the database_password key at Vault path secret/myapp

Vault paths may contain slashes; do not use additional dots in the path portion.

Configure the HashiCorp Vault Credential Store

The credential-store resource in the hashicorp-vault subsystem connects WildFly to your Vault server.

Add a Credential Store (CLI)

In production, use authentication-context attribute to specify authentication information.

$WILDFLY_HOME/bin/jboss-cli.sh --connect

/subsystem=hashicorp-vault/credential-store=my-vault:add(
    host-address="http://localhost:8200",
    credential-reference={clear-text="myroot"}
)

Current Configuration Attributes Reference

Attribute Required Description Example

Attribute	Required	Description	Example
`name`	Yes	Unique name for the credential store	`my-vault`
`host-address`	Yes	Vault server URL including protocol and port	`https://vault.example.com:8200`
`namespace`	No	Vault namespace (Enterprise feature)	`production`
`authentication-context`	No	Name of an Elytron `authentication-context` used for outbound TLS to Vault (trust store, client certificate, or mutual TLS)	`vault-tls-context`
`credential-reference`	No	Vault authentication token as clear text, or a reference to another credential store	`clear-text="myroot"`

name

Yes

Unique name for the credential store

my-vault

host-address

Yes

Vault server URL including protocol and port

https://vault.example.com:8200

namespace

Vault namespace (Enterprise feature)

production

authentication-context

Name of an Elytron authentication-context used for outbound TLS to Vault (trust store, client certificate, or mutual TLS)

vault-tls-context

credential-reference

Vault authentication token as clear text, or a reference to another credential store

clear-text="myroot"

The credential-reference and authentication-context child elements support the standard Elytron subsystem attributes.

Securing the Connection with TLS

Below example covers trust-only HTTPS (server TLS only). For mutual TLS, also add a client key-store, key-manager, and reference both managers on client-ssl-context.

/subsystem=elytron/key-store=vault-trust:add(
    type=JKS,
    path=vault-trust.jks,
    relative-to=jboss.server.config.dir,
    credential-reference={clear-text=changeit}
)

/subsystem=elytron/trust-manager=vault-trust-manager:add(key-store=vault-trust)

/subsystem=elytron/client-ssl-context=vault-ssl:add(
    trust-manager=vault-trust-manager,
    cipher-suite-filter=DEFAULT
)

/subsystem=elytron/authentication-context=vault-tls-context:add(
    match-rules=[{match-host=vault.example.com, ssl-context=vault-ssl}]
)

Use the hostname from your Vault URL in match-host (for example vault.example.com when host-address is https://vault.example.com:8200).

Add the credential store over HTTPS

/subsystem=hashicorp-vault/credential-store=my-vault:add(
    host-address="https://vault.example.com:8200",
    authentication-context=vault-tls-context,
    credential-reference={clear-text="VAULT_TOKEN"}
)

Using Credential Store References

Once configured, reference the credential store from other subsystems using the standard credential-reference attributes.

Example: Using with LDAP

<subsystem xmlns="urn:wildfly:elytron:18.0">
    <dir-contexts>
        <dir-context name="ldap-connection" url="ldap://ldap.example.com:389">
            <credential-reference store="my-vault" alias="secret/ldap.bind_password"/>
        </dir-context>
    </dir-contexts>
</subsystem>

The store attribute references the credential store name (my-vault), and the alias attribute uses the path.key format described above.

Vault Expressions

Reference secrets using expressions of the form:

${HC_VAULT::credential-store-name:alias}

For example, ${HC_VAULT::my-vault:secret/myapp.database_password} resolves the database_password key at path secret/myapp using the my-vault credential store.

What’s next?

Read more about Elytron credential stores in the WildFly Elytron Security documentation.
Read about Vault configuration (TLS, namespaces, policies, and token lifecycle) using the HashiCorp Vault documentation.

References

Note	The HashiCorp Vault feature-pack is planned to be moved under the wildfly-ee feature-pack.

You can Report issues on GitHub or reach the team on Zulip (#wildfly-elytron).

< Back to Guides