> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# HashiCorp Vault integration

> Configure HashiCorp Vault integration to manage secrets in Itential Gateway.

To manage secrets and help protect data, Itential Gateway supports **HashiCorp Vault**, a secrets management tool that secures, stores, and tightly controls access to tokens, passwords, certificates, API keys, and other secrets along with key revocation, key rolling, and auditing. HashiCorp Vault also provides secrets-as-a-service through a unified API. For more information, visit [HashiCorp Learn](https://learn.hashicorp.com/tutorials/vault/getting-started-install).

Gateway contains a [Script Execution Engine](/itential-gateway/4/script-execution-engine) that interacts with the key-value secrets stored in HashiCorp Vault. The AG server can fetch secrets stored on a Vault server at runtime and pass the values as command line arguments or environment variables when executing a script.

## Sample script

Below is a sample Python script that takes one command line argument.

```python
#!/usr/bin/env python

import sys

if len(sys.argv) > 1:
  print(f"The secret of foo is {sys.argv[1]}.")
else:
  print("No secret argument passed in")
```

## User schema decoration

To use a Vault secret, you first need to add a user schema to the script. Assuming the script is named `python_secret_demo.py`, you can add the schema below to this script. See [Manage decorations](/itential-gateway/4/manage-decorations) for more information on how a user schema works.

```json
{
    "schema": {
        "title": "schema for python secret",
        "type": "object",
        "properties": {
            "foo": {
                "type": "secret"
            }
        },
        "script_argument_order": ["foo"]
    }
}
```

Here we define a parameter named `foo` with type `secret`. This parameter also needs to be part of `script_argument_order`.

### Sample script payload

Assume the Vault secret you want to fetch is saved in path `hello` with key name `foo`. To execute the script with a secret, run `POST /api/v2.0/scripts/python_secret_demo.py/execute` with the following payload.

```json
{
  "args": {
    "foo": {
      "path": "hello",
      "key_name": "foo"
    }
  },
  "env": {},
  "hosts": []
}
```

### Sample response object

Below is the response object you get from the above example. The secret of `foo` is `bar` in this case.

```json
[
    {
        "status": "SUCCESS",
        "stdout": "The secret of foo is bar.\n",
        "stderr": "",
        "command": "/app/devtools/scripts/python_secret_demo.py bar",
        "env": [],
        "msg": "",
        "argument_warnings": null,
        "env_warnings": null,
        "working_directory": "/root",
        "raw_result": {
            "rc": 0
        }
    }
]
```

> **Info**
>
> This feature may have different behavior between releases.

## Execute script from Gateway UI

If you are executing the script from the Gateway web interface, after you add the user schema to the script, a blue triangle will appear on the left of `python_secret_demo.py`.

![](/_fern-img/017e27038f8a4a9b642d2251aac51f21b795e883132a40ddef2fd770f93cea99.webp)

> **Info**
>
> When the **Scripts** list is too long for the navigation menu, a scrollbar is displayed. Also, if the script name is very long, an ellipsis is used to reflect there is overflow text.

On the **Execute** tab, you can run the script by filling the `path` and `key_name` without a quote. The response object is the same as executing from the API.

![](/_fern-img/8cfa8a8f18fae0fdbca3e5fe065b6bbdb5d5e1645a10460c3ec71c1a3fe1fef7.webp)

## Configure Vault AppRole authentication

Beginning with the 4.3.0 release, Itential Gateway includes support for HashiCorp Vault AppRole authentication for retrieving secrets to validate requests from clients. This involves enabling `approle` and providing the `role_id` and `secret_id`. The `role_id` is analogous to a username while the `secret_id` is like a password.

> **Info**
>
> **Related reading:**
>
> * [Itential Platform's KV Secrets Engine AppRole](/itential-platform/6/secrets/hashicorp/enable-kv-v2-secrets-engine)
> * [HashiCorp Vault AppRole Authentication](https://developer.hashicorp.com/vault/docs/auth/approle)

#### Create a Vault policy

Create a Vault policy in HashiCorp for the role you are going to create. The example below creates a policy called `"aaapasfpassword only"`. The policy allows login to HashiCorp Vault, and also allows read access to a kv-v2 engine secret called `"aaaPSFPassword"`.

![](/_fern-img/67514f4f9010f1fe952a988626b1e868290b09e14d832985d3f80116db29300b.webp)

#### Enable the HashiCorp AppRole authentication method

Enable the HashiCorp AppRole access control authentication method.

![](/_fern-img/41015533a49f782c873ce272b1f9d188d1bb8e70231819d435e92754f5692862.webp)

#### Create an AppRole connected to the policy

In terminal, create an AppRole connected to the policy.

```bash
vault write auth/approle/role/my-psf-password-role \
policies="aaapsfpassword only" \
secret_id_ttl=10m \
token_ttl=1h \
token_max_ttl=4h
```

#### Get the role\_id for the new AppRole role

Get the `role_id` for the new AppRole role. Copy and paste the `role_id` into the **Vault Role ID** field on the Gateway Vault Configuration form.

```bash
vault read auth/approle/role/my-psf-password-role/role-id

Key        Value
---        -----
role_id    5b8c2892-c9d1-2f6e-669b-fe6ae8ce393f
```

#### Get the secret\_id for the AppRole

Get the `secret_id` for the AppRole. Copy and paste into the **Vault Secret ID** field on the Gateway Vault configuration form.

```bash
vault write -f auth/approle/role/my-psf-password-role/secret-id

Key                   Value
---                   -----
secret_id             6929696d-3078-ac07-3d17-a556c26da23d
secret_id_accessor    268383a3-2345-301f-945e-d42c13a9d8b1
secret_id_ttl         10m
```

#### Select the Vault AppRole Auth checkbox

Select the **Vault AppRole Auth** checkbox on the Gateway Vault configuration form.

#### Modify the Vault Server and Vault Access Token fields

Modify the **Vault Server** and **Vault Access Token** fields to the exact paths.

#### Save your changes

Save your changes. A banner displays to confirm the configuration successfully updated.

![](/_fern-img/f7bfc978ae8e93f44449b3f58fdac18e68c001c22923951d3c2d1e01568ea3f2.webp)

You can return to terminal to observe `Authenticating using Vault AppRole credentials`.

![](/_fern-img/8c40bd498522723785e7e0cfe1337f458a6622f0d65f49e60f328dbae2f2ccf4.webp)

AppRole credentials take precedence over tokens; when AppRole is enabled, the system uses these credentials to connect to the Vault server. If AppRole is not enabled, the system falls back to using token-based authentication.

![](/_fern-img/613ac1ee480ec47c39bcd3fe9d15eaac7fbac8922b283d60d07381a8233b3b2c.webp)![](/_fern-img/f00b1fe8e595d8d06a580cfb5fd1d4fdc054bc91f31a1a0c299a2ecfe163b78b.webp)