Keeper Secrets Manager Provider

The Keeper Secrets Manager provider reads and writes records available to a Keeper Secrets Manager application. Monosecret links Keeper’s official Rust SDK, so no separate ksm executable is required.

At a glance


Provider	`keeper` (0.2+)
URI	`keeper://FOLDER_UID[?config_file=PATH]`
Access	Read, write, and delete
Best for	Machine and CI/CD secrets managed in Keeper
Authentication	KSM configuration, or a one-time token while creating a file configuration
Availability	Monosecret 0.2+; requires the `keeper` build feature
Default storage	Login record `monosecret/{project}/{profile}/{key}`, field `password`

Quick start

# Store a secret as a Keeper record
$ monosecret set DATABASE_URL \
    --provider "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

# Read it back
$ monosecret get DATABASE_URL \
    --provider "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

# Resolve the profile and run a command
$ monosecret run \
    --provider "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json" \
    -- npm start

The folder must be shared with the KSM application and grant edit permission for writes.

Setup

Prerequisites

Monosecret 0.2+ built with the keeper feature
A Keeper Secrets Manager application
A shared folder available to that application
A bound KSM client configuration, or a one-time access token for initial binding

Keeper’s Rust SDK is embedded in Monosecret. Keeper Commander and the ksm CLI are useful for application setup, but neither is needed when Monosecret runs.

Authentication with KSM_CONFIG

Set KSM_CONFIG to the JSON or Base64 KSM client configuration:

$ export KSM_CONFIG="$KEEPER_CLIENT_CONFIG"

$ monosecret check --provider "keeper://SHARED_FOLDER_UID"

The configuration contains private client keys. Treat the whole value as a secret.

Monosecret 0.2+ also declares config as a provider credential, so the configuration can be loaded from another provider instead of the environment:

[providers]
bootstrap = "keyring://"

[providers.keeper]
uri = "keeper://SHARED_FOLDER_UID"
credentials = { config = "bootstrap" }

[profiles.production]
DATABASE_URL = { description = "Database URL", providers = ["keeper"] }

When no explicit config credential is supplied, the provider falls back to KSM_CONFIG.

Authentication with a configuration file

Use config_file to read and update a Keeper SDK configuration file:

[providers]
keeper = "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

Relative paths are resolved from the directory containing monosecret.toml. Without config_file, the SDK honors KSM_CONFIG_FILE, then uses its client-config.json default.

Bind with a one-time token

The token provider credential, or KSM_TOKEN fallback, can bind a new client. Pair it with file storage so the SDK can persist the generated client keys for later Monosecret processes:

$ export KSM_TOKEN="US:ONE_TIME_TOKEN"

$ monosecret check \
  --provider "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

$ unset KSM_TOKEN

A Keeper one-time token cannot be reused. Remove it after the first successful request and retain the generated configuration file securely.

Provider credentials

Credential	Environment fallback	Available since
`config`	`KSM_CONFIG`	0.2+
`token`	`KSM_TOKEN`	0.2+

See the complete provider credential reference for all supported providers and environment fallbacks.

Configuration

URI format

keeper://FOLDER_UID[?config_file=PATH]

FOLDER_UID is required. It is the case-sensitive UID of a shared folder or one of its subfolders. New convention records are created there.
config_file is optional. It selects a Keeper SDK client configuration file.

URI examples

keeper://SHARED_FOLDER_UID
keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json

Project configuration

[providers]
keeper_prod = "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

[profiles.production]
DATABASE_URL = { description = "Database URL", providers = ["keeper_prod"] }
API_KEY = { description = "API key", providers = ["keeper_prod"] }

Storage model

Convention secrets use Keeper login records:

record title: monosecret/{project}/{profile}/{key}
field:        password

For example, project storefront, profile production, and key DATABASE_URL map to record title monosecret/storefront/production/DATABASE_URL.

Monosecret fetches the application’s available records once for a batch of secret requests, then resolves all requested titles and fields locally. A duplicate convention title is rejected as ambiguous.

Use existing records

A secret’s ref can select an existing Keeper record by exact title or record UID. field selects a standard field type/label or custom field label and defaults to password:

[providers]
keeper = "keeper://SHARED_FOLDER_UID?config_file=.keeper/client-config.json"

[profiles.production]
DATABASE_URL = {
  description = "Database URL",
  providers = ["keeper"],
  ref = { item = "KEEPER_RECORD_UID", field = "Database URL" }
}

Reads and writes target the existing field in place. A write through ref never creates a missing record or field; create it in Keeper first. Use a record UID when duplicate titles exist.

CI/CD

Store the bound KSM configuration as one protected CI secret:

$ export KSM_CONFIG="$CI_KEEPER_CONFIG"

$ monosecret run --provider "keeper://SHARED_FOLDER_UID" -- ./deploy

The KSM application should receive access only to the folders the job needs. Grant edit permission only when the job must run set, refresh a Keeper-backed cache, or otherwise write records.

Security considerations

The official SDK encrypts and decrypts Keeper records inside the Monosecret process. Secret values and KSM credentials are not placed in child-process arguments. A config_file contains long-lived private client keys and must be protected like any other secret; prefer KSM_CONFIG or a provider credential when persistent local files are undesirable.