Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.1password.dev/llms.txt

Use this file to discover all available pages before exploring further.

The 1Password Connect Ansible collection contains modules that allow you to interact with your 1Password Connect deployment from Ansible playbooks. The modules communicate with the Connect API to support managing 1Password vaults and items through create, read, update, and delete operations.

​
Requirements

You must complete the following requirements before you can use the 1Password Connect Ansible collection:

​
Get started

Use the following instructions to get started with the 1Password Ansible collection:
  1. Install the 1Password collection.
  2. Use the 1Password collection in an Ansible playbook.
  3. Explore the example playbooks.

​
Step 1: Install the collection

Install the onepassword.connect collection from Ansible Galaxy. 
ansible-galaxy collection install onepassword.connect
The 1Password Ansible collection is also available for the Red Hat Ansible Automation Platform.

​
Step 2: Use the collection in an Ansible task

Use the onepassword.connect collection in an Ansible task:
  1. Add onepassword.connect to the task collections.
    playbook.yaml
    collections:
    - onepassword.connect  # Specify the 1Password collection
  2. Provide the Connect server access token using the token variable in the Ansible task or the OP_CONNECT_TOKEN environment variable. You must set this value in each Ansible task. It’s best practice to use a local variable to provide the Connect server access token because it’s more secure. The following example sets the connect_token variable to the Connect token value, then references it for the token field.
    playbook.yaml
    vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
collections:
    - onepassword.connect  # Specify the 1Password collection
tasks:
    - onepassword.connect.generic_item:
        token: "{{ connect_token }}"
  3. Provide the Connect server hostname, IP address, or URL through the hostname variable in the Ansible task or the OP_CONNECT_HOST environment variable. You must set this value in each Ansible task.
    playbook.yaml
    environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
collections:
    - onepassword.connect  # Specify the 1Password collection

​
Examples

Explore the following examples to learn how to perform specific tasks:

​
Create an item

The following example uses the generic_item module to create a 1Password item. It also creates the Random Code value with a custom generator_recipe.
playbook.yaml
- name: Create 1Password Secret
  hosts: localhost
  vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
  environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
  collections:
      - onepassword.connect  # Specify the 1Password collection
  tasks:
    - onepassword.connect.generic_item:
        token: "{{ connect_token }}"  # Pass the Connect server access token variable
        vault_id: "<vault-id>"  # Set the 1Password vault ID
        title: Club Membership
        state: present
        fields:
          - label: Codeword
            value: "hunter2"
            section: "Personal Info"
            field_type: concealed
          - label: Random Code
            generate_value: on_create  # Generate the value on creation
            generator_recipe:
                length: 16
                include_symbols: no
      no_log: true  # Turn off logs to avoid logging sensitive data
      register: op_item # Note: register is Ansible syntax

​
Update an item

The following example uses the generic_item module to update a 1Password item. It also sets the generate_value setting to always, which means 1Password generates a new value for the field each time you run the playbook.
The update operation completely replaces the item matching the title or uuid field. You will lose any properties that you don’t provide in the task definition.To avoid losing data, store the items created by Ansible in a vault that’s scoped in a way that only the Connect server can access it.
playbook.yaml
- name: Update a 1Password Secret
  hosts: localhost
  vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
  environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
    OP_VAULT_ID: "<vault-id>"  # Set the 1Password vault ID
  collections:
      - onepassword.connect  # Specify the 1Password collection
  tasks:
    - onepassword.connect.generic_item:
        token: "{{ connect_token }}"  # Pass the Connect server access token variable
        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  # Generate a new value every time the playbook runs
            generator_recipe:  # Provide a custom password recipe
                length: 16
                include_symbols: no
      no_log: true  # Turn off logs to avoid logging sensitive data

​
Find an item by name

The following example uses the item_info module to find a 1Password item by name.
playbook.yaml
  hosts: localhost
  vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
  environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
  collections:
    - onepassword.connect  # Specify the 1Password collection
  tasks:
    - name: Find the item with the label "Staging Database" in the vault "Staging Env"
      item_info:
        token: "{{ connect_token }}"
        item: Staging Database
        vault: Staging Env
      no_log: true  # Turn off logs to avoid logging sensitive data
      register: op_item

​
Get the value of a field

The following example uses the field_info module to get the value of a specific field in a 1Password item.
playbook.yaml
  hosts: localhost
  vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
  environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
  collections:
    - onepassword.connect  # Specify the 1Password collection
  tasks:
    - name: Find a field labeled "username" in an item named "MySQL Database" in a specific vault
      field_info:
        token: "{{ connect_token }}"  # Pass the Connect token variable
        item: MySQL Database
        field: username
        vault: <vault-id>  # Set the 1Password vault ID
      no_log: true  # Turn off logs to avoid logging sensitive data
      register: op_item
    - name: Print the field definition
      ansible.builtin.debug:
        msg: "{{ op_item.field }}"

​
Reference

Refer to the following sections to learn about the available variables and modules.

​
Variables

All modules support the following variable definitions. You can either explicitly define the value on the Ansible task or let Ansible fall back to an environment variable to use the same value across all tasks.
Module variableEnvironment variableDescription
hostnameOP_CONNECT_HOSTSpecifies the hostname, IP address, or URL where your Connect server is deployed.
tokenOP_CONNECT_TOKENSpecifies the string value of your Connect server access token.
vault_idOP_VAULT_ID(Optional) The UUID of a 1Password vault. It must be a vault the Connect server token has access to.
Module variables take precedence over environment variables. If you plan to use an environment variable, make sure the corresponding module variable is absent.

​
Modules

The 1Password Ansible collection has the following modules:

​
generic_item

You can use the generic_item module to create, update, and delete 1Password items.
State is importantThe generic_item module follows Ansible’s present/absent state pattern. Behavior when the state is present (state: present):
  • If the module can’t find a matching item by its uuid or title, it creates a new item with the defined values.
  • If the module finds a matching item on the server, it completely replaces the old item with a new item defined by the playbook values.
Behavior when the state is absent (state: absent):
  • If the module can’t find the item by its uuid or title, no action is taken.
  • If the module finds an item matching the uuid or title, it deletes the item. Otherwise, no action is taken.
When you use the generic_item module to create or update a 1Password item, you can have 1Password generate a field’s value. You can specify one of three settings for generate_value:
generate_value settingEffect
never (Default)Don’t generate the field value. Use the value parameter instead.
on_createGenerate the value when creating the field.
alwaysGenerate a new value for the field every time the playbook is run. Overwrites the value parameter.
The following example generates a value (with a custom recipe) for the Random Code field by using the on_create setting and supplying a custom generator_recipe.
playbook.yaml
- name: Create 1Password Secret
  hosts: localhost
  vars:
    connect_token: "<connect-server-token>"  # Set the Connect server access token
  environment:
    OP_CONNECT_HOST: <connect-host>  # Set the Connect server hostname
  collections:
      - onepassword.connect  # Specify the 1Password collection
  tasks:
    - onepassword.connect.generic_item:
        token: "{{ connect_token }}"  # Pass the Connect token variable
        vault_id: "<vault-id>"  # Set the 1Password vault ID (optional)
        title: Club Membership
        state: present
        fields:
          - label: Codeword
            value: "hunter2"
            section: "Personal Info"
            field_type: concealed
          - label: Random Code
            generate_value: on_create  # Generate the field value on creation
            generator_recipe:  # Provide a custom password recipe
                length: 16
                include_digits: no
      no_log: true  # Turn off logs to avoid logging sensitive data
      register: op_item

​
item_info

Use the item_info module to search for or get information about a 1Password item (such as the fields or metadata).
When you search for an item, 1Password first searches for the uuid (if it’s provided), then searches for the title. When searching for an item by its title, the module uses a case-sensitive, exact-match query.

​
field_info

Use the onepassword.connect.field_info module to get the value of an item field. The field_info module first finds the item by title or UUID, then searches for the requested field by name. If you provide a section, the module only searches within that item section. If you don’t provide a section, the field name must be unique within the item. The search method compares field names using the unicodedata.normalize function and the NKFD form.

​
Best practices

Consider the following best practices when using the 1Password Ansible collection.

​
Turn off task logging

It’s best practice to turn off task logging for any tasks that interact with 1Password Connect. Ansible might print sensitive information if no_log is unset or set to false. To turn off logging, set no_log to true:
playbook.yaml
collections:
      - onepassword.connect  # Specify the 1Password collection
tasks:
  - name: Find the item with the label "Staging Database" in the vault "Staging Env"
    item_info:
      token: "{{ connect_token }}"  # Pass the Connect token variable
      item: Staging Database
      vault: Staging Env
    no_log: true  # Turn off logs to avoid logging sensitive data
    register: op_item

​
Avoid using environment variables for sensitive information

It’s best practice to use a local variable to set sensitive information, such as the Connect server access token, because Ansible environment variables are normally passed in plain text.