Skip to content

Commit

Permalink
Merge pull request #121 from 1Password/update-documentation
Browse files Browse the repository at this point in the history 
Update documentation
  • Loading branch information
@volodymyrZotov
volodymyrZotov committed Dec 12, 2023
2 parents d5367ac + 65f8662 commit f1958d9
Show file tree
Hide file tree
Showing 6 changed files with 86 additions and 25 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ terraform {
}
provider "onepassword" {
url = "http://<1Password Connect API Hostname>"
service_account_token = "<1Password service account token>"
}
```

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ terraform {
}
provider "onepassword" {
url = "http://localhost:8080"
service_account_token = "<1Password service account token>"
}
variable "vault_id" {}
Expand Down
30 changes: 22 additions & 8 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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 generated by tfplugindocs -->
## 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.
47 changes: 40 additions & 7 deletions examples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 5 additions & 5 deletions onepassword/provider.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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{
Expand Down
20 changes: 17 additions & 3 deletions templates/index.md.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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 }}

0 comments on commit f1958d9

Please sign in to comment.