DocumentationAPI ReferenceRelease Notes
Documentation

Ansible | PS

Ansible is an open-source software provisioning, configuration management, and application-deployment tool that enables IaC (infrastructure as code). Password Safe's integration with Ansible provides an easy to use method for users to secure and manage their Ansible related secrets for automated workflows. Secrets Safe users can leverage this integration for Continuous Integration and Continuous Deployment (CI/CD) and DevOps workflows.

The Secrets Safe Lookup plugin can be configured to retrieve ASCII secrets from Secrets Safe.

Prerequisites


The Secrets Safe Lookup plugin supports the following software, features, and configurations:

  • Supports retrieval of secrets from BeyondInsight and Password Safe version 23.1 or later releases.
  • Supports OAuth client secret for authentication across applications and services.
  • Supports managed account password retrieval.
  • Requires Ansible Core 2.19.11 or later, excluding 2.20.0-2.20.6 and 2.21.0, that is 2.19.11+ on the 2.19 branch, 2.20.7+ on the 2.20 branch, or 2.21.1 and later. The excluded releases sort above the floor but are not supported, because they are unpatched for CVE-2026-11332.
  • CVE-2026-11332 is fixed per branch, not at a single version: 2.19.11+, 2.20.7+ and 2.21.1+ are patched; releases below those points on each branch are affected. Every release the supported set admits that existed when this collection shipped is patched for that advisory, though not every such patched release is admitted — the 2.16, 2.17 and 2.18 branches also carry patched releases and sit outside the supported set. This is not a guarantee against every ansible-core advisory: CVE-2026-16493 is published and has no fix in any release, including the pinned one. It is reachable only when installing collections from a git source, not via Galaxy or a tarball. The specifier is open-ended, so it additionally admits ansible-core versions published after this one; those have not been evaluated and no claim is made about them.
    ℹ️

    The 2.19 branch reaches end of life on 2026-11-30: it is supported until then, and dropping it afterwards will be a major release.

  • BeyondTrust builds and tests against the exact version pinned in requirements.txt. Other supported releases are expected to work but are not validated.
  • Requires a dedicated Python virtual environment. Installing the collection's requirements.txt sets the ansible-core version of whatever environment is active, so a shared or system environment would have its ansible-core changed for every other collection in it.
  • Requires Python 3.12, 3.13 or 3.14 — the versions the pinned ansible-core supports. 3.12 is a hard floor (ansible-core and beyondtrust-bips-library both declare requires-python >= 3.12); 3.14 is the current ceiling, because ansible-core 2.21.3 declares support no further. A newer Python is not covered by this collection's tested configuration.
  • The Secrets Safe instance must be preconfigured with the secret in question, and an account must be authorized to read it in order for this plugin to retrieve a secret.
🚧

Important information

  • Do not log the secrets to stdout. Security-minded engineers must review playbooks composition before changes are run with access to secrets.
  • Ansible writes lookup plugin arguments to stdout. Do not put secret text directly in the lookup plugin arguments. Use variables as an alternative.

Overview

The Secrets Safe Lookup plugin is named secrets_safe_lookup. It is designed to be run on an Ansible Control node (Linux). The lookup plugin is available from the Ansible Galaxy Registry.

ℹ️

For more information, see the Ansible Galaxy Registry.

A diagram showing how an Ansible Control Node integrates with Password Safe and Secrets Safe to retrieve credentials and run modules on managed nodes. The Ansible Control Node includes components such as Host Inventory, Ansible Core, Connection Plugins, Playbooks, Custom Modules, and a Secrets Safe Lookup Plugin.

General setup

  • Create an API registration in BeyondInsight. Ensure the User password required option is disabled.
  • Create or use an existing Secrets Safe group.
  • Create or use an existing BeyondInsight user.
  • Add API registration to the group.
  • Add the user to the group.
  • Add the Secrets Safe feature to the group. Assign read-only or full access based on your use case.

Managed accounts setup

  1. Create or use an existing access policy that has the View Password option enabled with the Auto Approve option selected.
  2. Add the All Managed Accounts Smart Group to the BeyondInsight group.
  3. Add the access policy to Password Safe role assigned to the All Managed Accounts Smart Group. Ensure that both Requestor and Approver are selected in the assigned role.
  4. Create or use an existing managed system.
  5. Create or use an existing managed account associated with the managed system.
  6. Configure the managed account with the API Enabled and Max Concurrent Requests Unlimited options selected.

Available Ansible collections

Prepare the environment

Before you install anything, run the following script:

ℹ️

Not preparing the environment is the most common cause of a failed install.

For more information, see Troubleshooting.

# Any Python 3.12, 3.13 or 3.14 interpreter works — substitute the one you have.
python3.12 -m venv ~/beyondtrust-ansible-venv
source ~/beyondtrust-ansible-venv/bin/activate
python --version          # confirm 3.12, 3.13 or 3.14

# Install from the newest supported branch. An unversioned install can land on
# an excluded release (2.21.0) and make the next step fail.
pip install 'ansible-core>=2.21.1'
ansible-galaxy --version  # confirm it resolves inside the virtual environment

Installing ansible-core here is required, not optional: a freshly created virtual
environment contains no ansible-galaxy, so the next step would otherwise fall through to
whatever global copy is on PATH — possibly one the collection does not support. The lower
bound above is deliberate: an unversioned pip install ansible-core can land on 2.21.0,
which is excluded, and the collection install then fails. The exact pin comes later, with
requirements.txt; this step only has to land on a supported release.

Installing collections from Ansible Galaxy

To install the collections, you can use the next command if the collection is on Ansible Galaxy repository:

ansible-galaxy collection install beyondtrust.secrets_safe
ansible-galaxy collection install beyondtrust.password_safe

Installing collections from Ansible Galaxy

To install the collections, you can use the next command if the collection is on Ansible Galaxy repository:

ansible-galaxy collection install beyondtrust.secrets_safe
ansible-galaxy collection install beyondtrust.password_safe

Installing collection manually

If you have the collections downloaded locally, you can run the next command:

ansible-galaxy collection install beyondtrust-secrets_safe-<version>.tar.gz
ansible-galaxy collection install beyondtrust-password_safe-<version>.tar.gz

If it's not a fresh install, you would need to run the next command to update the collection to its latest version:

ansible-galaxy collection install --upgrade beyondtrust-secrets_safe-<version>.tar.gz
ansible-galaxy collection install --upgrade beyondtrust-password_safe-<version>.tar.gz

where is the version that you downloaded.

If the installation is successful, run this command:

ansible-galaxy collection list

And you should see the collection installed:

...
Collection               Version
-----------------------  -------
beyondtrust.secrets_safe  1.0.1
beyondtrust.password_safe 1.0.1 
...

Install required modules

To run the plugin in a playbook, you need to install modules using pip, with the file requirements.txt, found locally after installing the collection. Run the following command:

pip install -r ~/.ansible/collections/ansible_collections/beyondtrust/secrets_safe/requirements.txt
pip install -r ~/.ansible/collections/ansible_collections/beyondtrust/password_safe/requirements.txt

Upgrade Python dependencies

When a new version of a required Python package is released, the collection itself does not automatically upgrade it. To upgrade all Python dependencies to the latest versions allowed by the version constraints, run the following commands:

pip install --upgrade -r ~/.ansible/collections/ansible_collections/beyondtrust/secrets_safe/requirements.txt
pip install --upgrade -r ~/.ansible/collections/ansible_collections/beyondtrust/password_safe/requirements.txt

This is also required after you upgrade the collection to a new version and to ensure the Python dependencies match the new requirements.

Troubleshooting

Error: No matching distribution found for ansible-core

The full error lists many available ansible-core versions and then reports that the
requested one is not among them.

The requirement string differs depending on which step you were on. Installing
requirements.txt applies the exact pin, so it reads ansible-core==<x.y.z>; the bootstrap
in step 1 installs a lower bound, so it reads ansible-core>=2.21.1. Both are the same
problem below.

Recent pip also prints an Ignored the following versions that require a different python version: line listing Requires-Python >=3.12 against each filtered release. When that line
is present it is the direct answer, and the diagnosis below just confirms it.

Diagnose with the "from versions" list, which shows what your pip can actually see:

  • The list stops at an older branch — your interpreter is older than 3.12. Recent
    ansible-core releases declare requires-python >= 3.12, so pip filters them out and
    reports the pinned version as nonexistent rather than as incompatible.

    Fix: create and activate a Python 3.12+ virtual environment, then re-run. Note
    python -m venv inherits the interpreter that created it — a virtual environment built by
    Python 3.10 stays 3.10, so it must be recreated with 3.12+, not just reactivated.

  • The list includes recent releases, or you are already on Python 3.12+ — the interpreter
    is not the problem. The configured package index does not carry the pinned release, which
    is common behind a corporate mirror or a private index that has not synced it. Check with
    pip config list and pip index versions ansible-core, then ask whoever maintains the
    mirror to sync the pinned version. Recreating the virtual environment will not help here.

The collection does not support your Ansible version

The control node's installed ansible-core does not satisfy requires_ansible in
meta/runtime.yml. This is not only about being too old — an explicitly excluded
release such as 2.21.0 is newer than the lower bound and fails the same check.

What you see depends on your ansible-core version:

  • 2.21.3requires_ansible is part of dependency resolution, so the install fails:
    ansible-galaxy exits 1 and the collection is not installed (verified).
  • Older clients — enforcement is inconsistent, so you cannot rely on being told.
    2.18.3 prints [WARNING]: Collection ... does not support Ansible version <x.y.z> and
    installs anyway; 2.20.6 installs an excluded release with no warning at all. Both exit 0
    (all verified). Check the version yourself rather than trusting the client.

Fix — this depends on which case you are in:

  • The install failed (2.21.3 and similar). The collection is not installed, so its
    requirements.txt does not exist locally yet — you cannot install from it. Bootstrap a
    supported ansible-core into the virtual environment first, then retry:

    pip install 'ansible-core>=2.21.1'
    ansible-galaxy collection install <collection>          # now succeeds
    pip install -r <installed collection path>/requirements.txt   # applies the exact pin
  • You only saw the warning (older clients). The collection is installed, so
    requirements.txt is available: install from it, then re-run the collection install so
    the warning clears.

COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH can downgrade the check, but that suppresses the
signal rather than fixing the mismatch.

Secrets Safe Ansible Collection Documentation

Use the Secrets Safe lookup plugin

Usage

  • api_url
    • description: BeyondTrust Password Safe API URL.
    • type: string
    • required: True
  • api_version
    • description: The recommended version is 3.1. If no version is specified, the default API version 3.0 is used.
    • type: string
    • required: False
  • retrieval_type
    • description: Type of secret to retrieve (use MANAGED_ACCOUNT or SECRET)
    • type: string
    • required: True
  • api_key
    • description: API Key. If not set, then client_id/client_secret become required. RunAs user should be provided along with API key, e.g:
    • type: string
    • required: False
  • client_id
    • description: API OAuth Client ID.
    • type: string
    • required: True
  • client_secret
    • description: API OAuth Client Secret.
    • type: string
    • required: True
  • secret_list
    • description: List of secrets (path/title,path/title) or managed accounts (ms/ma,ms/ma) to be retrieved, separated by a comma.
    • type: string
    • required: True
  • certificate_path
    • description: Password Safe API pfx Certificate Path. For use when authenticating using a Client Certificate.
    • type: string
    • required: False
  • certificate_password
    • description: Password Safe API pfx Certificate Password. For use when authenticating using a Client Certificate.
    • type: string
    • required: False
  • verify_ca
    • description: Controls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C (false) for testing purposes in trusted environments.
    • type: boolean/string
    • default: True
    • required: False
  • decrypt
    • description: When true, returns the decrypted password field; when false, the password field is omitted, this option only applies when retrieval_type is set to SECRET.
    • type: boolean
    • default: True
    • required: False
  • rotate_on_checkin
          description: If True, rotates the password on check-in, only applies when retrieval type is set to MANAGED_ACCOUNT
          type: boolean
          default: True
          required: False

Example

"{{lookup('beyondTrust.secrets_safe.secrets_safe_lookup', api_url=apiURL, api_version='3.1', retrieval_type='SECRET', client_id=clientIdFromEnvVar, client_secret=secretFromEnvVar, secret_list=secretList, certificate_path=certificatePath, certificate_password=certificatePasswordFromEnVar, wantlist=False, verify_ca=True)}}"

Output

  • description: list of retrieved secret(s) in the requested order.
  • type: list
  • elements: str

Example

export PASSWORD_SAFE_CLIENT_ID=********************
export PASSWORD_SAFE_CLIENT_SECRET=********************
export CERTIFICATE_PASSWORD=********************
export PASSWORD_SAFE_API_URL=https://example.com:443/BeyondTrust/api/public/v3
---
- name: book
  hosts: localhost
  connection: local
  vars:
      apiURL: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
      clientIdFromEnvVar: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
      secretFromEnvVar: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
      certificatePasswordFromEnVar:  "{{ lookup('ansible.builtin.env', 'CERTIFICATE_PASSWORD') }}"
      certificatePath: "<path>/ClientCertificate.pfx"
      secretManagedAccounts: "fake_system/fake_ managed_account,fake_system/fake_managed_account01"
      gotManagedAccount: "{{lookup('beyondTrust.secrets_safe.secrets_safe_lookup', api_url=apiURL, retrieval_type='MANAGED_ACCOUNT', client_id=clientIdFromEnvVar, client_secret=secretFromEnvVar, secret_list=secretManagedAccounts, certificate_path=certificatePath, certificate_password=certificatePasswordFromEnVar, wantlist=False)}}"
      secretList: "fake_grp/credential,fake_grp/file"
      gotSecrets: "{{lookup('beyondTrust.secrets_safe.secrets_safe_lookup', api_url=apiURL, api_version='3.1', retrieval_type='SECRET', client_id=clientIdFromEnvVar, client_secret=secretFromEnvVar, secret_list=secretList, certificate_path=certificatePath, certificate_password=certificatePasswordFromEnVar, wantlist=False, verify_ca=True)}}"
  tasks:
    - name: Display Retrieved Managed accounts
      ansible.builtin.debug:
        msg: "{{ gotManagedAccount }}"
    - name: Display Retrieved Secrets
      ansible.builtin.debug:
        msg: "{{ gotSecrets }}"

Module: folders_create

Short Description

Create Folder in Beyondtrust Password Safe API.

Description

Creates a folder in the given folder name.

Parameters

NameDescriptionTypeRequiredDefault
client_idAPI OAuth Client ID.str✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
api_urlBeyondTrust Password Safe API URLstr✅ Yes
dataFolder datadict✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (e.g. C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue

Details of data object

NameDescriptionTypeRequiredDefault
nameThe name of the folderstr✅ Yes
descriptionThe description of the folderstr❌ No
user_group_idthe user group id.int❌ No
folder_nameThe Name of the parent folder where folder will be created.str✅ Yes

Example

- name: Create Folder
  beyondtrust.secrets_safe.folders_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    data:
      name: "my_folder_name"
      folder_name: "parent_folder"
      description: "folder description"

Return values

NameDescriptionReturnedTypeSample
idCreated Folder Idsuccessstr5601e126-9f1a-4c9c-9e4c-08db7741b532
nameCreated Folder NamesuccessstrFolder Name

Module: safes_create

Short Description

Create Safe in Beyondtrust Password Safe API.

Description

Creates a Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
api_urlBeyondTrust Password Safe API URLstr✅ Yes
dataSafe datadict✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be usedstr❌ No3.0
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue

Details of data object

NameDescriptionTypeRequiredDefault
nameThe name of the Safestr✅ Yes
descriptionThe description of the Safestr❌ No

Example

- name: Create Safe
  beyondtrust.secrets_safe.safes_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    data:
      name: "my_safe_name"
      description: "safe description"

Return values

NameDescriptionReturnedTypeSample
idCreated Safes Idsuccessstr5601e126-9f1a-4c9c-9e4c-08db7741b532
nameCreated Safe NamesuccessstrSafe Title

Module: secrets_create

Short Description

Create secrets (credential, text, file) in Beyondtrust Password Safe API.

Description

Creates a secret (credential, text, file) in the given folder name.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
dataSecret datadict✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue

Details of data object

NameDescriptionTypeRequiredDefault
titleThe full title of the secretstr✅ Yes
descriptionThe description of the secretstr❌ No
owner_idThe ID of the ownerint❌ No
owner_typeThe type of the ownerstr❌ No
file_pathThe path to the file for File Secretsstr❌ No
usernameThe username for normal Secretsstr❌ No
passwordThe password for normal Secretsstr❌ No
password_rule_idThe ID of the password rulestr❌ No
notesNotes about the secretstr❌ No
textThe text content for Text Secretsstr❌ No
folder_nameThe Name of the folder where secrets will be created.str✅ Yes
urlsBeyondTrust A list of URLs with this format.list❌ No
ownersA list of owners.list✅ Yes

Example

- name: Create File Secret in PS
  beyondtrust.secrets_safe.secrets_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    data:
      title: "Secret Title"
      username: "test_user"
      password: "Secret content"
      folder_name: "my_folder_name"
      description: "Folder Description"
      owner_id: 12
      owner_type: "User"
      owners:
        - owner_id: 12
- name: Create Credential Secret in PS
  beyondtrust.secrets_safe.secrets_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    data:
      title: "Secret Title"
      text: "Secret content"
      folder_name: "my_folder_name"
      description: "Folder Description"
      owner_id: 12
      owner_type: "User"
      owners:
        - owner_id: 12
- name: Create Text Secret in PS
  beyondtrust.secrets_safe.secrets_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    data:
      title: "Secret Title"
      file_path: "my_secret.txt"
      folder_name: "my_folder_name"
      description: "Folder Description"
      owner_id: 12
      owner_type: "User"
      owners:
        - owner_id: 12

Return values

NameDescriptionReturnedTypeSample
secret_idCreated Secret Idsuccessstr5601e126-9f1a-4c9c-9e4c-08db7741b532
secret_nameCreated Secret NamesuccessstrSecret Title

Lookup Plugins

Lookup Plugin: safes_list

Short Description

Retrieve safes list from Password Safe.

Description

Custom lookup plugin to fetch safes list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
workgroup_idThe Workgroup ID, if want to search by Workgroup IDN/A❌ No
workgroup_nameThe Workgroup name, if want to search by Workgroup nameN/A❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    safes: "{{ lookup('beyondtrust.password_safe.safes_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Safes list
      debug:
        msg: "{{ safes }}"
    - name: Print my_new_safe_name safe
      debug:
        msg: "{{ safes | selectattr('Name', 'equalto', 'my_new_safe_name') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all safesstr

Lookup Plugin: folders_list

Short Description

Retrieve folders list from Password Safe.

Description

Custom lookup plugin to fetch folders list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
workgroup_idThe Workgroup ID, if want to search by Workgroup IDN/A❌ No
workgroup_nameThe Workgroup name, if want to search by Workgroup nameN/A❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    folders: "{{ lookup('beyondtrust.password_safe.folders_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Folders list
      debug:
        msg: "{{ folders }}"
    - name: Print folder2 folder
      debug:
        msg: "{{ folders | selectattr('Name', 'equalto', 'folder2') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all foldersstr

Lookup Plugin: secrets_safe_lookup

Short Description

Retrieve ASCII secrets from Secrets Safe.

Description

Retrieve ASCII secrets and managed account passwords from BeyondTrust Password Safe 23.1 or greater.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
api_key"API Key. If not set, then client_id/client_secret become required. RunAs user should be provided along with API key: e.g: <key;runas=<user"N/A❌ No
retrieval_typeType of secret to retrieve (use MANAGED_ACCOUNT or SECRET)str✅ Yes
client_idAPI OAuth Client ID. Required only if api_key is not provided.str❌ No
client_secretAPI OAuth Client Secret. Required only if api_key is not provided.str❌ No
certificate_pathPassword Safe API pfx Certificate Path. For use when authenticating using a Client Certificate.str❌ No
certificate_passwordPassword Safe API pfx Certificate Password. For use when authenticating using a Client Certificate.str❌ No
secret_listList of secrets (path/title) or managed accounts (ms/ma) to be retrieved, separated by comma.str✅ Yes
separatorSecrets path separator, that is: folder1/folder2str❌ No
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
list_delimiterList delimiter, e.g.: secret1,secret2,secret3.str❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret:
      "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    certificatePasswordFromEnVar:
      "{{ lookup('ansible.builtin.env', 'CERTIFICATE_PASSWORD') }}"
    certificatePath: "<path>/ClientCertificate.pfx"
    secretManagedAccounts:
      "fake_system/fake_managed_account,fake_system/fake_managed_account01"
    gotManagedAccount:
      "{{lookup('beyondTrust.secrets_safe.secrets_safe_lookup',
        api_url=api_url,
        retrieval_type='MANAGED_ACCOUNT',
        client_id=client_id,
        client_secret=client_secret,
        secret_list=secretManagedAccounts,
        certificate_path=certificatePath,
        certificate_password=certificatePasswordFromEnVar,
        wantlist=False)}}"
    secretList: "fake_grp/credential,fake_grp/file"
    gotSecrets:
      "{{lookup('beyondTrust.secrets_safe.secrets_safe_lookup',
        api_url=api_url,
        retrieval_type='SECRET',
        client_id=client_id,
        client_secret=client_secret,
        secret_list=secretList,
        certificate_path=certificatePath,
        certificate_password=certificatePasswordFromEnVar,
        wantlist=False,
        verify_ca=True)}}"

Return values

NameDescriptionReturnedTypeSample
_listlist of retrieved secret(s) in the requested orderlist

Password Safe Ansible Collection Documentation

Module: assets_create

Short Description

Create Assets in Beyondtrust Password Safe API.

Description

Creates an asset.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataAsset data.dict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
workgroup_idworkgroup id.int❌ No
workgroup_nameworkgroup name.str❌ No
ip_addressAsset IP addressstr✅ Yes
asset_nameAsset name. If not given, a padded IP address is used.str✅ Yes
dns_nameAsset DNS namestr❌ No
domain_nameAsset domain namestr❌ No
mac_addressAsset MAC addressstr❌ No
asset_typeAsset typestr❌ No
descriptionAsset descriptionlist❌ No
operating_systemAsset operating systemlist❌ No

Example

- name: Create Asset
  beyondtrust.password_safe.assets_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      workgroup_id: 10
      ip_address: "192.168.1.100"
      asset_name: "my_asset"
      dns_name: "my-asset.example.com"
      domain_name: "example.com"
      mac_address: "00:1A:2B:3C:4D:5E"
      asset_type: "Server"
      description: "Linux application server"
      operating_system: "Ubuntu 22.04 LTS"

Return values

NameDescriptionReturnedTypeSample
idCreated Asset Id.successint123
nameCreated Asset NamesuccessstrAsset Name

Module: workgroups_create

Short Description

Create Workgroup in Beyondtrust Password Safe API.

Description

Creates a workgroup.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataWorkgroup data.dict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
nameThe name of the workgroupstr✅ Yes
organization_idOrganization idstr❌ No

Example

- name: Create workgroup
  beyondtrust.password_safe.workgroups_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      name: "organization_name"

Return values

NameDescriptionReturnedTypeSample
idCreated Workgroup Idsuccessstr5601e126-9f1a-4c9c-9e4c-08db7741b532
nameCreated Workgroup namesuccessstrWorkgroup Name

Module: managed_systems_create_by_workgroup_id

Short Description

Create Managed System by Workgroup Id in Beyondtrust Password Safe API.

Description

Creates a Managed System by Workgroup Id.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caVerify CA parameter for SSL certificate validation. If set to False, SSL certificate validation will be disabled, which is insecure and exposes you to man-in-the-middle attacks. Only set to False for testing purposes in trusted environments.bool/str❌ NoTrue
dataManaged System datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
workgroup_idworkgroup id.int✅ Yes
entity_type_idID of the entity typeint✅ Yes
host_nameHost name of the managed systemstr✅ Yes
ip_addressIP address of the managed systemstr✅ Yes
dns_nameDNS name of the managed systemstr✅ Yes
domain_nameAsset domain namestr❌ No
instance_nameInstance name of the managed systemstr❌ No
forest_nameForest name for the managed systemstr❌ No
platform_idID of the managed system platformint✅ Yes
net_bios_nameNetBIOS name of the managed systemstr❌ No
contact_emailContact email address (max length 1000)str✅ Yes
descriptionDescription of the managed system (max length 255)str❌ No
timeoutConnection timeout in seconds before a slow or unresponsive connection fails.int❌ No
password_rule_idID of the default password rule assigned to managed accounts created under this managed system.int❌ No
account_name_formatFormat for the account name.int✅ Yes
oracle_internet_directory_service_nameOracle Internet Directory service name.str❌ No
release_durationDefault release duration in minutes.int❌ No
max_release_durationDefault maximum release duration in minutes.int❌ No
isa_release_durationDefault Information Systems Administrator (ISA) release duration in minutes.int❌ No
auto_management_flagTrue if password auto-management is enabled, otherwise false.bool❌ No
check_password_flagTrue to enable password testing, otherwise false.bool❌ No
change_password_after_any_release_flagTrue to change passwords on release of a request, otherwise false.bool❌ No
reset_password_on_mismatch_flagTrue to queue a password change when scheduled password test fails, otherwise false.bool❌ No
change_frequency_typeThe change frequency for scheduled password changes (first, last, xdays).str❌ No
change_frequency_daysNumber of days for xdays frequency.int❌ No
change_timeUTC time of day scheduled password changes take place (24hr format 00:00-23:59).str❌ No
remote_client_typeThe type of remote client to use.str❌ No
is_application_hostTrue if the managed system can be used as an application host, otherwise false.bool❌ No
access_urlAccess URL for the managed system.str❌ No
is_default_instanceTrue if this is the default instance, otherwise false.bool❌ No
use_sslTrue to use SSL for connections, otherwise false.bool❌ No
portThe port used to connect to the host.int❌ No
ssh_key_enforcement_modeEnforcement mode for SSH host keys (0- None, 1 -Auto, 2- Strict).int❌ No
ssh_key_enforcement_modeEnforcement mode for SSH host keys (0- None, 1- Auto, 2- Strict).int❌ No
login_account_idID of the functional account used for SSH Session logins.int❌ No
oracle_internet_directory_idOracle Internet Directory ID.str❌ No
functional_account_idID of the functional account used for local managed account password changes.int❌ No
elevation_commandElevation command to use (sudo, pbrun, pmrun).str❌ No
application_host_idManaged system ID of the target application host.int❌ No

Example

- name: Create Managed System
  beyondtrust.password_safe.managed_systems_create_by_workgroup_id:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      workgroup_id: 55
      entity_type_id: 1
      host_name: "test-server-01"
      ip_address: "192.168.1.100"
      dns_name: "test-server-01.example.com"
      instance_name: "SQLInstance1"
      template: "Standard"
      forest_name: "example.local"
      platform_id: 1
      net_bios_name: "TESTSRV01"
      contact_email: "[email protected]"
      description: "Test SQL Server"
      timeout: 60
      password_rule_id: 0
      account_name_format: 1
      oracle_internet_directory_service_name: "OIDService"
      release_duration: 180
      max_release_duration: 1440
      isa_release_duration: 120
      auto_management_flag: false
      check_password_flag: true
      change_password_after_any_release_flag: false
      reset_password_on_mismatch_flag: true
      change_frequency_type: "xdays"
      change_frequency_days: 30
      change_time: "02:00"
      remote_client_type: "EPM"
      is_application_host: false
      access_url: "https://test-server-01.example.com"
      is_default_instance: true
      use_ssl: true
      port: 1433
      ssh_key_enforcement_mode: 0
      dss_key_rule_id: 0
      login_account_id: 0
      oracle_internet_directory_id: "2a1ce180-2ae7-470a-9dda-1a8935407a1b"
      functional_account_id: 4
      elevation_command: "sudo"
      application_host_id: 5001

Return values

NameDescriptionReturnedTypeSample
idCreated Managed System Idsuccessint123
nameCreated Managed System NamesuccessstrManaged System Name

Module: managed_accounts_create

Short Description

Create Managed Accounts in Beyondtrust Password Safe API.

Description

Creates a managed account.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataManaged Account datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
managed_system_nameManaged System Namestr✅ Yes
account_nameAccount namestr❌ No
passwordAccount passwordstr✅ Yes
domain_nameAsset domain namestr❌ No
user_principal_nameUser Principal Namestr❌ No
sam_account_nameThe Active Directory SAM account namestr❌ No
platform_idID of the managed system platformint❌ No
distinguished_nameThe LDAP distinguished namestr❌ No
private_keyDSS private keystr❌ No
passphraseDSS passphrasestr❌ No
password_fallback_flagFlag to allow password fallbackbool❌ NoFalse
login_account_flagIndicates if this is a login accountbool❌ No
account_name_formatFormat for the account name.int❌ No

description

Description of the account.

Oracle Internet Directory service name.str❌ No
password_rule_idIdentifier of the password rule.int❌ No0
api_enabledIndicates if API access is enabled.bool❌ NoFalse
release_notification_emailEmail address for release notifications.int❌ No120
max_release_durationDefault maximum release duration in minutes.int❌ No525600
change_services_flagIndicates if services should be changed when the password is updated.❌ No
restart_services_flagIndicates if services should be restarted after password changes.❌ No
change_tasks_flagIndicates if tasks should be updated when the password changes.❌ No
release_durationDefault release duration in minutes.int❌ No
isa_release_durationDefault Information Systems Administrator (ISA) release duration in minutes.int❌ No120
max_concurrent_requestsMaximum number of concurrent password requests for this account.int❌ No1
auto_management_flagTrue if password auto-management is enabled, otherwise false.bool❌ NoFalse
dss_auto_management_flagTrue if DSS key auto-management is enabled, otherwise falsebool❌ NoFalse
check_password_flagTrue to enable password testing, otherwise false.bool❌ NoFalse
change_password_after_any_release_flagTrue to change passwords on release of a request, otherwise false.bool❌ NoFalse
reset_password_on_mismatch_flagTrue to queue a password change when scheduled password test fails, otherwise false.bool❌ NoFalse
next_change_dateDate of the next scheduled password change.str❌ No
use_own_credentialsTrue if the current account credentials should be used during change operations, otherwise false.bool❌ No
change_iis_app_pool_flagIndicates if IIS application pools should be updated after password changes.bool❌ No
restart_iis_app_pool_flagTrue if IIS application pools should be restarted after the run as password is changed, otherwise false.bool❌ No
workgroup_idID of the assigned Workgroup.❌ No
change_windows_auto_logon_flagTrue if Windows Auto Logon should be updated with the new password after a password change, otherwise false.bool❌ NoFalse
change_com_plus_flagTrue if COM+ Apps should be updated with the new password after a password change, otherwise false.bool❌ NoFalse
change_dcom_flagTrue if DCOM Apps should be updated with the new password after a password change, otherwise false.bool❌ NoFalse
change_scom_flagTrue if SCOM Identities should be updated with the new password after a password change, otherwise false.bool❌ NoFalse
object_idUnique object identifier.❌ No
change_frequency_typeThe change frequency for scheduled password changes (first, last, xdays).str❌ Nofirst
change_frequency_daysNumber of days for xdays frequency.int❌ No
change_timeUTC time of day scheduled password changes take place (24hr format 00:00-23:59).str❌ No

Example

- name: Create Managed Accounts
  beyondtrust.password_safe.managed_accounts_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      managed_system_name: "System Name"
      account_name: "example_account"
      password: "SomePasswordValue123!"
      domain_name: "example.com"
      user_principal_name: "[email protected]"
      sam_account_name: "EXAMPLE\\user"
      distinguished_name: "CN=User Example,OU=Users,DC=example,DC=com"
      private_key: "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9...\n-----END PRIVATE KEY-----"
      passphrase: "MySecurePassphrase"
      password_fallback_flag: true
      login_account_flag: false
      description: "This is an example managed account"
      password_rule_id: 42
      api_enabled: true
      release_notification_email: "[email protected]"
      change_services_flag: true
      restart_services_flag: false
      change_tasks_flag: true
      release_duration: 180
      max_release_duration: 1440
      isa_release_duration: 120
      max_concurrent_requests: 3
      auto_management_flag: false
      dss_auto_management_flag: false
      check_password_flag: true
      reset_password_on_mismatch_flag: true
      change_password_after_any_release_flag: false
      change_frequency_type: "xdays"
      change_frequency_days: 30
      change_time: "02:00"
      next_change_date: "2025-10-13"
      use_own_credentials: false
      change_iis_app_pool_flag: true
      restart_iis_app_pool_flag: true
      workgroup_id: 501
      change_windows_auto_logon_flag: false
      change_com_plus_flag: true
      change_dcom_flag: false
      change_scom_flag: false
      object_id: "d27fee10-30b2-46ee-9d61-192c34fb2bfd"

Return values

NameDescriptionReturnedTypeSample
idCreated Managed Account Idsuccessint61
nameCreated Managed Account NamesuccessstrManaged Account Name

Module: functional_accounts_create

Short Description

Create Functional Account in Beyondtrust Password Safe API.

Description

Creates a functional account.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataFunctional Account datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
functional_account_idFunctional Account IDstr❌ No
platform_idPlatform IDint✅ Yes
domain_nameDomain namestr❌ No
account_nameAccount Namestr✅ Yes
display_nameDisplay Namestr❌ No
passwordPasswordstr❌ No
private_keyPrivate Keystr❌ No
private_keyPrivate Keystr❌ No
descriptionDescriptionstr❌ No
elevation_commandElevation Commandstr❌ No
tenant_idTenant IDstr❌ No
object_idObject IDstr❌ No
secretSecretstr❌ No
service_account_emailService Account Emailstr❌ No
azure_instanceAzure Instance (AzurePublic or AzureUsGovernment)str❌ No

Example

- name: Create Functional account
  beyondtrust.password_safe.functional_accounts_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      platform_id: 123
      account_name: "my_account"
      domain_name: "example.com"
      display_name: "My Account Display Name"
      password: "SomePasswordValue"
      private_key: "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9...\n-----END PRIVATE KEY-----"
      passphrase: "MyPassphrase"
      description: "This is an example account description"
      elevation_command: "sudo su -"
      tenant_id: "a3f2c5e8-47b0-4b3f-8e9a-12c456789abc"
      object_id: "d47a9b1e-9f32-4c2e-8a3d-9e1b5f7f1c23"
      secret: "SomeSecretValue"
      service_account_email: "[email protected]"
      azure_instance: "AzurePublic"

Return values

NameDescriptionReturnedTypeSample
idCreated Functional Account Idsuccessint61
nameCreated Functional Account NamesuccessstrAccount Name

Module: databases_create

Short Description

Create Database in Beyondtrust Password Safe API.

Description

Creates a Database.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataDatabase datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
asset_idThe Asset Id.int✅ Yes
platform_idPlatform IDint✅ Yes
portThe database port.int✅ Yes
instance_nameName of the database instance. Required when IsDefaultInstance is false. Max string length is 100.str❌ No
is_default_instanceTrue if the database instance is the default instance, otherwise false.bool❌ No
versionThe database version. Max string value is 20.str❌ No
templateThe database connection template.str❌ No

Example

- name: Create Database
  beyondtrust.password_safe.databases_create:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      asset_id=1
      platform_id=9
      port=1
      instance_name="data base name"
      is_default_instance=false
      version="1.2"
      template=""

Return values

NameDescriptionReturnedTypeSample
idCreated Database Instance Idsuccessint123
nameCreated Database Instance NamesuccessstrDatabase Name

Module: managed_systems_create_by_database_id

Short Description

Create Managed System by Database Id in Beyondtrust Password Safe API.

Description

Creates a Managed System by Database Id.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataManaged System datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
database_idThe ID of the database.int✅ Yes
contact_emailContact email address (max length 1000).str✅ Yes
Description of the managed system (max length 255).The database port.int✅ Yes
timeoutConnection timeout in seconds before a slow or unresponsive connection fails (default 30).str❌ No
password_rule_idID of the default password rule assigned to managed accounts created under this managed system (default 0).bool❌ No
release_durationDefault release duration in minutes (range 1-525600, default 120).str❌ No120
max_release_durationDefault maximum release duration in minutes (range 1-525600, default 525600).str❌ No525600
isa_release_durationDefault Information Systems Administrator (ISA) release duration in minutes (range 1-525600, default 120).int❌ No120
auto_management_flagTrue if password auto-management is enabled, otherwise false; can be set if Platform.AutoManagementFlag is true (default false).bool❌ NoFalse
functional_account_idID of the functional account used for local managed account password changes.int❌ No
check_password_flagTrue to enable password testing, otherwise false.bool❌ No
change_password_after_any_release_flagTrue to change passwords on release of a request, otherwise false.bool❌ No
reset_password_on_mismatch_flagTrue to queue a password change when scheduled password test fails, otherwise false.bool❌ No
change_frequency_typeThe change frequency for scheduled password changes.str❌ Nofirst
change_frequency_daysNumber of days for xdays frequency.int❌ No
change_timeUTC time of day scheduled password changes take place (24hr format 00:00-23:59, default 23:30).str❌ No23:30

Example

- name: Create Managed System
  beyondtrust.password_safe.managed_systems_create_by_database_id:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      database_id: 2
      contact_email: "[email protected]"
      description: "Test SQL Server"
      timeout: 60
      password_rule_id: 0
      release_duration: 180
      max_release_duration: 1440
      isa_release_duration: 120
      auto_management_flag: false
      functional_account_id: 0
      check_password_flag: true
      change_password_after_any_release_flag: false
      reset_password_on_mismatch_flag: true
      change_frequency_type: "xdays"
      change_frequency_days: 30
      change_time: "02:00"

Return values

NameDescriptionReturnedTypeSample
idCreated Managed System Idsuccessint123
nameCreated Managed System NamesuccessstrManaged System Name

Module: managed_systems_create_by_asset_id

Short Description

Create Managed System by Asset Id in Beyondtrust Password Safe API.

Description

Creates a Managed System by Asset Id.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
dataManaged System datadict✅ Yes

Details of data object

NameDescriptionTypeRequiredDefault
asset_idThe ID of the Asset.int✅ Yes
platform_idID of the managed system platform (required).int✅ Yes
contact_emailContact email address (max length 1000).str✅ Yes
descriptionDescription of the managed system (max length 255).int✅ Yes
portThe port used to connect to the host, if null and Platform.PortFlag is true, uses Platform.DefaultPort.int❌ No
timeoutConnection timeout in seconds before a slow or unresponsive connection fails (default 30).str❌ No30
ssh_key_enforcement_modeEnforcement mode for SSH host keys (0- None, 1- Auto, 2- Strict; default 0).int❌ No0
password_rule_idID of the default password rule assigned to managed accounts created under this managed system (default 0).int❌ No0
dss_key_rule_idID of the default DSS key rule assigned to managed accounts; can be set when Platform.DSSFlag is true (default 0).int❌ No0
login_account_idID of the functional account used for SSH Session logins; can be set if Platform.LoginAccountFlag is true.int❌ No0
release_durationDefault release duration in minutes (range 1-525600, default 120).str❌ No120
max_release_durationDefault maximum release duration in minutes (range 1-525600, default 525600).str❌ No525600
isa_release_durationDefault Information Systems Administrator (ISA) release duration in minutes (range 1-525600, default 120).int❌ No120
auto_management_flagTrue if password auto-management is enabled, otherwise false; can be set if Platform.AutoManagementFlag is true (default false).bool❌ NoFalse
functional_account_idID of the functional account used for local managed account password changes.int❌ No
elevation_commandElevation command to use (sudo, pbrun, pmrun); can be set if Platform.SupportsElevationFlag is true.str❌ No
check_password_flagTrue to enable password testing, otherwise false.bool❌ No
change_password_after_any_release_flagTrue to change passwords on release of a request, otherwise false.bool❌ No
reset_password_on_mismatch_flagTrue to queue a password change when scheduled password test fails, otherwise false.bool❌ No
change_frequency_typeThe change frequency for scheduled password changes.str❌ Nofirst
change_frequency_daysNumber of days for xdays frequency.int❌ No
change_timeUTC time of day scheduled password changes take place (24hr format 00:00-23:59, default 23:30).str❌ No23:30
remote_client_typeThe type of remote client to use (None, EPM).str❌ No
application_host_idManaged system ID of the target application host (required when Platform.RequiresApplicationHost is true).int❌ No
is_application_hostTrue if the managed system can be used as an application host.bool❌ No

Example

- name: Create Managed System
  beyondtrust.password_safe.managed_systems_create_by_asset_id:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    api_version: "3.0"
    verify_ca: true
    data:
      asset_id: 48
      platform_id: 1
      contact_email: "[email protected]"
      description: "Linux Test Server"
      release_duration: 125
      max_release_duration: 1440
      isa_release_duration: 125
      password_rule_id: 0
      check_password_flag: true
      change_password_after_any_release_flag: false
      reset_password_on_mismatch_flag: true
      change_frequency_type: "xdays"
      change_frequency_days: 30
      change_time: "02:00"
      is_application_host: false
      timeout: 60
      port: 22
      ssh_key_enforcement_mode: 1
      dss_key_rule_id: 0
      login_account_id: 0
      auto_management_flag: false
      functional_account_id: 4
      elevation_command: "sudo"
      remote_client_type: "EPM"
      application_host_id: 3001

Return values

NameDescriptionReturnedTypeSample
idCreated Managed System Idsuccessint123
nameCreated Managed System NamesuccessstrManaged System Name

Lookup Plugins

Lookup Plugin: functional_accounts_list

Short Description

Retrieve functional accounts list from Password Safe.

Description

Custom lookup plugin to fetch functional accounts list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    functional_accounts: >-
      {{ lookup('beyondtrust.password_safe.functional_accounts_list',
        api_url=api_url,
        client_id=client_id,
        client_secret=client_secret) }}
  tasks:
    - name: Print functional accounts list
      debug:
        msg: "{{ functional_accounts }}"
    - name: Print test Functional account
      debug:
        msg: "{{ functional_accounts | selectattr('AccountName', 'equalto', 'test') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all functional accounts.list

Lookup Plugin: workgroups_list

Short Description

Retrieve workgroups list from Password Safe.

Description

List of all workgroups that match the specified filters.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
workgroup_nameThe Workgroup name, if want to search by Workgroup name.N/A❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    workgroups: "{{ lookup('beyondtrust.password_safe.workgroups_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Workgroups list
      debug:
        msg: "{{ workgroups }}"
    - name: Default Workgroup
      debug:
        msg: "{{ workgroups | selectattr('Name', 'equalto', 'Default Workgroup') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all workgroups.list

Lookup Plugin: assets_list

Short Description

List of all assets that match the specified filters.

Description

Custom lookup plugin to fetch assets list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide
a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.
bool/str❌ NoTrue
workgroup_idThe Workgroup ID, if want to search by Workgroup ID.N/A❌ No
workgroup_nameThe Workgroup name, if want to search by Workgroup name.N/A❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    assets: "{{ lookup('beyondtrust.password_safe.assets_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Assets list
      debug:
        msg: "{{ assets }}"
    - name: Print MyNewAsset2 Asset
      debug:
        msg: "{{ assets | selectattr('AssetName', 'equalto', 'MyNewAsset2') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all assets.list

Lookup Plugin: managed_accounts_list

Short Description

List of all managed accounts that match the specified filters.

Description

Custom lookup plugin to fetch managed accounts list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
workgroup_nameThe name of the workgroupstr❌ No
system_nameThe name of the system where the account is managed.str❌ No
account_nameThe name of the managed account to retrieve.str❌ No
system_idThe ID of the managed systemint❌ No
application_display_nameThe display name of the application.str❌ No
ip_addressThe IP address of the managed asset.str❌ No
type

The type of the managed account to return.

Options are: system, recent, domainlinked, database, cloud, application.

str❌ No
limitThe number of records to return. Default is 1000.int❌ No1000
offsetThe number of records to skip before returning records. Default is 0.int❌ No0

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    managed_accounts: "{{ lookup('beyondtrust.password_safe.managed_accounts_list', api_url=api_url,
      client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Managed Accounts list
      debug:
        msg: "{{ managed_accounts }}"
    - name: Print managed_account01 Managed Account
      debug:
        msg: "{{ managed_accounts | selectattr('AccountDescription', 'equalto', 'managed_account01') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all managed accounts.list

Lookup Plugin: platforms_list

Short Description

Retrieve platforms list from Password Safe.

Description

Custom lookup plugin to fetch platforms list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide
a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.
bool/str❌ NoTrue

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    platforms: "{{ lookup('beyondtrust.password_safe.folders_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Platforms list
      debug:
        msg: "{{ platforms }}"
    - name: Print XING Platform
      debug:
        msg: "{{ platforms | selectattr('Name', 'equalto', 'XING') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all platforms.list

Lookup Plugin: managed_systems_list

Short Description

List of all managed systems that match the specified filters.

Description

Custom lookup plugin to fetch managed systems list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue
nameThe managed system name.str❌ No
typeThe entity type of the managed system.int❌ No
offsetThe number of records to skip before returning records.int❌ No
limitThe number of records to return.int❌ No

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    managed_systems: "{{ lookup('beyondtrust.password_safe.managed_systems_list', api_url=api_url,
      client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print Managed Systems list
      debug:
        msg: "{{ managed_systems }}"
    - name: Print system01 Managed System
      debug:
        msg: "{{ managed_systems | selectattr('SystemName', 'equalto', 'system01') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all managed systems.list

Lookup Plugin: databases_list

Short Description

Retrieve databases list from Password Safe.

Description

Custom lookup plugin to fetch databases list from Password Safe.

Parameters

NameDescriptionTypeRequiredDefault
api_urlBeyondTrust Password Safe API URL.str✅ Yes
api_versionThe recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.str❌ No3.0
client_idAPI OAuth Client IDstr✅ Yes
client_secretAPI OAuth Client Secret.str✅ Yes
log_levelLog file's log level (INFO, DEBUG, WARNING, ERROR).str❌ NoDEBUG
log_file_nameLog file's namestr❌ Noansible-collection-modules-logs
verify_caControls SSL certificate verification for the Secrets Safe instance. Set to C(true) or C(false) to enable/disable verification, or provide a string path to a CA bundle file (that is, C(/etc/pki/tls/certs/ca-bundle.crt)) to verify against a specific certificate authority. Only set to C(false) for testing purposes in trusted environments.bool/str❌ NoTrue

Example

---
- vars:
    # PASSWORD_SAFE_API_URL, PASSWORD_SAFE_CLIENT_ID and PASSWORD_SAFE_CLIENT_SECRET are environment variables.
    api_url: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_API_URL') }}"
    client_id: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_ID') }}"
    client_secret: "{{ lookup('ansible.builtin.env', 'PASSWORD_SAFE_CLIENT_SECRET') }}"
    databases: "{{ lookup('beyondtrust.password_safe.databases_list', api_url=api_url, client_id=client_id, client_secret=client_secret) }}"
  tasks:
    - name: Print databases list
      debug:
        msg: "{{ databases }}"
    - name: Print test database
      debug:
        msg: "{{ databases | selectattr('InstanceName', 'equalto', 'test') | first }}"

Return values

NameDescriptionReturnedTypeSample
_listlist of all databases.list

©2003-2026 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.