External value references

External references supply both secret and non-secret bsh settings. A reference can provide a target hostname, port, duration, boolean, username, or credential. Non-secret references require bsh version 0.2.0 or later.

Syntax

A reference uses scheme://location with optional query parameters. The separator is ://, for example env://DATABASE_HOST.

Recognized references resolve when the command loads its configuration, before conversion to the expected type. probe and doctor also resolve references, so either command can contact an external store.

A fetched value is not resolved again. For example, a store value of env://ANOTHER_VARIABLE remains that text. literal:// returns its payload unchanged and is useful when a value must begin with a recognized scheme. Ordinary non-secret URLs, such as https://bridge.example.com, remain literal values.

Placement

References are accepted in flags, BSH_* environment variables, YAML params, and structured YAML fields. The following environment values obtain both connection settings and a password from one JSON object:

export BSH_TARGET_HOST='aws-sm://prod/database?key=host&region=us-east-1'
export BSH_TARGET_PORT='aws-sm://prod/database?key=port&region=us-east-1'
export BSH_TRANSPORT_USER='aws-sm://prod/database?key=username&region=us-east-1'
export BSH_TRANSPORT_PASSWORD='aws-sm://prod/database?key=password&region=us-east-1'

A typed flag can also contain a reference:

bsh probe ssh --method ephemeral-key --target-port 'env://SSH_PORT'

Shell quotes preserve &, ?, and other shell-significant characters in a reference. Quotes are not part of the value in a permission’s variable mapping.

JSON fields and typed values

?key=name selects a top-level field from a JSON object. It is not a JSONPath expression. For example, this object supplies host, port, and boolean values:

{
  "host": "db.example.com",
  "port": 5432,
  "sudo": false
}

The selected number or boolean is converted to text, then parsed as the destination setting’s type. A port must resolve to an integer. A duration must resolve to an accepted duration value. A list must resolve to a comma-separated or whitespace-separated string. A JSON array is not automatically converted to a bsh list.

Without key, environment, file, AWS, Azure, and Google references return the whole value. Vault has separate single-field behavior described below.

Environment variables and files

env://NAME reads NAME from the command’s process environment. The broker must receive that variable. A variable in an administrator’s interactive shell does not automatically reach a broker service or container.

file:///absolute/path reads a local file as text and removes trailing line endings. The broker’s operating-system user must be able to read the file.

Secret settings also support an _FILE suffix. For example:

BSH_TRANSPORT_PASSWORD_FILE=/etc/britive/secrets/database-password

The _FILE value is a file path, not a file:// URL. This shortcut applies to credentials. Non-secret values use file:// references. A reference can also supply a path for a setting that expects one, but a fetched file path does not become file content unless that setting reads the file.

AWS Secrets Manager

aws-sm://secret-id?key=field&region=us-east-1&version=AWSCURRENT

The location is the secret name or ARN. region can come from the query or the AWS runtime configuration, such as AWS_REGION. version selects a version stage or version ID. Without a version, the current secret version is used.

Authentication uses the AWS default credential chain, including workload credentials available to the broker. That identity needs permission to read the secret and, when applicable, decrypt it with its KMS key. The value must be a string secret. Binary secrets are not supported.

Azure Key Vault

azure-kv://vault-name/secret-name?key=field&version=version-id

version is optional. Without it, the latest version is read.

Supported identities include App Service managed identity, AKS workload identity, a client secret, and VM managed identity. Workload identity uses AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_FEDERATED_TOKEN_FILE. Client-secret authentication uses AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET. The broker identity needs access to read the secret.

Google Secret Manager

gcp-sm://project-id/secret-name?key=field&version=latest

version defaults to latest. Authentication uses the workload’s metadata service or a service-account key JSON file named by GOOGLE_APPLICATION_CREDENTIALS. The identity needs permission to access the secret version. Other Application Default Credentials file formats are not supported by this resolver.

HashiCorp Vault

vault://mount/path/to/secret?key=field&version=2

The resolver uses Vault KV v2. version selects a secret version. The connection requires VAULT_ADDR and a token in VAULT_TOKEN or ~/.vault-token. VAULT_NAMESPACE selects a namespace when required.

With key, the resolver returns that field. Without key, a secret with one field returns that field’s value. A secret with multiple fields requires key.

Credential handling

Credential settings include BSH_TRANSPORT_KEY, BSH_TRANSPORT_PASSWORD, BSH_BRIDGE_BROKER_API_TOKEN, BSH_BRIDGE_AUTH_PASSWORD, BSH_KUBE_TOKEN, and BSH_TARGET_BEARER_TOKEN.

Literal credentials and literal:// credential values are rejected on the command line. A reference such as --transport-password 'env://DATABASE_PASSWORD' is accepted. An unrecognized reference scheme in a credential is an error.

Missing variables, unreadable files, denied store access, missing JSON fields, and invalid typed results fail configuration loading. The troubleshooting guide describes checks to run from the broker’s execution environment.