> 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.

# Configure a secret provider

> Register HashiCorp Vault or CyberArk CCP as a secret provider in Itential Gateway.

Gateway 5.5+

A secret provider stores the connection and authentication settings for your external secrets manager. After you register a provider, you can create secret aliases that point to secrets within it.

For providers not covered here, including Vault KV v1 and IAM-authenticated Vault, see [Configure a custom plugin provider](./configure-custom-plugin-provider).

## Before you begin

* Itential Gateway installed and running
* Network access from the gateway server to your secrets manager
* Authentication credentials stored as files on the gateway server

Never pass credentials as command-line values. Store tokens, certificate files, and private keys on disk and reference them by file path.

All communications between Gateway and your secrets manager use TLS 1.3+.

## HashiCorp Vault, token authentication

Use token authentication for Vault deployments with long-lived tokens. For short-lived tokens, use AppRole authentication instead.

```bash
iagctl create secret-provider <name> \
  --type vault \
  --auth-method token \
  --url https://vault.example.com \
  --secrets-endpoint secret \
  --token /etc/gateway/vault_token
```

| Flag                 | Required | Description                                  |
| -------------------- | -------- | -------------------------------------------- |
| `--url`              | Yes      | Vault server URL                             |
| `--secrets-endpoint` | Yes      | KV v2 mount path, for example `secret`       |
| `--token`            | Yes      | Path to the token file on the gateway server |

If your token expires, secret retrieval fails until you update the token file. For short-lived tokens, use AppRole authentication.

## HashiCorp Vault, AppRole authentication

AppRole authentication uses a role ID and a secret ID stored in separate files. Gateway handles token refresh automatically.

Unlike the secret ID, the role ID is passed as a literal value with `--role-id`, not a file path. Role IDs are not treated as sensitive by Vault, but the secret ID must always be supplied as a file using `--secret-id-file`.

```bash
iagctl create secret-provider <name> \
  --type vault \
  --auth-method approle \
  --url https://vault.example.com \
  --secrets-endpoint secret \
  --role-id <role-id-uuid> \
  --secret-id-file /etc/gateway/vault_secret_id
```

| Flag                 | Required | Description                                      |
| -------------------- | -------- | ------------------------------------------------ |
| `--url`              | Yes      | Vault server URL                                 |
| `--secrets-endpoint` | Yes      | KV v2 mount path                                 |
| `--role-id`          | Yes      | AppRole role ID value                            |
| `--secret-id-file`   | Yes      | Path to the secret ID file on the gateway server |

When Vault rotates your secret ID, update the file on disk. Gateway picks up the new value automatically on its next authentication cycle.

## CyberArk Central Credential Provider (CCP)

CyberArk CCP uses mutual TLS. Store the client certificate and private key as files on the gateway server.

```bash
iagctl create secret-provider <name> \
  --type cyberark \
  --url https://cyberark.example.com \
  --app-id <application-id> \
  --cert-file /etc/gateway/cyberark.crt \
  --key-file /etc/gateway/cyberark.key
```

| Flag                    | Required | Description                                                                  |
| ----------------------- | -------- | ---------------------------------------------------------------------------- |
| `--url`                 | Yes      | CyberArk CCP server URL                                                      |
| `--app-id`              | Yes      | CyberArk application ID for this Gateway instance                            |
| `--cert-file`           | Yes      | Path to the client certificate on the gateway server                         |
| `--key-file`            | Yes      | Path to the private key on the gateway server                                |
| `--ca`                  | No       | Path to a CA certificate file, if your CyberArk CCP server uses a private CA |
| `--allow-invalid-certs` | No       | Skip TLS certificate verification. Use only in development environments.     |

## Verify your provider

```bash
iagctl get secret-providers
```

```
NAME            TYPE      URL
my-vault        vault     https://vault.example.com
my-cyberark     cyberark  https://cyberark.example.com
```

## Next steps

* [Create secret aliases](./manage-secret-aliases)