Skip to content
This repository was archived by the owner on Mar 17, 2026. It is now read-only.

6861 vault config #123

Merged
Panthevm merged 4 commits into from
Feb 24, 2026
Merged

6861 vault config #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1728f03
[#6861] update vault config info
andreyorst Feb 23, 2026
39a9cbe
[#6861] fix variable name
andreyorst Feb 24, 2026
5e765e5
[#6861] fix warning
andreyorst Feb 24, 2026
c4e6387
[#6861] add info about variable to all settings
andreyorst Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions docs/configuration/secret-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,14 @@ flowchart LR

## Configuration

| Environment variable | Description | Default |
| --- | --- | --- |
| `AIDBOX_VAULT_CONFIG` | Path to the vault config JSON file that maps named secrets to file paths and resource scopes. | empty (feature disabled) |
| Environment variable | Description | Default |
|----------------------|-----------------------------------------------------------------------------------------------|--------------------------|
| `BOX_VAULT_CONFIG` | Path to the vault config JSON file that maps named secrets to file paths and resource scopes. | empty (feature disabled) |

See [Aidbox Settings Reference](../reference/all-settings.md) for the full list of environment variables.

{% hint style="warning" %}
This setting requires a restart to take effect. The config file itself is re-read automatically when modified — no restart needed for config changes.
This setting requires a restart to take effect. The config file is loaded once — restart is required after changing the vault config.
{% endhint %}

### Vault config file format
Expand All @@ -47,15 +47,15 @@ This setting requires a restart to take effect. The config file itself is re-rea
"secret": {
"client-secret": {
"path": "/run/secrets/client-secret",
"scope": ["Client/my-client"]
"scope": {"resource_type": "Client", "id": "my-client"}
},
"kafka-jaas": {
"path": "/run/secrets/kafka-jaas",
"scope": ["AidboxTopicDestination/kafka-dest-1"]
"scope": {"resource_type": "AidboxTopicDestination", "id": "kafka-dest-1"}
},
"jwt-key": {
"path": "/run/secrets/jwt-key",
"scope": ["TokenIntrospector"]
"scope": {"resource_type": "TokenIntrospector"}
}
}
}
Expand All @@ -64,7 +64,7 @@ This setting requires a restart to take effect. The config file itself is re-rea

Each entry under `"secret"` maps a secret name to:

<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references that are allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/my-client"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "my-client"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "TokenIntrospector"}</code>)</td></tr></tbody></table>

## Extension pattern

Expand Down Expand Up @@ -135,25 +135,25 @@ This works with any mechanism that updates files in place — Kubernetes Secrets

The following fields support secret references via the extension pattern:

| Resource | Field | Description |
| --- | --- | --- |
| **Client** | `secret` | Client secret for authentication |
| **IdentityProvider** | `client.secret` | Client secret for symmetric authentication |
| **IdentityProvider** | `client.private-key` | Private key for asymmetric authentication |
| **IdentityProvider** | `client.certificate` | Certificate for asymmetric authentication |
| **TokenIntrospector** | `jwt.secret` | Shared secret key for JWT verification |
| **TokenIntrospector** | `jwt.keys.k` | Symmetric key for validation |
| **TokenIntrospector** | `introspection_endpoint.authorization` | Authorization header value |
| **AidboxTopicDestination** | `parameter.saslJaasConfig` | SASL JAAS configuration for Kafka authentication |
| **AidboxTopicDestination** | `parameter.sslKeystoreKey` | SSL keystore private key for Kafka connection |
| Resource | Field | Description |
|----------------------------|----------------------------------------|--------------------------------------------------|
| **Client** | `secret` | Client secret for authentication |
| **IdentityProvider** | `client.secret` | Client secret for symmetric authentication |
| **IdentityProvider** | `client.private-key` | Private key for asymmetric authentication |
| **IdentityProvider** | `client.certificate` | Certificate for asymmetric authentication |
| **TokenIntrospector** | `jwt.secret` | Shared secret key for JWT verification |
| **TokenIntrospector** | `jwt.keys.k` | Symmetric key for validation |
| **TokenIntrospector** | `introspection_endpoint.authorization` | Authorization header value |
| **AidboxTopicDestination** | `parameter.saslJaasConfig` | SASL JAAS configuration for Kafka authentication |
| **AidboxTopicDestination** | `parameter.sslKeystoreKey` | SSL keystore private key for Kafka connection |

## Delivering secrets to the filesystem

The external secrets feature is agnostic to how files are placed on the filesystem. Common approaches:

| Method | Description |
| --- | --- |
| [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) | Mounted as volumes in pods |
| [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/) | Mounts secrets from external vaults with automatic rotation. See the [Azure Key Vault](../tutorials/other-tutorials/azure-key-vault-external-secrets.md) and [HashiCorp Vault](../tutorials/other-tutorials/hashicorp-vault-external-secrets.md) tutorials |
| [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) | Available at `/run/secrets/` in swarm mode |
| Docker volumes | Bind-mount a host directory containing secret files |
| Method | Description |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) | Mounted as volumes in pods |
| [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/) | Mounts secrets from external vaults with automatic rotation. See the [Azure Key Vault](../tutorials/other-tutorials/azure-key-vault-external-secrets.md) and [HashiCorp Vault](../tutorials/other-tutorials/hashicorp-vault-external-secrets.md) tutorials |
| [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) | Available at `/run/secrets/` in swarm mode |
| Docker volumes | Bind-mount a host directory containing secret files |
10 changes: 10 additions & 0 deletions docs/reference/all-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -900,6 +900,16 @@ Activates debugging features for access policy development, including the `_debu

<details><summary>Details</summary><table data-header-hidden="true"><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td>ID</td><td><code>security.dev-mode</code></td></tr><tr><td>Type</td><td>Bool</td></tr><tr><td>Recommended value</td><td><code>true</code></td></tr><tr><td>Default value</td><td><code>false</code></td></tr><tr><td>Environment variable</td><td><code>BOX_SECURITY_DEV_MODE</code></td></tr><tr><td>Deprecated environment variables</td><td><code>AIDBOX_DEV_MODE</code></td></tr><tr><td>Sensitive</td><td><code>false</code> — value will be visible in plaintext in Admin UI</td></tr><tr><td>Set via</td><td>Admin UI → Settings<br />Environment variables</td></tr><tr><td>Hot reload</td><td><code>true</code> — setting can be changed at runtime</td></tr></tbody></table></details>

### Vault config<a href="#vault-config" id="vault-config"></a>

```yaml
BOX_VAULT_CONFIG: "/path/to/vault-config.json"
```

Path to the vault config JSON file that maps named secrets to file paths and resource scopes. When set, Aidbox can reference secrets stored as files on the filesystem instead of keeping them in the database. See [External Secrets](../configuration/secret-files.md) for details.

<details><summary>Details</summary><table data-header-hidden="true"><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td>ID</td><td><code>vault-config</code></td></tr><tr><td>Type</td><td>String</td></tr><tr><td>Default value</td><td>(no default — feature disabled)</td></tr><tr><td>Environment variable</td><td><code>BOX_VAULT_CONFIG</code></td></tr><tr><td>Available from</td><td><code>2602</code></td></tr><tr><td>Sensitive</td><td><code>false</code> — value will be visible in plaintext in Admin UI</td></tr><tr><td>Set via</td><td>Environment variables</td></tr><tr><td>Hot reload</td><td><code>false</code> — setting requires system restart</td></tr></tbody></table></details>

## Modules

Modules settings
Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ data:
"secret": {
"client-secret": {
"path": "/run/azure-secrets/client-secret",
"scope": ["Client/basic"]
"scope": {"resource_type": "Client", "id": "basic"}
}
}
}
Expand All @@ -197,7 +197,7 @@ data:

Each entry under `"secret"` maps a secret name to:

<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/basic"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "basic"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "Client"}</code>)</td></tr></tbody></table>

## Step 8. Deploy Aidbox

Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ data:
"secret": {
"client-secret": {
"path": "/run/vault-secrets/client-secret",
"scope": ["Client/basic"]
"scope": {"resource_type": "Client", "id": "basic"}
}
}
}
Expand All @@ -176,7 +176,7 @@ data:

Each entry under `"secret"` maps a secret name to:

<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/basic"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "basic"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "Client"}</code>)</td></tr></tbody></table>

## Step 7. Deploy Aidbox

Expand Down