Puppet | PS

Overview

The BeyondTrust Password Safe Puppet module (beyondtrust-passwordsafe) integrates BeyondTrust Password Safe with Puppet, enabling Puppet-managed nodes to securely retrieve secrets and managed account credentials at catalog application time, directly on the agent.

The module exposes two Deferred Puppet functions backed by the btps_client Ruby gem:

Both functions return a Sensitive[String] value. Puppet automatically redacts Sensitive values from logs, reports, and catalog diffs, ensuring secrets are never exposed in plain text.

Because the functions run as Deferred, secret resolution happens on the agent node during catalog application. Secrets are never transmitted to or stored on the Puppet server.

Prerequisites

ℹ️

The btps_client gem must be installed in Puppet's own gem environment (that is, using puppet_gem provider), not in the system Ruby.

Supported Platforms

Key Features

• Agent-side secret retrieval : Deferred functions resolve secrets on the agent node, never on the Puppet server. Sensitive values never traverse the Puppet infrastructure.
• Automatic secret redaction : All return values are typed as Sensitive[String]. Puppet automatically redacts these values from logs, reports, and file diffs.
• Secrets Safe support : Retrieve Credential, Text, and File-type secrets stored in BeyondTrust Secrets Safe using a simple slash-delimited path identifier.
• Managed Account support : Retrieve managed account credentials using the full Password Safe checkout → retrieve → checkin lifecycle. Checkin is guaranteed even on failure.
• Flexible credential configuration : Connection parameters can be supplied inline in the Puppet manifest, via Sensitive[String] wrappers, or via BTPS_* environment variables on the agent.
• TLS verification : SSL certificate verification is enabled by default, enforcing secure communication with the Password Safe API.
• Broad OS support : Tested on major Linux distributions, Solaris, and Windows platforms.
• Puppet 7 and 8 compatible : Supports current Puppet enterprise and open-source releases.

API Reference

passwordsafe::get_secret

Retrieves a secret from BeyondTrust Secrets Safe using a slash-delimited path identifier. The last path segment is the secret title; everything before it is the folder path.

'folder/path/title'
 └──────────┘ └───┘
  folder path  title

Signature

passwordsafe::get_secret(
  String $identifier,
  Optional[Struct[{
    Optional['host']          => String,
    Optional['base_path']     => String,
    Optional['client_id']     => String,
    Optional['client_secret'] => Variant[String, Sensitive[String]],
    Optional['verify_ssl']    => Boolean,
  }]] $options = {}
) >> Sensitive[String]

Input Parameters

**Required unless the corresponding BTPS_ environment variable is set on the agent.

Output

The function raises Puppet::Error if:

• host, client_id, or client_secret cannot be resolved from either the options hash or environment variables.
• The Password Safe API returns an error response.

passwordsafe::get_managed_account

Retrieves a managed account credential from BeyondTrust Password Safe using the checkout → retrieve → checkin workflow. The identifier must follow the 'system_name/account_name' format with exactly one slash. Nested paths are not supported.

'system-name/account-name'
 └──────────┘ └───────────┘
 system name  account name

The checkout is always checked in, even when retrieval fails.

Signature

passwordsafe::get_managed_account(
  String $identifier,
  Optional[Struct[{
    Optional['host']             => String,
    Optional['base_path']        => String,
    Optional['client_id']        => String,
    Optional['client_secret']    => Variant[String, Sensitive[String]],
    Optional['duration_minutes'] => Integer,
    Optional['verify_ssl']       => Boolean,
  }]] $options = {}
) >> Sensitive[String]

Input Parameters

** Required unless the corresponding BTPS_* environment variable is set on the agent.

Output

The function raises Puppet::Error if:

• host, client_id, or client_secret cannot be resolved from either the options hash or environment variables.
• The identifier contains more or fewer than exactly one slash.
• The Password Safe API returns an error response during checkout or retrieval.

Connection Parameters

Each connection parameter in the options hash is optional. When a key is absent or empty, the function falls back to the corresponding BTPS_* environment variable set on the agent node.

host, client_id, and client_secret are always required. The function raises Puppet::Error if any of the three remains unresolved after checking both the options hash and the environment variable.

client_secret accepts either a plain String or a Sensitive[String]; the value is unwrapped automatically before being passed to the API.

Setup Instructions

Step 1: Install the Module

Install the module from the Puppet Forge on your Puppet server:

puppet module install beyondtrust-passwordsafe

Or declare it in your Puppetfile for use with r10k or Code Manager:

mod 'beyondtrust-passwordsafe', '0.1.0'

Step 2: Install the Ruby Gem on Agents

The btps_client gem must be installed in Puppet's gem environment on every agent node that will use the module functions. Add the following resource to a base profile or role that applies to all relevant nodes:

package { 'btps_client':
  ensure   => present,
  provider => 'puppet_gem',
}

Important: Using provider => 'puppet_gem' installs the gem into Puppet's own gem environment. Do not use the gem provider (system Ruby), as Puppet's Deferred functions use Puppet's Ruby runtime.

Step 3: Configure Connection Parameters

Choose one of the two supported approaches for supplying connection parameters:

$db_password = Deferred('passwordsafe::get_secret', [
  'production/myapp/db-password',
  {
    host          => 'bt.example.com:443',
    base_path     => 'BeyondTrust/api/public/v3',
    client_id     => 'my-oauth-client-id',
    client_secret => Sensitive('my-oauth-client-secret'),
    verify_ssl    => true,
  }
])

BTPS_HOST=bt.example.com:443
BTPS_BASE_PATH=BeyondTrust/api/public/v3
BTPS_CLIENT_ID=my-oauth-client-id
BTPS_CLIENT_SECRET=my-oauth-client-secret
BTPS_VERIFY_SSL=true
BTPS_DURATION_MIN=5

$db_password = Deferred('passwordsafe::get_secret', ['production/myapp/db-password'])

Usage Examples

# Retrieve a database password from Secrets Safe
$db_password = Deferred('passwordsafe::get_secret', [
  'production/postgres/password',
  {
    host          => 'bt.example.com:443',
    client_id     => 'my-client-id',
    client_secret => Sensitive('my-client-secret'),
  }
])

# Write the secret to a configuration file
file { '/etc/myapp/db.conf':
  content   => Deferred('passwordsafe::get_secret', ['production/postgres/db-credential']),
  show_diff => false,
  mode      => '0600',
  owner     => 'myapp',
  group     => 'myapp',
}

# Retrieve a service account password using managed account checkout
$svc_password = Deferred('passwordsafe::get_managed_account', [
  'prod-server/svc_account',
  {
    host             => 'bt.example.com:443',
    client_id        => 'my-client-id',
    client_secret    => Sensitive('my-client-secret'),
    duration_minutes => 10,
  }
])

# Write it to a configuration file
file { '/etc/myapp/svc.conf':
  content   => Deferred('passwordsafe::get_managed_account', ['prod-server/deploy']),
  show_diff => false,
  mode      => '0600',
}

class myapp (
  Sensitive[String] $db_password = Deferred('passwordsafe::get_secret',
    ['production/myapp/db-password']),
) {
  file { '/etc/myapp/database.conf':
    content   => epp('myapp/database.conf.epp', { password => $db_password }),
    show_diff => false,
  }
}

$db_password  = Deferred('passwordsafe::get_secret',          ['production/postgres/password'])
$svc_password = Deferred('passwordsafe::get_managed_account', ['prod-server/svc_account'])

Troubleshooting

Limitations

• Tested on Puppet 7.x and 8.x. Puppet versions earlier than 7.24 and 9.x or later are not supported.
• The btps_client gem must be installed in Puppet's gem environment on each agent node using the puppet_gem provider — not the system Ruby.
• Deferred functions require Puppet 6.0 or later on the agent; Puppet 7.24+ is recommended.
• get_managed_account identifiers must use exactly one slash (system_name/account_name). Nested account paths are not supported.
• SSL verification is enabled by default. Do not disable certificate validation in production environments.