The 1Password Connect collection contains modules that interact with your 1Password Connect deployment. The modules communicate with the 1Password Connect API to support Vault Item create/read/update/delete operations.

You can learn more about Secrets Automation and 1Password Connect on our website.

• Requirements
• Installation
• Module & Environment Variables
• generic_item Module
• item_info Module
• field_info Module
• Testing
• About 1Password
• Security

• Python >= 3.6.0
• 1Password Connect >= 1.0.0

This collection has been tested against the following Ansible versions:

• ansible-core: >=2.9, 2.11, 2.12
• ansible: >=4.0, <5.0

You can install the Ansible collection from Ansible Galaxy:

ansible-galaxy collection install onepassword.connect

All modules support the following variable definitions. You may either explicitly define the value on the task or let Ansible fallback to an environment variable to use the same value across all tasks.

Environment variables are ignored if the module variable is defined for a task.

🔥 Warning 🔥 It is strongly recommended you define no_log: true on any tasks that interact with 1Password Connect. Ansible may print sensitive data if no_log is not set.

Create a new Item

---
- name: Create 1Password Secret
  hosts: localhost
  environment:
    OP_CONNECT_HOST: http://localhost:8001
    OP_CONNECT_TOKEN: "api.jwt.here"
  tasks:
    - onepassword.connect.generic_item:
        vault_id: "qwerty56789asdf"
        title: Club Membership
        state: present
        fields:
          - label: Codeword
            value: "hunter2"
            section: "Personal Info"
            field_type: concealed
          - label: Random Code
            generate_value: on_create
            generator_recipe:
                length: 16
                include_letters: yes
                include_digits: yes
                include_symbols: no
      no_log: true
      register: op_item

The generic_item module follows Ansible's present/absent state pattern.

• state: present
  • If the module cannot find a matching Item by its uuid or title, a new item is created with the defined values.
  • If the module finds a matching Item on the server, it will completely replace the old Item with a new Item defined by the playbook values.
• state:absent
  • If the Item cannot be found, no action is taken.
  • If the Item is found, it is deleted. Otherwise, no action is taken.

Search order for an existing Item

1. Search by the Item's uuid, if provided.
2. Search by title, using a case-sensitive, exact-match query.

1Password can generate a field's value on the user's behalf when creating or updating an Item. Because generating random values is not idempotent, the user can specify one of three settings for generate_value:

Update an Item

❗️Note❗ The update operation will completely replace the Item matching the title or uuid field. Any properties not provided in the task definition will be lost.

We recommend storing the Items created by Ansible in a Vault that only 1Password Connect may access.

---
- name: Update a 1Password Secret
  hosts: localhost
  environment:
    OP_CONNECT_HOST: http://localhost:8001
    OP_CONNECT_TOKEN: "valid.jwt.here"
    OP_VAULT: "zyzzyz1234example"
  tasks:
    - onepassword.connect.generic_item:
        title: Club Membership
      # uuid: 1ff75fa9fexample  -- or use an Item ID to locate an item instead
        state: present
        fields:
          - label: Codeword
            field_type: concealed
          - label: Dashboard Password
            generate_value: always  # new value is generated every time playbook is run
            generator_recipe:
                length: 16
                include_symbols: no
      no_log: true

Get information about an Item, including fields and metadata.

Find an Item by Name

--- 
  hosts: localhost
  environment:
    OP_CONNECT_HOST: http://localhost:8001
    OP_CONNECT_TOKEN: "valid.jwt.here"
  collections:
    - onepassword.connect
  tasks:
    - name: Find the item with the label "Staging Database" in the vault "Staging Env"
      item_info:
        item: Staging Database
        vault: Staging Env
      no_log: true
      register: op_item

{
    "changed": false,
    "failed": false,
    "op_item": {
        "category": "SERVER",
        "createdAt": "2020-11-23T15:29:07.312397-08:00",
        "fields": {
            "Test": {
                "id": "j6ao3EXAMPLEvmzbrtre",
                "label": "Test",
                "type": "STRING",
                "value": ".........."
            },
            "notesPlain": {
                "id": "notesPlain",
                "label": "notesPlain",
                "purpose": "NOTES",
                "type": "STRING"
            }
        },
        "id": "bactwEXAMPLEpxhpjxymh7yy",
        "tags": [],
        "title": "Test Item 2",
        "updatedAt": "2020-11-23T15:29:07.312397-08:00",
        "vault": {
            "id": "4ktuuifg2ad7m4vEXAMPLEm"
        }
    }
}

Use the onepassword.connect.field_info module to get the value of an item field.

The field_info module will first find the item by name or UUID, then search for the requested field by name. If a section is provided, the module will only search within that item section. If no section is provided, the field name must be unique within the item.

The search method compares field names using the unicodedata.normalize function and the NKFD form.

---
  hosts: localhost
  environment:
    OP_CONNECT_HOST: http://localhost:8001
    OP_CONNECT_TOKEN: "valid.jwt.here"
  collections:
    - onepassword.connect
  tasks:
    - name: Find a field labeled "username" in an item named "MySQL Database" in a specific vault.
      onepassword.connect.field_info:
      item: MySQL Database
      field: username
      vault: 2zbeu4smcibizsuxmyvhdh57b6
    no_log: true
    register: op_item

    - name: Print the field definition
      ansible.builtin.debug:
        var: "{{ op_item.field }}"

{
    "value": "mysql_username_example",
    "section": "",
    "id": "fb3b40ac85f5435d26e"
}

Use the test Makefile target to run unit tests:

make test

For more information about testing, see tests/README.md

1Password is a privacy-focused password manager that keeps you safe online.

By combining industry-leading security and award-winning design, the company provides private, secure, and user-friendly password management to businesses and consumers globally. More than 60,000 business customers trust 1Password as their enterprise password manager.

1Password requests you practice responsible disclosure if you discover a vulnerability.

Please file requests via BugCrowd.

For information about security practices, please visit our Security homepage.