Hashicorp Vault 1Password Secrets Backend
This is a backend plugin to be used with Hashicorp Vault. This plugin allows for the retrieval, creation, and deletion of items stored in a 1Password vault accessed by use of the 1Password Connect.
Installation
Prerequisites:
- A basic understanding of Hashicorp Vault. Read this guide to get started with Vault.
- Hashicorp Vault Command Line Installed
- A running Vault server (However, for a Quickstart this guide does have instructions on running a
local
server with the 1Password secrets backend). - 1Password Connect deployed in your infrastructure.
The first step to using this plugin is to build it. Copy the binary to the plugin directory
of your choice. For example:
go build -o vault/plugins/op-connect .
This directory will be specified as the plugin_directory
in the Vault config used to start the server.
plugin_directory = "path/to/plugin/directory"
Start a Vault server with this config file:
vault server -config=path/to/config.json ...
Register the plugin with the Vault Server's plugin catalog:
vault write sys/plugins/catalog/secret/op-connect \
sha_256="$(shasum -a 256 path/to/plugin/directory/op-connect | cut -d " " -f1)" \
command="op-connect"
Enable the plugin:
vault secrets enable --plugin-name='op-connect' --path="op" plugin
...
Successfully enabled 'op-connect' at 'op'!
To check if your plugin has been registered you should be able to see the plugin when listing all registered plugins:
vault secrets list
Quickstart Local Installation
The first step to using this plugin is to build it. Copy the binary to your plugin directory
of your choice. For example:
go build -o vault/plugins/op-connect .
Run the vault server locally with a 1Password Connect plugin:
vault server -dev -dev-root-token-id=root -dev-plugin-dir=./vault/plugins -log-level=debug
Enable the plugin:
vault secrets enable --path="op" op-connect
To check if your plugin has been registered you should be able to see the plugin when listing all registered plugins:
vault secrets list
Plugin Configuration
In order to configure your plugin to access the 1Password Connect API, create a configuration json file:
{
"op_connect_host": "<host_address_of_1Password_Connect_API>",
"op_connect_token": "<API_token_for_1Password_Connect>"
}
Save the configuration file:
vault write op-connect/config @op-connect-config.json
Usage
Environment Variables
- OP_CONNECT_TOKEN (required if
op_connect_token
is not set in configuration): The API token created to be used to connect with the 1Password Connect API.
Commands
NOTE
If multiple 1Password vaults/items have the same title
when using a title in the access path, the desired action will be performed on the oldest vault/item. Furthermore, titles that include white space characters cannot be used.
Listing vaults available to the 1Password API token:
vault list op/vaults
Listing items stored in the specified vault:
# list vaults by id
vault list op/vaults/<vault_id_or_title>
Read item:
vault read op/vaults/<vault_id_or_title>/items/<item_id_or_title>
Create item (Please see the Creating and Updating Items section for more details on the json file contents):
vault write op/vaults/<vault_id_or_title>/items @some_json_file.json
Update item (Please see the Creating and Updating Items section for more details on the json file contents):
vault write op/vaults/<vault_id_or_title>/items/<item_id_or_title> @some_json_file.json
Delete item:
vault write op/vaults/<vault_id_or_title>/items/<item_id_or_title>
Creating and Updating Items Details
- category(required): Describes the category of the item to create. Currently supported are
database
,login
, andpassword
. - title(required on create): Specifies what the item will be titled.
- url: Specifies the url where the item may be used
- fields: Describes the fields to create for the item. Each field can be described with the following
- id: The id of the field to create.
- label: How the field will be titled in the UI
- type: The type of the field.
STRING
,EMAIL
,CONCEALED
,URL
,TOTP
,DATE
,MONTH_YEAR
, andMENU
are currently supported. - purpose: The purpose of the field.
""
,USERNAME
,PASSWORD
,NOTES
are currently supported. - value: The value of the field.
- generate: Used for fields with a password type. Set as true to have 1Password generate the value.
- entropy: Used for fields with a password type. Set as an integer value for passwords where you would like to specify the value.
- section: Describes what section to place the field. If not specified will be placed in the default section. Sections can be described with the following:
- section_id: The id of the section to create the item in
- sections: Describes what sections to create for the item
- id: The id of the section
- label: How the section will be titled in the UI
Example Login Item with custom section:
{
"category": "login",
"title": "Example Login",
"fields": [
{
"id": "username",
"label": "username",
"type": "STRING",
"purpose": "USERNAME",
"value": "my_user"
},
{
"id": "password",
"label": "password",
"purpose": "PASSWORD",
"type": "CONCEALED",
"value": "",
"generate": true
},
{
"id": "custom_field_id",
"type": "STRING",
"label": "My Custom Field",
"value": "my custom value",
"section": {
"id": "my_new_section"
}
}
],
"sections": [
{
"id": "my_new_section",
"label": "New Section"
}
]
}
Example Password Item:
{
"category": "password",
"title": "Example Password",
"fields": [
{
"id": "password",
"label": "password",
"purpose": "PASSWORD",
"type": "CONCEALED",
"value": "",
"generate": true
}
]
}
Example Database Item:
{
"category": "database",
"title": "Example Database",
"fields": [
{
"id": "username",
"label": "username",
"type": "STRING",
"purpose": "USERNAME",
"value": "my_user"
},
{
"id": "password",
"label": "password",
"purpose": "PASSWORD",
"type": "CONCEALED",
"value": "",
"generate": true
},
{
"id": "hostname",
"label": "hostname",
"type": "STRING",
"value": "my_host"
},
{
"id": "database",
"label": "database",
"type": "STRING",
"value": "my_database"
},
{
"id": "port",
"label": "port",
"type": "STRING",
"value": "8080"
}
]
}
Vault Enterprise Namespaces
The 1Password Secrets Backend supports Vault Enterprise Namespaces. If you are using a namespaced Vault, please note that the The 1Password Secrets Backend must be enabled for each namespace.
Enabling the plugin for a namespace can be done with the following command:
vault secrets enable -namespace=<namespace> op
The plugin also requires configuration in each namespace. Please refer to the Plugin Configuration section for example configuration.
Applying the configuration to a namespace can be done with the following command:
vault write -namespace=<namespace> op-connect/config @op-connect-config.json
For more information on Vault Namespaces please refer to the official Vault Enterprise Namespaces Documentation
Development
Running Tests
make test
Security
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.