From 1728f03cc2fef287c1ab32de011f75e4bf36ec07 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Mon, 23 Feb 2026 19:06:23 +0300 Subject: [PATCH 1/4] [#6861] update vault config info --- docs/configuration/secret-files.md | 42 +++++++++---------- .../azure-key-vault-external-secrets.md | 4 +- .../hashicorp-vault-external-secrets.md | 4 +- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/configuration/secret-files.md b/docs/configuration/secret-files.md index 1eba28327..9f9396fc2 100644 --- a/docs/configuration/secret-files.md +++ b/docs/configuration/secret-files.md @@ -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"} } } } @@ -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: -
FieldDescription
pathAbsolute path to the file containing the secret value
scopeArray of resource references that are allowed to access this secret. Entries can be "ResourceType/id" (specific instance, e.g. "Client/my-client") or "ResourceType" (any instance of that type, e.g. "Client")
+
FieldDescription
pathAbsolute path to the file containing the secret value
scopeObject identifying the resource allowed to access this secret. Use resource_type and id to restrict to a specific instance (e.g. {"resource_type": "Client", "id": "my-client"}), or resource_type alone to allow any instance of that type (e.g. {"resource_type": "TokenIntrospector"})
## Extension pattern @@ -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 | diff --git a/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md b/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md index 8cb2a40bb..7d707c071 100644 --- a/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md +++ b/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md @@ -188,7 +188,7 @@ data: "secret": { "client-secret": { "path": "/run/azure-secrets/client-secret", - "scope": ["Client/basic"] + "scope": {"resource_type": "Client", "id": "basic"} } } } @@ -197,7 +197,7 @@ data: Each entry under `"secret"` maps a secret name to: -
FieldDescription
pathAbsolute path to the file containing the secret value
scopeArray of resource references allowed to access this secret. Entries can be "ResourceType/id" (specific instance, e.g. "Client/basic") or "ResourceType" (any instance of that type, e.g. "Client")
+
FieldDescription
pathAbsolute path to the file containing the secret value
scopeObject identifying the resource allowed to access this secret. Use resource_type and id to restrict to a specific instance (e.g. {"resource_type": "Client", "id": "basic"}), or resource_type alone to allow any instance of that type (e.g. {"resource_type": "Client"})
## Step 8. Deploy Aidbox diff --git a/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md b/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md index d2d743ccd..c4a4c9e45 100644 --- a/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md +++ b/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md @@ -167,7 +167,7 @@ data: "secret": { "client-secret": { "path": "/run/vault-secrets/client-secret", - "scope": ["Client/basic"] + "scope": {"resource_type": "Client", "id": "basic"} } } } @@ -176,7 +176,7 @@ data: Each entry under `"secret"` maps a secret name to: -
FieldDescription
pathAbsolute path to the file containing the secret value
scopeArray of resource references allowed to access this secret. Entries can be "ResourceType/id" (specific instance, e.g. "Client/basic") or "ResourceType" (any instance of that type, e.g. "Client")
+
FieldDescription
pathAbsolute path to the file containing the secret value
scopeObject identifying the resource allowed to access this secret. Use resource_type and id to restrict to a specific instance (e.g. {"resource_type": "Client", "id": "basic"}), or resource_type alone to allow any instance of that type (e.g. {"resource_type": "Client"})
## Step 7. Deploy Aidbox From 39a9cbee15b7a704115d4fce65bf0320e4ca4615 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Tue, 24 Feb 2026 14:53:56 +0300 Subject: [PATCH 2/4] [#6861] fix variable name Co-authored-by: Ivan Bagrov --- docs/configuration/secret-files.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration/secret-files.md b/docs/configuration/secret-files.md index 9f9396fc2..b3054ddb3 100644 --- a/docs/configuration/secret-files.md +++ b/docs/configuration/secret-files.md @@ -29,9 +29,9 @@ 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. From 5e765e590c30fcb1eda7c57fe2f47b3f1f2ba5f9 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Tue, 24 Feb 2026 14:57:02 +0300 Subject: [PATCH 3/4] [#6861] fix warning Co-authored-by: Ivan Bagrov --- docs/configuration/secret-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/secret-files.md b/docs/configuration/secret-files.md index b3054ddb3..d49ca7b64 100644 --- a/docs/configuration/secret-files.md +++ b/docs/configuration/secret-files.md @@ -36,7 +36,7 @@ flowchart LR 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 From c4e638724882d365002dcc7343b09312b4172f0e Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Tue, 24 Feb 2026 15:02:13 +0300 Subject: [PATCH 4/4] [#6861] add info about variable to all settings Co-authored-by: Ivan Bagrov --- docs/reference/all-settings.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/reference/all-settings.md b/docs/reference/all-settings.md index 06ae211a9..645654c1e 100644 --- a/docs/reference/all-settings.md +++ b/docs/reference/all-settings.md @@ -900,6 +900,16 @@ Activates debugging features for access policy development, including the `_debu
Details
IDsecurity.dev-mode
TypeBool
Recommended valuetrue
Default valuefalse
Environment variableBOX_SECURITY_DEV_MODE
Deprecated environment variablesAIDBOX_DEV_MODE
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadtrue — setting can be changed at runtime
+### Vault config + +```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
IDvault-config
TypeString
Default value(no default — feature disabled)
Environment variableBOX_VAULT_CONFIG
Available from2602
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ ## Modules Modules settings