Add guide about upcoming HashiCorp Vault integration

content/guides/security-hashicorp-vault-credential-store.adoc

@@ -0,0 +1,211 @@
+---
+layout: guide
+---
+= Upcoming integration of HashiCorp Vault within WildFly
+:summary: How to integrate WildFly with HashiCorp Vault to use it as a credential store for managing secrets.
+:includedir: /templates
+include::../../templates/partials/guides/attributes.adoc[]
+:prerequisites-time: 15
+
+We are working on adding ability to use HashiCorp Vault as a credential store in WildFly. This integration will be added through a dedicated subsystem and feature pack which are in alpha stages of development. This guide demonstrates how to set up and use the HashiCorp Vault credential store with WildFly.
+
+include::../../templates/partials/guides/prerequisites.adoc[]
+* HashiCorp Vault server (or Docker for testing)
+* 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 in-progress integration currently allows you to:
+
+* Store credentials in HashiCorp Vault
+* Reference Vault secrets from other WildFly subsystems using standard credential-reference mechanisms
+* Manage credentials through WildFly management operations
+
+**Note:** The HashiCorp Vault subsystem is currently in Alpha stage with `experimental` stability, so you must start provisioned server with the experimental stability flag.
+
+== 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:
+
+[source,bash]
+----
+docker run -p 8200:8200 -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' hashicorp/vault
+----
+
+This starts Vault in development mode with HTTP endpoint at `http://localhost:8200` and with root token: `myroot`.
+
+For production, you should use a properly configured Vault server with TLS and secure token management.
+
+=== Step 1: Build the Feature Pack
+
+First, build the feature pack from the repository:
+
+[source,bash]
+----
+git clone https://github.com/wildfly-security-incubator/wildfly-hashicorp-vault-feature-pack
+cd wildfly-hashicorp-vault-feature-pack
+mvn clean install
+----
+
+This builds the feature pack and installs it to your local Maven repository.
+
+=== 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:
+
+[source,bash]
+----
+galleon.sh install org.wildfly:wildfly-hashicorp-vault-feature-pack:1.0.0.Alpha1-SNAPSHOT \
+  --layers=hashicorp-vault \
+  --dir=wildfly
+----
+
+This command creates a `wildfly` directory with a 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:
+
+[source,bash]
+----
+./wildfly/bin/standalone.sh --stability=experimental
+----
+
+== Configuring the Credential Store in the HashiCorp Vault Subsystem
+
+The `credential-store` in the `hashicorp-vault` subsystem can be configured with various attributes to connect to your Vault server.
+
+=== Configuration Attributes
+
+[cols="1,1,3,2"]
+|===
+|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 TLS verification
+|`/path/to/truststore.jks`
+
+|`keystore-path`
+|No
+|Path to keystore file for mutual TLS authentication or client certificate 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"`
+|===
+
+=== CLI Configuration Example
+
+You can configure a minimal credential store using the WildFly CLI:
+
+[source,bash]
+----
+$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"}
+)
+----
+
+**Note:** You can configure TLS for your connection by using the `truststore-path`, `keystore-path`, and `keystore-password` attributes listed in the table above.
+
+== Using Credential Store References
+
+Once configured, the credential store can be referenced from other subsystems using the standard `credential-reference` attributes.
+
+=== 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
+
+=== Example: Using with LDAP
+
+Here's an example of using the HashiCorp Vault credential store with an LDAP connection:
+
+[source,xml]
+----
+<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 specifies the credential located at vault path and key in the format `<vault-path>.<key>`.
+
+== Runtime Operations
+
+The subsystem provides runtime operations for managing credentials in Vault:
+
+=== Add a Credential
+
+Add a new credential to Vault through the WildFly management interface:
+
+[source,bash]
+----
+/subsystem=hashicorp-vault/credential-store=my-vault:add-alias(
+    alias="secret/myapp.database_password",
+    secret-value="supersecret"
+)
+----
+
+This creates or updates the `database_password` key in the `secret/myapp` path in Vault.
+
+=== Remove a Credential
+
+Remove a credential from Vault:
+
+[source,bash]
+----
+/subsystem=hashicorp-vault/credential-store=my-vault:remove-alias(
+    alias="secret/myapp.database_password"
+)
+----
+
+This removes the `database_password` key from the `secret/myapp` path in Vault.
+
+== Additional Resources
+
+* link:https://www.vaultproject.io/[HashiCorp Vault Documentation]
+* link:https://docs.wildfly.org/galleon/[Galleon Documentation]
+* link:https://docs.wildfly.org/35/WildFly_Elytron_Security.html#CredentialStore[Elytron's Credential Store Security Guide]
+* Project Repositories:
+** https://github.com/wildfly-security-incubator/wildfly-elytron-hashicorp-vault
+** https://github.com/wildfly-security-incubator/wildfly-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, you can also create GitHub issues with features you'd like to see: https://github.com/wildfly-security-incubator/wildfly-hashicorp-vault-feature-pack/issues
+or reach us on Zulip: https://wildfly.zulipchat.com/#narrow/stream/173102-wildfly-elytron
+

data/guides.yaml

@@ -115,6 +115,10 @@ categories:
   - category: Security
     cat-id: security
     guides:
+      - title: Upcoming integration of HashiCorp Vault within WildFly
+        url: /guides/security-hashicorp-vault-credential-store
+        description: How to integrate WildFly with HashiCorp Vault to use it as a credential store for managing secrets.
+        keywords: Security, Credential Store, HashiCorp Vault, Vault, Secrets Management, Credential Reference
       - title: Securing WildFly Apps with Keycloak on OpenShift
         url: /guides/security-oidc-openshift
         description: Learn how to secure applications deployed to WildFly on OpenShift with the Keycloak OpenID provider.
@@ -159,5 +163,3 @@ categories:
         url: /guides/security-credential-store-enc-exp
         description: How to set up encrypted expressions and use it to replace clear-text sensitive information.
         keywords: Security, Credential Stores, Encrypted Expressions
-
-