HashiCorp Vault Integration for Credential Management

The integration supports the following authentication methods:

• Token Authentication
• AppRole Authentication

The retrieved credentials can be used for:

• Database connections
• REST API login/authentication

Benefits

Using HashiCorp Vault provides the following benefits:

• Credentials are not required to be stored directly in application configuration files.
• Credentials can be centrally managed in HashiCorp Vault.
• Access to secrets can be controlled through Vault authentication and policies.
• The same GenRocket configuration can retrieve credentials at runtime without exposing the actual username and password.

How the Integration Works

The general flow is:

1. GenRocket connects to HashiCorp Vault
2. Authenticate
   1. Token
   2. AppRole
3. Read secret from configured secret path
4. Extract configured username/password keys
5. Use credentials for the following:
   1. Database Connection
   2. REST API Authentication

HashiCorp Vault Configuration

The following parameters are used to configure the HashiCorp Vault integration.

Authentication Methods

Token Authentication

With token authentication, GenRocket uses a Vault token to authenticate with HashiCorp Vault.

Configuration

vault=hashiCorp
vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/credentials
authMethod=token

vaultToken=<VAULT_TOKEN>

userKey=userKeyInVault
passwordKey=passwordKeyInVault

debug=false

Example

vault=hashiCorp

vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/credentials

authMethod=token
vaultToken=<VAULT_TOKEN>

userKey=myapp_user_key
passwordKey=myapp_password_key

debug=false

AppRole Authentication

AppRole authentication uses a Role ID and Secret ID to authenticate GenRocket with Vault.

Configuration

vault=hashiCorp

vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/oauth

authMethod=approle

roleId=<ROLE_ID>
secretId=<SECRET_ID>

userKey=userKeyInVault
passwordKey=passwordKeyInVault

debug=false

Example

vault=hashiCorp
vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/oauth

authMethod=approle
roleId=<ROLE_ID>
secretId=<SECRET_ID>

userKey=myapp_user_key
passwordKey=myapp_password_key

debug=true

The Role ID identifies the configured AppRole, while the Secret ID is used as the credential for authenticating against that AppRole.

After successful authentication, GenRocket obtains the Vault authentication token and uses it to retrieve the configured secret.

Database Connection Using HashiCorp Vault

HashiCorp Vault can be used to retrieve credentials before establishing a database connection.

The database configuration does not need to contain the actual database username and password when those values are retrieved from HashiCorp Vault.

Example Database Configuration

driver=com.mysql.jdbc.Driver

url=jdbc:mysql://localhost:3306/bank_demo?rewriteBatchedStatements=true&allowLoadLocalInfile=true

batchCount=100

# HashiCorp Vault Configuration
vault=hashiCorp

# Vault Server Configuration
vaultUrl=http://127.0.0.1:8200

# Secret Path
secretPath=secret/data/api/oauth

# Authentication Method
authMethod=approle

# AppRole Authentication
roleId=<ROLE_ID>
secretId=<SECRET_ID>

# Secret Key Mapping
userKey=userKeyInVault
passwordKey=passwordKeyInVault

# Debug Mode
debug=true

Runtime Flow

1. GenRocket reads database configuration
2. Detects vault=hashiCorp within the configuration
3. Connects to configured Vault URL
4. Authenticates using configured authMethod (token or appRole)
5. Reads secretPath
6. Retrieves userKey and passwordKey
7. Uses retrieved credentials
8. Establishes database connection

REST API Authentication Using HashiCorp Vault (RESTDirectoryV2Receiver)

HashiCorp Vault can also be used when a REST API requires username/password authentication.

In this scenario, GenRocket retrieves the login credentials from the Vault and uses them in the configured login request.

Example

<?xml version="1.0" encoding="UTF-8"?>
<configs>

    <!-- Common headers applied to all requests -->
    <commonHeaders>
        <header type="constant" name="Accept">application/json</header>
        <header type="constant" name="Content-Type">application/json</header>
    </commonHeaders>

    <!-- Login configuration -->
    <login
        responseTokenName="access_token"
        vault="hashiCorp"
        authorizationHeaderName="Authorization"
        includeBearer="true">

        <requestURL>https://app.genrocket.com/home/login</requestURL>
        <method>POST</method>

        <contentType name="response">JSON</contentType>
        <contentType name="request">JSON</contentType>

        <!-- HashiCorp Vault configuration -->
        <vault>

            <parameter name="vaultUrl">
                http://127.0.0.1:8200
            </parameter>

            <parameter name="authMethod">
                approle
            </parameter>

            <parameter name="roleId">
                <ROLE_ID>
            </parameter>

            <parameter name="secretId">
                <SECRET_ID>
            </parameter>

            <parameter name="secretPath">
                secret/api/oauth
            </parameter>

            <parameter name="userKey">
                userKeyInVault
            </parameter>

            <parameter name="passwordKey">
                passwordKeyInVault
            </parameter>

            <parameter name="loginUserName">
                username
            </parameter>

            <parameter name="loginPassword">
                password
            </parameter>

            <parameter name="debug">
                false
            </parameter>

        </vault>

        <parameter name="grant_type">
            password
        </parameter>

    </login>

    <!-- API endpoint configuration -->
    <config tag="postData">

        <requestURL>
            https://app.genrocket.com/home/org
        </requestURL>

        <method>POST</method>

        <headers>
            <header
                type="timestamp"
                name="X-Timestamp"
                format="yyyy-MM-dd'T'HH:mm:ss.SSS'Z'">
                timestamp
            </header>

            <header
                type="UUID"
                name="X-Correlation-ID">
                correlation-id
            </header>
        </headers>

    </config>

</configs>

Understanding the API Vault Parameters

The Vault parameters in the API configuration define where GenRocket retrieves the login credentials and how those credentials are passed to the REST API. 

The configuration uses two sets of parameters, which serve two different purposes:

Vault Credential Keys

These identify the keys inside the Vault Secret and tell GenRocket where to get the credentials from the Vault. . 

<parameter name="userKey">userKeyInVault</parameter>
<parameter name="passwordKey">passwordKeyInVault</parameter>

Example: 

userKeyInVault     = <USERNAME>
passwordKeyInVault = <PASSWORD>

API Login Field Names

These identify the fields expected by the target REST API and tell GenRocket which API login fields receive the Vault Key Credentials

<parameter name="loginUserName">username</parameter>
<parameter name="loginPassword">password</parameter>

For example, the API may expect:

{
    "username": "<USERNAME>",
    "password": "<PASSWORD>"
}

Quick Vault  Parameter Example

For example, suppose the Vault secret contains:

userKeyInVault     = <USERNAME>
passwordKeyInVault = <PASSWORD>

GenRocket retrieves these values using userKey and passwordKey. It then places the retrieved values into the API fields specified by loginUserName and loginPassword.

The resulting login request contains:

{
  "username": "<USERNAME>",
  "password": "<PASSWORD>"
}

Credential Flow

The credential flow is:

HashiCorp Vault
    |
    |  userKeyInVault     -> <USERNAME>
    |  passwordKeyInVault -> <PASSWORD>
    |
    v
GenRocket retrieves the credentials
    |
    |  loginUserName -> username
    |  loginPassword -> password
    |
    v
REST API Login Request

{
  "username": "<USERNAME>",
  "password": "<PASSWORD>"
}

REST API Token Authentication

HashiCorp Vault integration can also be configured with Vault Token authentication.

Example

<vault>

    <parameter name="vaultUrl">
        http://127.0.0.1:8200
    </parameter>

    <parameter name="authMethod">
        token
    </parameter>

    <parameter name="vaultToken">
        <VAULT_TOKEN>
    </parameter>

    <parameter name="secretPath">
        secret/data/api/credentials
    </parameter>

    <parameter name="userKey">
        userKeyInVault
    </parameter>

    <parameter name="passwordKey">
        passwordKeyInVault
    </parameter>

    <parameter name="loginUserName">
        username
    </parameter>

    <parameter name="loginPassword">
        password
    </parameter>

    <parameter name="debug">
        false
    </parameter>

</vault>

The difference between Token and AppRole authentication is how GenRocket authenticates to HashiCorp Vault.

Token:

authMethod = token
vaultToken = <VAULT_TOKEN>

AppRole:

authMethod = approle
roleId     = <ROLE_ID>
secretId   = <SECRET_ID>

Nested Secret Keys

The credential mapping supports nested keys using dot notation.

For example, a Vault secret may contain:

{
    "data": {
        "credentials": {
            "username": "<USERNAME>",
            "password": "<PASSWORD>"
        }
    }
}

The corresponding configuration can specify:

userKey=data.credentials.username
passwordKey=data.credentials.password

This allows credentials to be retrieved from nested structures instead of only top-level keys.

Debug Mode

The optional debug parameter can be used when troubleshooting Vault integration.

Enable debug logging:

debug=true

Disable debug logging:

debug=false

Configuration Examples

AppRole

vault=hashiCorp
vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/credentials

authMethod=approle
roleId=<ROLE_ID>
secretId=<SECRET_ID>

userKey=username
passwordKey=password

debug=false

Token

vault=hashiCorp
vaultUrl=http://127.0.0.1:8200
secretPath=secret/data/api/credentials

authMethod=token
vaultToken=<VAULT_TOKEN>

userKey=username
passwordKey=password
debug=false

Security Recommendations

The following practices are recommended when configuring HashiCorp Vault integration:

1. Do not commit Vault secrets to source control.
   • Avoid committing Vault tokens, Secret IDs, passwords, or JWTs.
2. Use the least-privilege Vault policy possible.
   • The GenRocket authentication identity should only have access to the required secrets.
3. Prefer AppRole authentication where appropriate.
   • These methods can avoid embedding a long-lived Vault token directly in configuration.
4. Do not enable debug logging in production unless necessary.
5. Use environment variables or deployment-secret mechanisms for sensitive authentication values where supported.
6. Do not include actual credentials in customer documentation.
   • Use placeholders such as:
     • <VAULT_TOKEN>
     • <ROLE_ID>
     • <SECRET_ID>
     • <USERNAME>
     • <PASSWORD>

Troubleshooting

Unable to connect to Vault

Verify:

vaultUrl=http://127.0.0.1:8200

Check that:

1. The Vault server is running.
2. The configured URL is reachable from the GenRocket runtime environment.
3. Network/firewall rules allow the connection.
4. The Vault URL and port are configured correctly.

Authentication Failure

Token authentication

Verify:

authMethod=token
vaultToken=<VAULT_TOKEN>

Ensure the token is valid and has permission to read the configured secret.

AppRole authentication

Verify:

authMethod=approle
roleId=<ROLE_ID>
secretId=<SECRET_ID>

Ensure that:

1. The Role ID is correct.
2. The Secret ID is valid.
3. The AppRole has the required Vault policy.
4. The policy permits access to the configured secret path.

Secret Not Found

Verify:

secretPath=secret/data/api/credentials

The configured path must correspond to the secret containing the required credentials.

Also verify that the configured keys exist:

userKey=userKeyInVault
passwordKey=passwordKeyInVault

For example, the secret should contain corresponding keys:

userKeyInVault
passwordKeyInVault

If nested keys are used, verify the complete dot-notated path:

userKey=data.credentials.username
passwordKey=data.credentials.password

Username or Password Not Retrieved

Check the mapping between:

Vault Secret Key
        ↓
userKey / passwordKey
        ↓
Retrieved Credential
        ↓
Database or API authentication

For REST APIs, also verify the API field mapping:

<parameter name="loginUserName">username</parameter>
<parameter name="loginPassword">password</parameter>

The Vault key names and API login field names do not need to be identical.

Summary

HashiCorp Vault integration allows GenRocket to retrieve sensitive credentials at runtime rather than requiring credentials to be directly stored in a database or REST API configuration.

GenRocket can authenticate with HashiCorp Vault using either Token or AppRole authentication, retrieve the required credentials, and use them for a database connection or REST API login.

The integration supports:

                   HashiCorp Vault
                           |
              +------------+------------+
              |            |            |
            Token       AppRole    
              |            |            |
              +------------+------------+
                           |
                    Retrieve Secret
                           |
                  +--------+--------+
                  |                 |
             DB Connection      REST API

The key configuration concepts are:

For REST API authentication, the API-specific mappings are additionally configured: