`linuxfabrik.lfops.bitwarden_item`¶

Create, update or fetch a Bitwarden login item

Synopsis¶

Looks up a Bitwarden login item by name (and optional username, folder, collection and organization), or directly by Bitwarden item ID, and creates or updates it as needed to match the given parameters.
When the item does not yet exist, it is created with the supplied values. When it exists but differs from the supplied values, it is updated in place. When it already matches, no API call is made and the module reports changed=false.
When id is set, only the lookup-by-ID path is used and all other search filters are ignored. The module fails if the ID does not exist - IDs are never auto-created.
When the lookup is by name and matches more than one item, the module fails because it cannot decide which item to operate on.
When name is omitted, a title is generated automatically as hostname - purpose (e.g. appsrv01 - MariaDB) or just hostname when no purpose is given.
On success, the module returns the full Bitwarden item object. username and password are additionally lifted to the top level so they can be addressed without going through the login sub-dictionary.
Items are read from a local on-disk cache backed by bw serve. A cached bw sync is performed at most every 60 seconds, so consecutive calls in the same play do not hammer the API.

Available since LFOps 1.0.0.

Requirements¶

Bitwarden CLI bw version v2022.9.0 or newer. See https://bitwarden.com/help/article/cli/ for installation instructions.
You must be logged in and unlocked (bw login followed by bw unlock), and have the local API running, e.g. bw serve --hostname 127.0.0.1 --port 8087. The module connects to 127.0.0.1:8087 by default.

Optional Parameters¶

attachments

List of local file paths to upload as attachments. The basename of each path is used as the attachment name in Bitwarden. Bitwarden allows duplicate attachment names, but this module does not, and fails if two paths share the same basename. Existing attachments with the same basename are assumed to have the same content and are not re-uploaded.
Type: List.

collection_id

Bitwarden collection ID the item belongs to. Used both as a search filter and, if the item has to be created, as the target collection.
Type: String.

folder_id

Bitwarden folder ID the item belongs to. Used both as a search filter and, if the item has to be created, as the target folder.
Type: String.

hostname

Hostname the password belongs to. Used to generate the item name when name is not given.
Type: String.

id

Operate on an existing item by its Bitwarden item ID. When set, all other search filters are ignored. The module fails if the ID does not exist (no auto-creation).
Type: String.

name

Explicit name/title of the item. When set, disables automatic name generation from hostname and purpose.
Type: String.

notes

Notes to set on the item. Bitwarden limits notes to 10000 characters. Updates on existing items overwrite previous notes.
Type: String.
Default: Generated by Ansible.

organization_id

Bitwarden organization ID the item belongs to. Used both as a search filter and, if the item has to be created, as the target organization.
Type: String.

password

Password to set on the login item. None (the default) leaves the password unmanaged - a new item gets no password and an existing item keeps its current one. Any non-None value is written on every run.
Type: String.

purpose

What the password is for (e.g. MariaDB, Rocky). Combined with hostname to build the item name when name is not given.
Type: String.

uris

List of URIs to set on the login item. The URI list is replaced on every run; omit only when you want the item to have no URIs.
Type: List.

username

Username to set on the login item. Used both as a search filter and, if the item has to be created or updated, as the login.username value.
Type: String.

Examples¶

- name: 'Get or create a password item from Bitwarden (automated name creation).'
  linuxfabrik.lfops.bitwarden_item:
    hostname: 'appsrv11'
    purpose: 'MariaDB'
    username: 'mariadb-admin'
  register: creds

- name: 'Add a password to the above item'
  linuxfabrik.lfops.bitwarden_item:
    hostname: 'appsrv11'
    purpose: 'MariaDB'
    username: 'mariadb-admin'
    password: 'linuxfabrik'
  register: creds

- debug:
    msg: 'ID: "{{ creds.id }}", Name: "{{ creds.name }}", Username: "{{ creds.username }}", Password: "{{ creds.password }}"'

- name: 'Change name/title of Bitwarden item by using the ID'
  linuxfabrik.lfops.bitwarden_item:
    id: '62b779ca-cb95-4d61-864d-ee670995686a'
    name: 'appsrv133 - New name'
  register: creds

# a full-fledged example
- name: 'Get or create a password item from Bitwarden (automated name creation).'
  linuxfabrik.lfops.bitwarden_item:
    collection_id: '4649ec03-c1be-4d5a-9413-7f7ad8ebbace'
    organization_id: '06c7691f-c64f-4140-8680-d4f60a9cb038'
    hostname: 'appsrv12'
    notes: 'please note'
    purpose: 'MariaDB'
    username: 'mariadb-admin'
    password: 'linuxfabrik'
    uris:
     - 'https://www.example.com'
     - 'https://www.example.org'
  register: creds

- name: 'Set multiple attachments. '
  linuxfabrik.lfops.bitwarden_item:
    hostname: 'appsrv11'
    purpose: 'MariaDB'
    attachments:
      - /tmp/file1
      - /tmp/file2
  register: creds

Return Values¶

collectionIds

List of collection IDs in which the item is.
Type: List.
Returned: always.
Sample:

yaml - 58a5a2ef-93ca-4ca3-81de-f9b0f2d947a7

favorite

Whether the item is favorited or not.
Type: Bool.
Returned: always.
Sample: False

folderId

Bitwarden folder ID in which the item is.
Type: String.
Returned: always.
Sample: 6fb1792a-dc44-4306-8669-aca5a8bb0e72

id

Unique Bitwarden password item ID.
Type: String.
Returned: always.
Sample: daba87c4-44d4-47ee-be7f-f21cb0fc8ea6

login

A Bitwarden login object (dictionary).
Type: Dictionary.
Returned: always.

name

Name/Title of the password item.
Type: String.
Returned: always.
Sample: appsrv01 - MariaDB

notes

Some notes about the cipher.
Type: String.
Returned: always.
Sample: Automatically generated by Ansible.

object

Type of the Bitwarden object. Always returns item.
Type: String.
Returned: always.
Sample: item

organizationId

The ID of the organization.
Type: String.
Returned: always.
Sample: 7845ea14-5364-4c62-82ba-383864e47889

password

The password. Same as under the login dict, but at a higher level for easier access.
Type: String.
Returned: always.
Sample: 6VuIkoKQmCl9Yyv3xpgjU6SF2ecs6k

reprompt

If Bitwarden should re-prompt for the master password when accessing this item.
Type: Number.
Returned: always.
Sample: 0

revisionDate

Date/Time the item was created or last modified.
Type: String.
Returned: always.
Sample: 2019-01-28T15:31:34.300Z

type

Bitwarden item type. Always 1 (login) for items handled by this module. Other Bitwarden types (2 secure note, 3 card, 4 identity) are filtered out and never returned.
Type: Number.
Returned: always.
Sample: 1