WildFly Elytron

WildFly Elytron

Upcoming WildFly HashiCorp Vault Integration

By Diana Krepinska | December 3, 2025
#hashicorp #vault #credential-store #credential-reference #subsystem #feature-pack

Introduction

We are working on a dedicated subsystem and a feature pack that will provide integration of WildFly server with HashiCorp Vault. We are currently in an Alpha stages of development and you can experiment with the feature pack and provide a feedback as we continue development.

Using the HashiCorp Vault Feature Pack and Subsystem

The HashiCorp Vault feature pack provides a dedicated WildFly subsystem for managing HashiCorp Vault credential stores.

Quick Start

Start HashiCorp Vault (Development Mode)

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

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

Step 1: Build the Feature Pack

First, build the feature pack located at https://github.com/wildfly-security-incubator/wildfly-hashicorp-vault-feature-pack :

git clone https://github.com/wildfly-security-incubator/wildfly-hashicorp-vault-feature-pack
cd wildfly-hashicorp-vault-feature-pack
mvn clean install

Step 2: 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 one you have just built:

galleon.sh install org.wildfly:wildfly-hashicorp-vault-feature-pack:1.0.0.Alpha1-SNAPSHOT \
  --layers=hashicorp-vault \
  --dir=wildfly

Above command created a wildfly directory with the WildFly server that contains the HashiCorp Vault subsystem.

Step 3: Start WildFly with Experimental Stability

The HashiCorp Vault subsystem is currently developed with experimental stability, so you must start WildFly with the experimental stability flag:

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

Configuring the HashiCorp Vault Subsystem

The credential-store in the hashicorp-vault subsystem can currently be configured with the below attributes:

Configuration Attributes

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

production

truststore-path

No

Path to truststore file for SSL/TLS verification

/path/to/truststore.jks

keystore-path

No

Path to keystore file for mutual TLS authentication

/path/to/keystore.jks

keystore-password

No

Password for the keystore file

my-password

credential-reference

No

Reference to credential store or clear-text for Vault authentication token

clear-text="myroot"

XML Configuration Example

For our example, add the subsystem configuration to your standalone.xml:

<subsystem xmlns="urn:wildfly:hashicorp-vault:experimental:1.0">

    <credential-store name="my-vault"
                      host-address="https://vault.example.com:8200"
        <credential-reference clear-text="myroot"/>
    </credential-store>
</subsystem>

Note You can configure certificate stores for your connection by using the attributes listed in the table above.

CLI Configuration Example

This is the command to add the above using the WildFly CLI:

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

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

Note You can configure certificate stores for your connection by using the attributes listed in the table above.

Using Credential Store References

Once configured, the credential store is automatically advertised as a WildFly capability and can be referenced from other subsystems using the standard credential-reference mechanism.

Example: Using with LDAP

<subsystem xmlns="urn:wildfly:elytron:15.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>

Runtime Operations

The subsystem provides runtime operations for managing credentials:

Add a Credential Alias

/subsystem=hashicorp-vault/credential-store=my-vault:add-alias(
    alias="secret/myapp.database_password",
    secret-value="supersecret"
)

Remove a Credential Alias

/subsystem=hashicorp-vault/credential-store=my-vault:remove-alias(
    alias="secret/myapp.database_password"
)

Alias Format

The credential store uses a specific alias format to map WildFly credential references to Vault secrets:

  • Format: <vault-path>.<key>

  • Example: secret/myapp.database_password maps to the database_password key in the secret/myapp path in Vault

Conclusion

This post gave a simple example of how to use hashicorp vault feature pack.

Getting Involved

The HashiCorp Vault feature pack and subsystem are in Alpha stages of development. You can experiment with the feature pack and provide feedback on our work. You are also encouraged to create GH issues with features you’d like to see: https://github.com/wildfly-security-incubator/wildfly-hashicorp-vault-feature-pack/issues. You can also reach us on Zulip: https://wildfly.zulipchat.com/#narrow/stream/173102-wildfly-elytron

Resources