External Secrets

Aidbox can reference secrets stored as files on the filesystem instead of keeping them in the database. A JSON vault config file maps named secrets to file paths and controls which resources can access each secret. The actual values are never persisted or returned through the API.

How it works

flowchart LR
    File(/run/secrets/client-secret):::blue2 -->|read at runtime| Aidbox(Aidbox):::violet2
    Config(vault-config.json):::blue2 -->|maps name → path + scope| Aidbox
    Aidbox -->|stores reference name| DB(_secret extension):::neutral2

1. 1.
   A secret value is placed as a file on the filesystem (via Kubernetes Secrets, CSI Driver, Docker volumes, or any other mechanism)
2. 2.
   A vault config JSON file maps named secrets to file paths and declares which resources may access them
3. 3.
   A resource field uses the FHIR data-absent-reason / secret-reference extension pattern to reference a named secret
4. 4.
   At runtime, Aidbox looks up the secret name in the vault config, verifies the requesting resource is in scope, and reads the file
5. 5.
   Reading the resource back returns the extension with the secret name, never the secret value

Configuration

See Aidbox Settings Reference for the full list of environment variables.

Vault config file format

{
  "secret": {
    "client-secret": {
      "path": "/run/secrets/client-secret",
      "scope": ["Client/my-client"]
    },
    "kafka-jaas": {
      "path": "/run/secrets/kafka-jaas",
      "scope": ["AidboxTopicDestination/kafka-dest-1"]
    },
    "jwt-key": {
      "path": "/run/secrets/jwt-key",
      "scope": ["TokenIntrospector"]
    }
  }
}

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

Extension pattern

The resource uses FHIR primitive extensions on the secret field. The extension element carries two entries:

• data-absent-reason with value masked — indicates the field value is intentionally absent
• secret-reference with the secret name from the vault config — tells Aidbox which secret to resolve at runtime

Example: Client secret

{
  "resourceType": "Client",
  "id": "my-client",
  "_secret": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
        "valueCode": "masked"
      },
      {
        "url": "http://health-samurai.io/fhir/secret-reference",
        "valueString": "client-secret"
      }
    ]
  },
  "grant_types": ["client_credentials", "basic"]
}

Reading the Client back returns the extension, not the resolved value:

{
  "resourceType": "Client",
  "id": "my-client",
  "_secret": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
        "valueCode": "masked"
      },
      {
        "url": "http://health-samurai.io/fhir/secret-reference",
        "valueString": "client-secret"
      }
    ]
  },
  "grant_types": ["client_credentials", "basic"]
}

Scope enforcement

Aidbox verifies that the resource requesting a secret is listed in the secret's scope array. If the requesting resource is not in scope, Aidbox returns an error.

Secret rotation

Aidbox caches file contents with a short TTL and validates against file modification time. Updated files take effect automatically — no restart required.

This works with any mechanism that updates files in place — Kubernetes Secrets, CSI drivers, configuration management tools, or manual updates.

Supported resources

The following fields support secret references via the extension pattern:

Delivering secrets to the filesystem

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