diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 580dc8eb..1c42b07f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ terraform { } provider "onepassword" { - url = "http://<1Password Connect API Hostname>" + service_account_token = "<1Password service account token>" } ``` diff --git a/README.md b/README.md index d0b2888e..20c19a5c 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ terraform { } provider "onepassword" { - url = "http://localhost:8080" + service_account_token = "<1Password service account token>" } variable "vault_id" {} diff --git a/docs/index.md b/docs/index.md index ceb9a15a..0ecebf88 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,6 +17,8 @@ You must install [1Password CLI](https://developer.1password.com/docs/cli) on th ## Use with 1Password CLI +:warning: Minimum [1Password CLI version](https://app-updates.agilebits.com/product_history/CLI2) `v2.23.0` is required. + Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault. Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account. @@ -27,7 +29,9 @@ terraform apply `-parallelism=n` ### Authenticate CLI with service account -To authenticate CLI with service account, set `service_account_token` in the provider configuration. +To authenticate CLI with service account: +1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account) +2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration. ### Authenticate the CLI with user account using biometric unlock @@ -39,14 +43,15 @@ URL EMAIL USER ID acme.dev.com test.user@acme.com HERE_WILL_BE_REAL_USER_ID acme.prod.com prod.user@acme.com HERE_WILL_BE_REAL_USER_ID ``` -3. Set `account` in the provider configuration with the `URL` or `USER ID` value from the previous step. +3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step. 4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in). ## Use with 1Password Connect To use the provider with 1Password Connect you need to 1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment) -2. Set `url` and `token` in the provider configuration. +2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration. +3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration. ## Example Usage @@ -60,13 +65,22 @@ provider "onepassword" { } ``` +You can set each of the configuration options using environment variables. +Environment variables are a more secure way to set configuration options because they prevent accidentally pushing sensitive values to the project repo. + +- `OP_CONNECT_HOST` - The URL where your 1Password Connect API can be found. +- `OP_CONNECT_TOKEN` - A valid token for your 1Password Connect API. +- `OP_SERVICE_ACCOUNT_TOKEN` - A valid 1Password service account token to use with 1Password CLI +- `OP_ACCOUNT` - A valid account's sign-in address or ID to use with 1Password CLI and biometrics unlock. +- `OP_CLI_PATH` - The path to the 1Password CLI binary. + ## Schema ### Optional -- `account` (String) A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from OP_ACCOUNT. Must be set to use with biometric unlock. -- `op_cli_path` (String) The path to the 1Password CLI binary. Can also be sourced from OP_CLI_PATH. Defaults to `op`. -- `service_account_token` (String) A valid token for your 1Password Service Account. Can also be sourced from OP_SERVICE_ACCOUNT_TOKEN. Must be set to use with 1Password service account. -- `token` (String) A valid token for your 1Password Connect API. Can also be sourced from OP_CONNECT_TOKEN. Must be set to use with 1Password Connect server. -- `url` (String) The HTTP(S) URL where your 1Password Connect API can be found. Must be provided through the OP_CONNECT_HOST environment variable if this attribute is not set. Must be set to use with 1Password Connect server. +- `account` (String) A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from `OP_ACCOUNT` environment variable. Provider will use the 1Password CLI if set. +- `op_cli_path` (String) The path to the 1Password CLI binary. Can also be sourced from `OP_CLI_PATH` environment variable. Defaults to `op`. +- `service_account_token` (String) A valid 1Password service account token. Can also be sourced from `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Provider will use the 1Password CLI if set. +- `token` (String) A valid token for your 1Password Connect server. Can also be sourced from `OP_CONNECT_TOKEN` environment variable. Provider will use 1Password Connect server if set. +- `url` (String) The HTTP(S) URL where your 1Password Connect server can be found. Can also be sourced `OP_CONNECT_HOST` environment variable. Provider will use 1Password Connect server if set. diff --git a/examples/README.md b/examples/README.md index 0521d572..6e449e41 100644 --- a/examples/README.md +++ b/examples/README.md @@ -3,16 +3,49 @@ This example demonstrates creating the currently supported types of 1Password Items (Logins, Passwords, and Databases). ## Prerequisites -To run this example you have to have either issue a 1Password service account token or setup a 1Password Connect API instance and issued a Connect Token with access to a demo vault. You will need to export both the Connect API token and the UUID of your demo vault as environment variables. +The 1Password Terraform provider supports using both [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server) +and [1Password CLI](https://developer.1password.com/docs/cli). -```sh -# to use service account, set -$ export OP_SERVICE_ACCOUNT_TOKEN="Put your 1Password service account token here" +You must install [1Password CLI](https://developer.1password.com/docs/cli) on the machine running Terraform to use it. Refer to the +[Terraform documentation](https://developer.hashicorp.com/terraform/cloud-docs/run/install-software#only-install-standalone-binaries) to learn how to install 1Password CLI on Terraform Cloud. + +## Use with 1Password CLI + +Minimum 1Password CLI version `v2.23.0` is required. + +Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault. +Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account. -# to use Connect, set -$ export OP_CONNECT_TOKEN="Put your 1Password Connect API token here" -$ export TF_VAR_demo_vault="Put a Vault UUID that has been added to your 1Password Connect API here" +It's recommended to limit the number of parallel resource operations. It can be done by using `-parallelism=n` flag when running `terraform apply`, where `n` is the number of parallel resource operations (the default is `10`). ``` +terraform apply `-parallelism=n` +``` + +### Authenticate CLI with service account + +To authenticate CLI with service account: +1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account) +2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration. + +### Authenticate the CLI with user account using biometric unlock + +To authenticate the CLI with user account using biometric unlock: +1. [Turn on the app integration](https://developer.1password.com/docs/cli/app-integration/#step-1-turn-on-the-app-integration) +2. In the terminal run `op account ls` to find sign-in address or account ID. It will print similar output in the console: +``` +URL EMAIL USER ID +acme.dev.com test.user@acme.com HERE_WILL_BE_REAL_USER_ID +acme.prod.com prod.user@acme.com HERE_WILL_BE_REAL_USER_ID +``` +3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step. +4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in). + +## Use with 1Password Connect + +To use the provider with 1Password Connect you need to +1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment) +2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration. +3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration. ## Create the Items diff --git a/onepassword/provider.go b/onepassword/provider.go index c958e1fd..13a08de4 100644 --- a/onepassword/provider.go +++ b/onepassword/provider.go @@ -44,31 +44,31 @@ func Provider() *schema.Provider { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc("OP_CONNECT_HOST", nil), - Description: "The HTTP(S) URL where your 1Password Connect API can be found. Must be provided through the OP_CONNECT_HOST environment variable if this attribute is not set. Must be set to use with 1Password Connect server.", + Description: "The HTTP(S) URL where your 1Password Connect server can be found. Can also be sourced `OP_CONNECT_HOST` environment variable. Provider will use 1Password Connect server if set.", }, "token": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc("OP_CONNECT_TOKEN", nil), - Description: "A valid token for your 1Password Connect API. Can also be sourced from OP_CONNECT_TOKEN. Must be set to use with 1Password Connect server.", + Description: "A valid token for your 1Password Connect server. Can also be sourced from `OP_CONNECT_TOKEN` environment variable. Provider will use 1Password Connect server if set.", }, "service_account_token": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc("OP_SERVICE_ACCOUNT_TOKEN", nil), - Description: "A valid token for your 1Password Service Account. Can also be sourced from OP_SERVICE_ACCOUNT_TOKEN. Must be set to use with 1Password service account.", + Description: "A valid 1Password service account token. Can also be sourced from `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Provider will use the 1Password CLI if set.", }, "account": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc("OP_ACCOUNT", nil), - Description: "A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from OP_ACCOUNT. Must be set to use with biometric unlock.", + Description: "A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from `OP_ACCOUNT` environment variable. Provider will use the 1Password CLI if set.", }, "op_cli_path": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc("OP_CLI_PATH", "op"), - Description: "The path to the 1Password CLI binary. Can also be sourced from OP_CLI_PATH. Defaults to `op`.", + Description: "The path to the 1Password CLI binary. Can also be sourced from `OP_CLI_PATH` environment variable. Defaults to `op`.", }, }, DataSourcesMap: map[string]*schema.Resource{ diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 46fa5c5f..1ea25c61 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -17,6 +17,8 @@ You must install [1Password CLI](https://developer.1password.com/docs/cli) on th ## Use with 1Password CLI +:warning: Minimum [1Password CLI version](https://app-updates.agilebits.com/product_history/CLI2) `v2.23.0` is required. + Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault. Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account. @@ -27,7 +29,9 @@ terraform apply `-parallelism=n` ### Authenticate CLI with service account -To authenticate CLI with service account, set `service_account_token` in the provider configuration. +To authenticate CLI with service account: +1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account) +2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration. ### Authenticate the CLI with user account using biometric unlock @@ -39,17 +43,27 @@ URL EMAIL USER ID acme.dev.com test.user@acme.com HERE_WILL_BE_REAL_USER_ID acme.prod.com prod.user@acme.com HERE_WILL_BE_REAL_USER_ID ``` -3. Set `account` in the provider configuration with the `URL` or `USER ID` value from the previous step. +3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step. 4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in). ## Use with 1Password Connect To use the provider with 1Password Connect you need to 1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment) -2. Set `url` and `token` in the provider configuration. +2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration. +3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration. ## Example Usage {{tffile "examples/provider/provider.tf"}} +You can set each of the configuration options using environment variables. +Environment variables are a more secure way to set configuration options because they prevent accidentally pushing sensitive values to the project repo. + +- `OP_CONNECT_HOST` - The URL where your 1Password Connect API can be found. +- `OP_CONNECT_TOKEN` - A valid token for your 1Password Connect API. +- `OP_SERVICE_ACCOUNT_TOKEN` - A valid 1Password service account token to use with 1Password CLI +- `OP_ACCOUNT` - A valid account's sign-in address or ID to use with 1Password CLI and biometrics unlock. +- `OP_CLI_PATH` - The path to the 1Password CLI binary. + {{ .SchemaMarkdown | trimspace }}