Keeper Plugin

Our Keeper Security plugin enables secure loading of secrets from Keeper vaults via the Keeper Secrets Manager SDK.

The plugin uses base64-encoded configuration tokens for programmatic access to your Keeper secrets, making it suitable for both CI/CD and production environments.

Features

• SDK-based authentication - Secure access via base64-encoded Secrets Manager config tokens
• Flexible secret access - Fetch by record UID, title, #field selector, or Keeper notation
• Standard and custom fields - Access any field type including password, login, URL, notes, and custom fields
• Multiple instances - Connect to different Keeper applications or vaults simultaneously
• Built-in secret caching - Avoids redundant API calls within a single resolution pass
• Comprehensive error handling with helpful tips

Installation and setup

In a JS/TS project, you may install the @varlock/keeper-plugin package as a normal dependency. Otherwise you can just load it directly from your .env.schema file, as long as you add a version specifier. See the plugins guide for more instructions on installing plugins.

.env.schema

# 1. Load the plugin
# @plugin(@varlock/keeper-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initKeeper(token=$KSM_CONFIG)
# ---

# 3. Add a config item for the Secrets Manager config token
# @type=keeperSmToken @sensitive
KSM_CONFIG=

Secrets Manager application setup

1. Create a Secrets Manager Application in the Keeper Admin Console

   Navigate to Secrets Manager → Applications → Click Create Application. Give it a descriptive name (e.g., “varlock-prod”).

2. Share a folder with the application

   In your Keeper vault, right-click the folder containing your secrets, select Share Folder, and share it with your Secrets Manager application.

3. Generate a one-time access token

   In the application settings, click Add Device and copy the one-time access token.

4. Initialize and export the config

   Use the KSM CLI to create a config:

   pip install keeper-secrets-manager-cli
   ksm profile init <one-time-token>
   ksm profile export --format json | base64

   Save the config securely

   Store the base64-encoded config token securely. The one-time access token can only be used once to initialize a device.

5. Wire up the token in your config

   .env.schema

   # @plugin(@varlock/keeper-plugin)
   # @initKeeper(token=$KSM_CONFIG)
   # ---
   
   # @type=keeperSmToken @sensitive
   KSM_CONFIG=

6. Set your config token in environments

   Use your CI/CD system or platform’s env var management to securely inject the KSM_CONFIG value.

Multiple instances

If you need to connect to different Keeper applications or vaults, register multiple named instances:

.env.schema

# @plugin(@varlock/keeper-plugin)
# @initKeeper(token=$KSM_PROD, id=prod)
# @initKeeper(token=$KSM_DEV, id=dev)
# ---

# @type=keeperSmToken @sensitive
KSM_PROD=
# @type=keeperSmToken @sensitive
KSM_DEV=

PROD_SECRET=keeper(prod, "XXXXXXXXXXXXXXXXXXXX")
DEV_SECRET=keeper(dev, "XXXXXXXXXXXXXXXXXXXX")

Loading secrets

Once the plugin is installed and initialized, you can start adding config items that load values using the keeper() resolver function.

By record UID

Fetch secrets by record UID. By default, the password field is returned:

.env.schema

# Fetches the "password" field from the record
DB_PASSWORD=keeper("XXXXXXXXXXXXXXXXXXXX")

With a field selector

Use the # syntax to access a specific field:

.env.schema

# Standard fields
DB_USER=keeper("XXXXXXXXXXXXXXXXXXXX#login")
SITE_URL=keeper("XXXXXXXXXXXXXXXXXXXX#url")

# Custom fields by label
API_KEY=keeper("XXXXXXXXXXXXXXXXXXXX#API_KEY")

Or use the named field parameter:

.env.schema

DB_HOST=keeper("XXXXXXXXXXXXXXXXXXXX", field="host")

Using Keeper notation

The plugin supports Keeper’s notation syntax for advanced access patterns:

.env.schema

# Standard field by type
DB_PASS=keeper("XXXX/field/password")

# Login field
DB_USER=keeper("XXXX/field/login")

# Custom field by label
MY_SECRET=keeper("XXXX/custom_field/MySecretLabel")

# By record title instead of UID
API_KEY=keeper("My API Keys/field/password")

With named instances

When using multiple instances, specify which one to use as the first argument:

.env.schema

PROD_SECRET=keeper(prod, "XXXX/field/password")
DEV_SECRET=keeper(dev, "YYYY#password")

Record UIDs vs titles

You can reference records by either their UID or their title. UIDs are more reliable since titles can be changed, but titles are more readable. UIDs are case-sensitive.

---

Reference

Root decorators

@initKeeper()

Initialize a Keeper Secrets Manager plugin instance for accessing secrets.

Key/value args:

• token (required): Base64-encoded Secrets Manager config token. Should be a reference to a config item of type keeperSmToken.
• id (optional): Instance identifier for multiple instances

# @initKeeper(token=$KSM_CONFIG)
# ---
# @type=keeperSmToken @sensitive
KSM_CONFIG=

Data types

keeperSmToken

Represents a base64-encoded configuration token for the Keeper Secrets Manager SDK. Validation ensures the value is a valid base64-encoded JSON string. Note that the type itself is marked as @sensitive, so adding an explicit @sensitive decorator is optional.

# @type=keeperSmToken
KSM_CONFIG=

Resolver functions

keeper()

Fetch a secret field from Keeper Secrets Manager.

Array args:

• instanceId (optional): instance identifier to use when multiple plugin instances are initialized
• reference (required): record UID, title, UID with #field selector, or Keeper notation string

Key/value args:

• field (optional): explicit field type or label to extract from the record

# By record UID (defaults to password field)
DB_PASSWORD=keeper("XXXXXXXXXXXXXXXXXXXX")

# With field selector
DB_USER=keeper("XXXXXXXXXXXXXXXXXXXX#login")

# With named field parameter
DB_HOST=keeper("XXXXXXXXXXXXXXXXXXXX", field="host")

# Using Keeper notation
API_KEY=keeper("XXXX/field/password")
CUSTOM=keeper("XXXX/custom_field/API_KEY")

# With instance ID
PROD_SECRET=keeper(prod, "XXXXXXXXXXXXXXXXXXXX")

---

Troubleshooting

Failed to parse config token

• The KSM_CONFIG value must be a valid base64-encoded JSON string
• Regenerate it using the KSM CLI:

  ksm profile export --format json | base64

Access denied

• Verify the Secrets Manager application has not been revoked
• Check that the shared folder permissions are still active
• The one-time token may have expired before being used — generate a new one

Record not found

• Verify the record UID or title is correct
• Ensure the record is in a folder shared with the Secrets Manager application
• Record UIDs are case-sensitive

Field not found in record

• Check available field types: login, password, url, oneTimeCode, note
• Custom fields use the label: keeper("uid/custom_field/My Label")
• Use the # syntax for quick field access: keeper("uid#login")

Config token issues

• One-time access tokens can only be used once to initialize a device
• If you need a new config, create a new device in the application settings
• Config tokens contain encrypted keys — do not modify them manually

Resources

• Keeper Security
• Keeper Secrets Manager
• JavaScript SDK Documentation
• KSM CLI Documentation