Ansible Lookup

CE

Pro

Cloud

The passbolt Ansible lookup plugin retrieves secrets from your passbolt instance inside your playbooks, so credentials never appear in your playbooks or version control. It is a read-only lookup: it fetches and decrypts resources, it does not create or update them.

Requirements

• A passbolt server v5 with encrypted metadata enabled; the resources you look up must use the v5 (encrypted metadata) format.
• On the control node: ansible-core 2.20.1, which the repository's requirements.txt pins alongside ansible 13.2.0, the GnuPG binary, and the python-gnupg, requests and jsonschema Python packages, pinned in the same file. The collection declares no minimum Python version, and its container image is built on Python 3.12.

Install

The collection is not published on Ansible Galaxy yet. Install it from the git repository:

ansible-galaxy collection install git+https://github.com/passbolt/passbolt-ansible-lookup-plugin.git#/passbolt/passbolt_lookup/

Pin a revision in production

An installation from git follows the main branch, and there is no tagged release yet. For a reproducible production setup, pin a specific revision:

ansible-galaxy collection install git+https://github.com/passbolt/passbolt-ansible-lookup-plugin.git#/passbolt/passbolt_lookup/,<commit>

Configure the plugin

The plugin authenticates with your account kit and your passphrase.

Step 1. Download your account kit from the passbolt web interface, in Profile > Desktop app setup > Download your account kit. The kit is a signed file bundling everything needed for authentication; treat it as a secret.

Step 2. Store the kit content and your passphrase as Ansible Vault variables:

ansible-vault encrypt_string --name 'vault_passbolt_account_kit' "$(cat /path/to/your-account-kit)"
ansible-vault encrypt_string --name 'vault_passbolt_passphrase' 'your-passphrase'

Step 3. Expose them to the plugin through the passbolt variable block, which is where the plugin reads its configuration:

vars:
  passbolt:
    account_kit: "{{ vault_passbolt_account_kit }}"
    passphrase: "{{ vault_passbolt_passphrase }}"

Both variables are mandatory: a missing one fails the task with "Variable 'passbolt.account_kit' is required but not provided."

Two optional keys sit in the same block:

• skip_ssl_verification, a boolean defaulting to false, skips the TLS certificate verification on the calls to the passbolt API. Read the default the right way round: the plugin passes the opposite of this option to its HTTP client, so false means verification is active, which is the setting you want.
• timeout, an integer defaulting to 30, is the number of seconds to wait for the passbolt API to reply. It applies to each HTTP request rather than to the lookup as a whole, and one lookup makes several, the authentication sequence included, so a slow instance can keep a task waiting considerably longer than the value you set.

There are no native environment variables. On a CI runner where the secrets live in the runner's secret store, bridge them in the playbook:

vars:
  passbolt:
    account_kit: "{{ lookup('env', 'PASSBOLT_ACCOUNT_KIT') }}"
    passphrase: "{{ lookup('env', 'PASSBOLT_PASSPHRASE') }}"

note

The plugin has no multi-factor authentication support: a lookup with an account under an enforced MFA policy fails. Use an automation account that is not subject to MFA enforcement.

Retrieve a secret

Each lookup opens its own API session and logs out afterwards; no API tokens persist between calls. The GnuPG keys it imports do persist, see the security recommendations below. The recommended form is by resource id, which you can read in the web interface URL when a resource is open: https://your-domain/app/passwords/view/<uuid>.

- name: Fetch the database credentials
  ansible.builtin.set_fact:
    db_secret: "{{ lookup('passbolt.passbolt_lookup.passbolt_lookup', 'cf496fdd-5c02-4094-9ca7-6da98d8bde9f') }}"
  no_log: true

- name: Use them
  ansible.builtin.template:
    src: db.conf.j2
    dest: /etc/app/db.conf
  vars:
    db_password: "{{ db_secret.password }}"

The lookup returns the whole decrypted resource as a single flat dictionary, and your playbook picks what it needs. The possible keys are name, username, password, description, note, uris, totp and custom_fields. Empty fields are omitted, so no key is guaranteed to be present: guard optional fields with a Jinja default.

A resource that cannot be found, or that is not shared with your account, fails the task with an error; the lookup never returns an empty result silently. Use ignore_errors or a rescue block if a missing resource is acceptable in your play.

Search by name, username or URI

Instead of an id, you can pass one or more filters:

"{{ lookup('passbolt.passbolt_lookup.passbolt_lookup', name='acme-db-production', username='app') }}"

The name, username and uri filters match exactly and are case-sensitive; when several are supplied, all must match. Two caveats:

• First match wins. Resource names are not unique in passbolt: when several readable resources match, the plugin returns the first one in server pagination order, without warning. For production playbooks, pin lookups by id, or supply enough filters to make the match unique.
• Slower than an id lookup. A filter search walks your resources and decrypts metadata until it finds a match. The passbolt session keys cache makes this fast once warm; the cache is filled as your clients (web, mobile, desktop) open resources, so a search over resources no client has ever opened stays slow. An id lookup is always a single round-trip and a single decryption.

When a play needs the same filtered lookup several times, resolve it once at the top of the play and reuse the result with set_fact, as in the example above.

Security recommendations

• Keep the account kit and the passphrase in Ansible Vault, and never in plain variables or inventory.
• Add no_log: true on tasks that receive secrets, so decrypted values do not land in the Ansible output or CI logs.
• The plugin imports your private key (and, for shared resources, metadata keys) into the GnuPG keyring of the user running Ansible, and does not remove them. Treat the control node as a durable holder of the key: use a dedicated system user for automation, or point GNUPGHOME at a dedicated directory in the environment.
• Prefer a dedicated passbolt account for automation, shared only on the resources your playbooks need.
• Pin the collection to a specific git revision, as shown above.

Going further

The plugin's README, in the passbolt-ansible-lookup-plugin repository, covers the full option reference and error behaviours.