Use Connect with Ansible

The 1Password Connect Ansible collection contains modules that allow you to interact with your 1Password Connect deployment from Anisble 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:

• Create and deploy a Connect server.
• Install Ansible version 7.x or later.
• Install Ansible Core version 2.14 or later.
• Install Python version 3.8 or later.

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.

info

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

2. Provide the Connect server token through 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 set the Connect server token because it's more secure. The following example sets the connect_token variable to the Connect server token value, then references it for the token field.

   playbook.yaml

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

Examples

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

• Create an item.
• Update an item.
• Find an item by name.
• Get the value of a field.

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

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.

caution

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

Find an item by name

The following example uses the item_info module to find a 1Password item by name.

playbook.yaml

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

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 variable	Environment variable	Description
hostname	OP_CONNECT_HOST	Specifies the hostname, IP address, or URL where your Connect server is deployed.
token	OP_CONNECT_TOKEN	Specifies the string value of your Connect server token.
vault_id	OP_VAULT_ID	(Optional) The UUID of a 1Password vault. It must be a vault the Connect server token has access to.

caution

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 module
• item_info module
• field_info module

generic_item

You can use the generic_item module to create, update, and delete 1Password items.

State is important

The 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 setting	Effect
never (Default)	Don't generate the field value. Use the value parameter instead.
on_create	Generate the value when creating the field.
always	Generate 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

item_info

Use the item_info module to search for or get information about a 1Password item (such as the fields or metadata).

info

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.
• Avoid using environment variables for sensitive information.

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

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 token, because Ansible environment variables are normally passed in plain text.