# 1Password Secrets Automation Documentation > Service accounts, Connect server, CI/CD integrations, and Kubernetes operator documentation. This file contains all documentation content in a single document following the llmstxt.org standard. ## Load secrets from 1Password into CircleCI With the [1Password Secrets orb for CircleCI ](https://circleci.com/developer/orbs/orb/onepassword/secrets), you can securely load secrets from 1Password into CircleCI CI/CD pipelines using [secret references](/docs/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. [CircleCI orbs ](https://circleci.com/docs/orb-intro/) are packages containing YAML configuration files. Using an orb allows you to refer to these configurations with a single line of code. :::info The [1Password Secrets orb for CircleCI ](https://github.com/1password/secrets-orb) is officially supported and maintained by 1Password, but community contributions are welcome. ::: You can use the orb with a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/). See the video below for a brief introduction to using 1Password Service Accounts with CircleCI and Docker. ## Requirements The requirements for getting started with the 1Password for CircleCI orb vary depending on whether you use a service account or Connect server. **Service account:** Before you use 1Password for CircleCI with a service account, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/) - Create a [CircleCI ](https://circleci.com/) account. **Connect:** Before you use 1Password for CircleCI with a Connect server, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server.](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) - Create a [CircleCI ](https://circleci.com/) account. :::warning[caution] Connect credentials take precedence over service account credentials. If you've set the `OP_CONNECT_HOST` or `OP_CONNECT_TOKEN` environment variables alongside `OP_SERVICE_ACCOUNT_TOKEN`, the Connect credentials take precedence over the provided service account token. You must unset the Connect environment variables to make sure the action uses the service account token. ::: ## Get started **Service account:** 1. Set the service account token environment variable in CircleCI. On the [CircleCI settings page ](https://circleci.com/docs/introduction-to-the-circleci-web-app#project-settings), set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to token of the service account to use to load secrets. 2. Edit the CircleCI configuration file and make the following updates: - Update the [CircleCI `config.yml` file ](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. - Specify the version number or use `volatile` to use the latest version number. Add the onepassword/secrets orb to your `config.yml` file. ```yaml [{ "color": "tangerine", "lineNo": 2, "substr": "onepassword/secrets" }] title="config.yml" orbs: 1password: onepassword/secrets@1.0.0 ``` To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. ```yaml [{ "color": "lagoon", "lineNo": 2, "substr": "volatile" }] title="config.yml" orbs: 1password: onepassword/secrets@volatile ``` 3. Install 1Password CLI version **2.18.0 or later** as the first step of a CircleCI job using the 1password/install-cli [command](#commands). You must install the CLI in the pipeline for the 1Password CircleCI orb to function. Earlier versions of 1Password CLI don't support service accounts. Find the latest version number in the [1Password CLI release notes](https://releases.1password.com/developers/cli/). ```yaml title="config.yml" {3} [{ "lineNo": 3, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] steps: - 1password/install-cli: version: 2.x.x ``` 4. Use 1Password CLI commands in subsequent steps in the pipeline. See the following example `config.yml` files. Make sure to update `2.x.x` to [1Password CLI version 2.18.0 or later](https://releases.1password.com/developers/cli/). **Example 1:** ```yaml title="config.yml" {10} [{ "color": "dahlia", "lineNo": 9, "substr": "1password/install-cli" }, { "lineNo": 10, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli: version: 2.x.x - checkout - run: shell: op run -- /bin/bash environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` **Example 2:** ```yaml title="config.yml" {12} [{ "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }, { "lineNo": 12, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] description: Install 1Password CLI within a job and make it useable for all the commands following the installation. usage: version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli: version: 2.x.x - checkout - run: | docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) docker build -t company/app:${CIRCLE_SHA1:0:7} . docker push company/app:${CIRCLE_SHA1:0:7} workflows: deploy: jobs: - deploy ``` **Connect:** 1. Set the Connect server environment variables in CircleCI. On the [CircleCI settings page ](https://circleci.com/docs/introduction-to-the-circleci-web-app#project-settings), set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables for the Connect server to use to load secrets: - Set `OP_CONNECT_TOKEN` to the Connect server token. - Set `OP_CONNECT_HOST` to the Connect server hostname or IP address. 2. Edit the CircleCI configuration file. Update the [CircleCI `config.yml` file ](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. Make sure to specify the version number or use `volatile` to use the latest version number. Add the onepassword/secrets orb to your `config.yml` file. ```yaml [{ "color": "tangerine", "lineNo": 2, "substr": "onepassword/secrets" }] title="config.yml" orbs: 1password: onepassword/secrets@1.0.0 ``` To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. ```yaml [{ "color": "lagoon", "lineNo": 2, "substr": "volatile" }] title="config.yml" orbs: 1password: onepassword/secrets@volatile ``` 3. Install 1Password CLI. You must install [1Password CLI](/docs/cli/) in the pipeline for the 1Password CircleCI orb to function: - Install the CLI as the first step of a CircleCI job using the 1password/install-cli [command](#commands). - Use 1Password CLI commands in subsequent steps in the pipeline. See the following example `config.yml` files. **Example 1:** ```yaml title="config.yml" version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli - checkout - run: shell: op run -- /bin/bash environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` **Example 2:** ```yaml title="config.yml" [{ "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }] description: Install 1Password CLI within a job and make it useable for all the commands following the installation. usage: version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - 1password/install-cli - checkout - run: | docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) docker build -t company/app:${CIRCLE_SHA1:0:7} . docker push company/app:${CIRCLE_SHA1:0:7} workflows: deploy: jobs: - deploy ``` ## Reference The following sections document the 1Password for CircleCI orb [commands](#commands) and the [secret reference syntax](#secret-reference-syntax). ### Commands There are three commands to use when you configure your orb: `1password/install-cli`, `1password/exec`, and `1password/export`. :::warning[caution] Only some commands mask secrets. Both the `1password/exec` orb command and the [`op run`](/docs/cli/reference/commands/run/) shell wrapper automatically mask secrets from the CircleCI log output. If secrets accidentally get logged, 1Password replaces them with ``. The `1password/export` command doesn't mask secrets. ::: | Command | Description | Masks secrets | | ------- | -------- | ------- | | 1password/install-cli | Installs 1Password CLI. You must use this command as a step to use 1Password CLI commands in subsequent steps. | N/A | | 1password/exec | Loads secrets on demand and executes the commands requiring secrets. See [loading secrets with the `exec` command](#load-exec). | Yes | | 1password/export | Loads secrets with references exported in the environment and makes them available to subsequent steps of the job. See [loading secrets with the `export` command](#load-export). | No | ### Secret reference syntax You can make secrets available to CircleCI jobs and steps by including references to them in the environment using secret references. Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op://vault-name/item-name/[section-name/]field-name ``` Visit the [secret reference syntax](/docs/cli/secret-reference-syntax/) documentation to access examples and learn more about referencing secrets. ## Usage examples Explore the following sections to learn about specific use case examples for the 1Password CircleCI orb. - [Load secrets with `exec`](#load-exec) - [Load secrets with `export`](#load-export) ### Load secrets with the `exec` command {#load-exec} To load secrets with the `1password/exec` command: 1. Install 1Password CLI with 1password/install-cli. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the 1password/exec command to load secrets on demand and execute commands that require secrets. After you add the 1password/exec command as a step in your job, subsequent steps of the job can access secrets. The following example shows how to use the 1password/exec command to resolve variables at the job level. The `exec` command automatically masks any secrets or sensitive values that might be accidentally logged. ```yaml [{ "color": "tangerine", "lineNo": 16, "substr": "1password/exec" }, { "color": "dahlia", "lineNo": 14, "substr": "1password/install-cli" }, { "lineNo": 15, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] title="config.yml" version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key steps: - checkout - 1password/install-cli: version: 2.x.x - 1password/exec: command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` ### Load secrets with the `export` command {#load-export} To load secrets with the `1password/export` command: 1. Install 1Password CLI with 1password/install-cli. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the 1password/export command to load the [secret references](#secret-reference-syntax) exported in the environment. 3. Access secrets in subsequent steps of the job. The following example shows how to use the 1password/export command to resolve variables at the job level. ```yaml title="config.yml" url="https://github.com/1Password/secrets-orb/blob/main/src/examples/export.yml" [{ "color": "sunbeam", "lineNo": 13, "substr": "1password/export" }, { "color": "dahlia", "lineNo": 11, "substr": "1password/install-cli" }, { "lineNo": 12, "substr": "2.x.x", "editableId": "version-number", "label": "Version number" }] version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - checkout - 1password/install-cli version: 2.x.x - 1password/export: var-name: AWS_ACCESS_KEY_ID secret-reference: op://company/app/aws/access_key_id - 1password/export: var-name: AWS_SECRET_ACCESS_KEY secret-reference: op://company/app/aws/secret_access_key - run: command: | echo "This value will not be masked: $AWS_ACCESS_KEY_ID" echo "This value will not be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` --- ## Load secrets from 1Password into GitHub Actions With the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password), you can securely load secrets from 1Password into GitHub Actions using [secret references](/docs/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate `load-secrets-action` with a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/). See the video below for a brief introduction to using the GitHub Action with a service account. :::info Similar to regular [GitHub repository secrets ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions), 1Password automatically masks sensitive fields that appear in GitHub Actions logs. If one of these values accidentally gets printed, it's replaced with `***`. ::: ## Requirements You can configure the action to authenticate to 1Password with either a [service account](/docs/service-accounts/) or a [Connect server](/docs/connect/). **Service account:** Before using the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) with a service account, you must: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/) - Have the service account token on hand. **Connect:** Before using the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) with a Connect server, you must: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. - Have the Connect server hostname and Connect server token on hand. :::warning[caution] The [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) only supports Mac and Linux [runners ](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners). It doesn't work with Windows runners. ::: ## Get started The steps to get started vary depending on whether you use a service account or a Connect server. **Service account:** 1. Add the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to your workflow. See [Adding an action to your workflow ](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow). 2. Add the service account token to your workflow. Create a secret for your GitHub repository named OP_SERVICE_ACCOUNT_TOKEN and set it to the service account token value. Visit [Using secrets in GitHub Actions ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. 3. Configure your workflow. Use the `1password/load-secrets-action/configure` action to specify the token of the service account you plan to get secrets from. The following example uses the `configure` command to set the service-account-token to the OP_SERVICE_ACCOUNT_TOKEN secret. ```yaml title="config.yml" [{ "color": "tangerine", "lineNo": 3, "substr": "service-account-token" }, { "color": "bitsblue", "lineNo": 3, "substr": "OP_SERVICE_ACCOUNT_TOKEN"}] uses: 1password/load-secrets-action/configure@v2 with: service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} ``` :::tip Setting the service-account-token in the `configure` step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. To use the service account token in a specific step, set it in the `env` variables for that step. ```yaml title="config.yml" env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} ``` ::: 4. Load a secret. Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. The following example sets the SECRET environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 3, "substr": "SECRET" }] uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/hello-world/secret ``` The action makes the referenced secret available as the `SECRET` environment variable for the next steps. **Connect:** 1. Add the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) (`load-secrets-action`) to your workflow. See [Adding an action to your workflow ](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow). 2. Add the Connect server token to your workflow. Create a secret named OP_CONNECT_TOKEN in your repository and set it to the Connect server token value. Visit [Using secrets in GitHub Actions ](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. 3. Configure your workflow. Use the `1password/load-secrets-action/configure` action to specify the Connect server environment variable. The following example uses the configure command to: - Set the connect-host to the Connect server hostname (OP_CONNECT_HOST). - Set the connect-token to the OP_CONNECT_TOKEN secret. ```yaml title="config.yml" [{ "color": "dahlia", "lineNo": 3, "substr": "connect-host" }, { "color": "sunbeam", "lineNo": 3, "substr": "OP_CONNECT_HOST" }, { "color": "tangerine", "lineNo": 4, "substr": "connect-token" }, { "color": "bitsblue", "lineNo": 4, "substr": "OP_CONNECT_TOKEN" }] uses: 1password/load-secrets-action/configure@v2 with: connect-host: OP_CONNECT_HOST connect-token: ${{ secrets.OP_CONNECT_TOKEN }} ``` :::tip Setting the connect-token in the configure step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. To use the service account token in a specific step, set it in the `env` variables for that step. ```yaml title="config.yml" env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} ``` ::: 4. Load a secret. Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. The following example sets the SECRET environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 3, "substr": "SECRET" }] uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/hello-world/secret ``` The action makes the referenced secret available as the `SECRET` environment variable for the next steps. ## Reference The following sections document the [action inputs](#action-inputs) and [secret reference syntax](#secret-reference-syntax) for the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password). ### Action inputs The following table contains the available `configure` action inputs. | Action input | Environment variable | Description | | ----------------------- | -------------------------- | --------------------------------------------------------- | | `connect-host` | `OP_CONNECT_HOST` | The Connect server, hostname, IP address, or instance URL. | | `connect-token` | `OP_CONNECT_TOKEN` | The Connect server token. | | `service-account-token` | `OP_SERVICE_ACCOUNT_TOKEN` | The service account token. | ### Secret reference syntax Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/docs/cli/reference#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "vault-name" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "item-name" }, { "badge": 3, "color": "intrepidblue", "lineNo": 1, "substr": "section-name" }, { "badge": 4, "color": "dahlia", "lineNo": 1, "substr": "field-name" }] op://vault-name/item-name/[section-name/]field-name ``` Set an environment variable to a secret reference in your workflow YAML file, and the action will make the referenced secret available as the environment variable for the next steps. #### Example The following example shows how to reference the `secret-access-key` field of the `aws` item in the `app-cicd` vault. ```yaml title="config.yml" {4} [{ "badge": "1", "color": "sunbeam", "lineNo": 4, "substr": "app-cicd" },{ "badge": "2", "color": "lagoon", "lineNo": 4, "substr": "aws" },{ "badge": "3", "color": "dahlia", "lineNo": 4, "substr": "secret-access-key" }] - name: Load secret uses: 1password/load-secrets-action@v2 env: SECRET: op://app-cicd/aws/secret-access-key ``` - **Vault:** app-cicd - **Item:** aws - **Field:** secret-access-key ## Usage examples You can load secrets using the action in two ways: 1. [Use secrets from the action's output](#use-secrets-from-the-actions-output) 2. [Export secrets as environment variables](#export-secrets-as-environment-variables) ### Use secrets from the action's output You can use the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to access secrets as environment variables. **Service account:** The following examples show how to load a secret from a service account and print the output when a `push` event occurs. You need to set an ID for the step to access its outputs. See [`outputs.` ](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_id). **Simple example:** The following example shows how to use a service account to load (and print) a secret (as the SECRET env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 15, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret id: op-load-secret uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password (as DOCKERHUB_USERNAME and DOCKERHUB_TOKEN), then use them to log into Docker Hub. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 25, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 26, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 31, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 32, "substr": "DOCKERHUB_TOKEN"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Service Account uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Service Account Authorization token # for next steps. # Keep in mind that every single step in the job is now # able to access the token. service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} - name: Load Docker credentials id: load-docker-credentials uses: 1password/load-secrets-action@v2 with: export-env: false env: DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest ``` **Connect:** The following examples show how to load a secret from a Connect server and print the output when a `push` event occurs. **Simple example:** The following example shows how to use a Connect server to load (and print) a secret (as the SECRET env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 16, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret id: op-load-secret uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_CONNECT_HOST: connect-host OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password (as DOCKERHUB_USERNAME and DOCKERHUB_TOKEN), then use them to log into Docker Hub. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 24, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 25, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 30, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 31, "substr": "DOCKERHUB_TOKEN"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Connect uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Connect URL for next steps. You can also persist # the Connect token using input `connect-token`, but keep in mind that # every single step in the job would then be able to access the token. connect-host: OP_CONNECT_HOST - name: Load Docker credentials id: load-docker-credentials uses: 1password/load-secrets-action@v2 with: export-env: false env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest ``` ### Export secrets as environment variables You can use the [Load secrets from 1Password GitHub Action ](https://github.com/marketplace/actions/load-secrets-from-1password) to use loaded secret outputted from the `steps.step-id.outputs.secret-name`. **Service account:** The following examples show how to use a service account to load a 1Password secret as an environment variable. **Simple example:** The following example shows how to use a service account to load a secret as an environment variable named SECRET. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 15, "substr": "SECRET" }, { "color": "lagoon", "lineNo": 18, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: $SECRET"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, then uses them to log into Docker Hub. It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then uses them to deploy to AWS. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 25, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 26, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 31, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 32, "substr": "DOCKERHUB_TOKEN"}, { "badge": "3", "color": "lagoon", "lineNo": 51, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 52, "substr": "AWS_SECRET_ACCESS_KEY"}, { "badge": "3", "color": "lagoon", "lineNo": 55, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 55, "substr": "AWS_SECRET_ACCESS_KEY"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Service Account uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Service Account Authorization token # for next steps. # Keep in mind that every single step in the job is now able # to access the token. service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} - name: Load Docker credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ env.DOCKERHUB_USERNAME }} password: ${{ env.DOCKERHUB_TOKEN }} - name: Print environment variables with masked secrets run: printenv - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest - name: Load AWS credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true # Remove local copies of the Docker credentials, which are not needed anymore unset-previous: true env: AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key - name: Deploy app # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was # done automatically by the step above run: ./deploy.sh ``` **Connect:** The folowing examples show how to use a Connect server to load a secret from 1Password as an environment variable. **Simple example:** The following example shows how to use a Connect server to load a secret as an environment variable named SECRET. When you print a secret, 1Password automatically replaces it with `***`. ```yaml title="config.yml" [{ "color": "lagoon", "lineNo": 16, "substr": "SECRET" }, { "color": "lagoon", "lineNo": 19, "substr": "SECRET" }] on: push jobs: hello-world: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Load secret uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_CONNECT_HOST: connect-host OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} SECRET: op://app-cicd/hello-world/secret - name: Print masked secret run: 'echo "Secret: $SECRET"' # Prints: Secret: *** ``` **Advanced example:** The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named DOCKERHUB_USERNAME and DOCKERHUB_TOKEN, then uses them to log into Docker Hub. It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, then uses them to deploy to AWS. ```yaml title="config.yml" [{ "badge": "1", "color": "sunbeam", "lineNo": 26, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 27, "substr": "DOCKERHUB_TOKEN"}, { "badge": "1", "color": "sunbeam", "lineNo": 32, "substr": "DOCKERHUB_USERNAME"}, { "badge": "2", "color": "dahlia", "lineNo": 33, "substr": "DOCKERHUB_TOKEN"}, { "badge": "3", "color": "lagoon", "lineNo": 53, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 54, "substr": "AWS_SECRET_ACCESS_KEY"}, { "badge": "3", "color": "lagoon", "lineNo": 57, "substr": "AWS_ACCESS_KEY_ID"}, { "badge": "4", "color": "bitsblue", "lineNo": 57, "substr": "AWS_SECRET_ACCESS_KEY"}] on: push name: Deploy app jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Configure 1Password Connect uses: 1password/load-secrets-action/configure@v2 with: # Persist the 1Password Connect hostname for next steps. # You can also persist the Connect token using input # `connect-token`, but keep in mind that every single # step in the job would then be able to access the token. connect-host: OP_CONNECT_HOST - name: Load Docker credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} DOCKERHUB_USERNAME: op://app-cicd/docker/username DOCKERHUB_TOKEN: op://app-cicd/docker/token - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ env.DOCKERHUB_USERNAME }} password: ${{ env.DOCKERHUB_TOKEN }} - name: Print environment variables with masked secrets run: printenv - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest - name: Load AWS credentials uses: 1password/load-secrets-action@v2 with: # Export loaded secrets as environment variables export-env: true # Remove local copies of the Docker credentials, which are not needed anymore unset-previous: true env: OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key - name: Deploy app # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was # done automatically by the step above run: ./deploy.sh ``` ## Troubleshooting If you try to create items using 1Password CLI in your GitHub pipelines (without using `load-secrets-action`), the command fails with the following error: ```text variant="bad" Failed to create item: invalid JSON ``` For example, the following results in an error: ```shell variant="bad" op item create --category=login --title='My Example Item' --vault='Test' \ --url https://www.acme.com/login \ --generate-password=20,letters,digits \ username=jane@acme.com \ 'Test Field 1=my test secret' \ 'Test Section 1.Test Field2[text]=Jane Doe' \ 'Test Section 1.Test Field3[date]=1995-02-23' \ 'Test Section 2.Test Field4[text]='$myNotes ``` The pipeline environment is in piped mode. This triggers the CLI's pipe detection, which expects a piped input. To create items in this environment, use a [JSON template](/docs/cli/item-template-json/) with your item details. 1. Get the template for the category of item you want to create: ```shell op item template get --out-file=new-item.json ``` 2. Edit [the template](/docs/cli/item-template-json/) to add your information. 3. Pipe the item content to the command: ```shell cat new-item.json | op item create --vault ``` --- ## Load secrets from 1Password into Jenkins With the [1Password Secrets plugin for Jenkins ](https://plugins.jenkins.io/onepassword-secrets/), you can securely load secrets from 1Password as environment variables in a Jenkins CI/CD pipeline using [secret references](/docs/cli/secret-reference-syntax/). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate the plugin with a [1Password Service Account](/docs/service-accounts/) or a [1Password Connect Server](/docs/connect/). :::info The 1Password Jenkins plugin is officially supported and maintained by 1Password. Community contributions are welcome. [View the repository on GitHub. ](https://github.com/jenkinsci/onepassword-secrets-plugin) ::: ## Requirements You can use the 1Password Secrets plugin for Jenkins with either a [service account](/docs/service-accounts/get-started/) or a [Connect server](/docs/connect/get-started/). If you configure both a service account and a Connect server, the Connect server takes precedence. **Service account:** - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create a service account.](/docs/service-accounts/get-started/) - [Have a Jenkins instance up and running. ](https://www.jenkins.io/doc/) **Connect server:** - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Create and deploy a Connect server](/docs/connect/get-started/). - [Have a Jenkins instance up and running. ](https://www.jenkins.io/doc/) ## Get started To get started with the 1Password Secrets plugin for Jenkins: 1. [Install the 1Password Secrets plugin for Jenkins.](#install-plugin) 2. [Install 1Password CLI.](#step-2-install-1password-cli) 3. [Configure the 1Password Secrets plugin for Jenkins.](#configure-plugin) ### Step 1: Install the 1Password Secrets plugin for Jenkins {#install-plugin} You have several available options to install the 1Password Secrets plugin for Jenkins. You can use the Jenkins GUI (graphical user interface), the Jenkins CLI tool, or a direct upload. **Jenkins GUI:** To install the 1Password Secrets plugin for Jenkins using the GUI: 1. Sign in to your Jenkins instance. 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. 3. Select the **Available plugins** tab. 4. Search for *onepassword-secrets*. 5. Select the 1Password Secrets plugin for Jenkins, then select **Install**. Refer to [Use the GUI ](https://www.jenkins.io/doc/book/managing/plugins#from-the-web-ui) for more detailed instructions. **Jenkins CLI tool:** To install the 1Password Secrets plugin for Jenkins using the CLI tool: 1. Follow the [Use the CLI tool ](https://github.com/jenkinsci/plugin-installation-manager-tool) instructions. 2. Run the following command. Make sure to replace `1.0.0` with the correct version. ```sh jenkins-plugin-cli --plugins onepassword-secrets:1.0.0 ``` **Direct upload:** To install the 1Password Secrets plugin for Jenkins using a direct upload: 1. Download one of the [releases ](https://plugins.jenkins.io/onepassword-secrets#releases). 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. 3. Select the **Advanced** tab. 4. Select the `.hpi` file you downloaded from the release. 5. Select **Deploy**. Refer to [Use direct upload ](https://www.jenkins.io/doc/book/managing/plugins#advanced-installation) for more detailed instructions. ### Step 2: Install 1Password CLI The 1Password Secrets plugin for Jenkins relies on 1Password CLI. You must install 1Password CLI on the same machine that runs the Jenkins CI/CD pipeline. You can install 1Password CLI using a [Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) or using a Freestyle job. Either of these methods can install 1Password CLI in the same pipeline as the 1Password Secrets plugin for Jenkins or in a separate pipeline. :::info If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). ::: **Jenkinsfile:** To install 1Password CLI using a Jenkinsfile: 1. Sign in to your Jenkins instance. 2. Select **New Item**. 3. Enter the job details, then select **Pipeline**. 4. Configure the job details. 5. Scroll to **Advanced Project Options** > **Pipeline**. 6. Select **Pipeline script**. 7. Add the code to install 1Password CLI to the **Script** field. You can install 1Password CLI with a Jenkinsfile using declarative or scripted [Jenkins pipeline syntax ](https://www.jenkins.io/doc/book/pipeline/syntax/). :::info The following examples show how to install 1Password CLI version 2.24 on a Linux amd64 machine. Make sure to change the example scripts to match your platform and use the [latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). ::: **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" pipeline { agent any stages { stage('Install 1Password CLI') { steps { sh 'curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip"' sh 'unzip -o op.zip -d op-dir' sh 'mv -f op-dir/op /usr/local/bin' sh 'rm -r op.zip op-dir' } } } } # code-result [Pipeline] Start of Pipeline [Pipeline] node Running on Jenkins in /config/workspace/Example [Pipeline] { [Pipeline] stage [Pipeline] { (Install 1Password CLI) [Pipeline] sh + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip [Pipeline] sh + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op [Pipeline] sh + mv -f op-dir/op /usr/local/bin [Pipeline] sh + rm -r op.zip op-dir [Pipeline] } [Pipeline] // stage [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" node { stage('Install 1Password CLI') { sh ''' ARCH="amd64" curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" unzip -o op.zip -d op-dir mv -f op-dir/op /usr/local/bin rm -r op.zip op-dir ''' } } # code-result [Pipeline] Start of Pipeline [Pipeline] node Running on Jenkins in /config/workspace/Test 1Password Secrets [Pipeline] { [Pipeline] stage [Pipeline] { (Install 1Password CLI) [Pipeline] sh + ARCH=amd64 + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op + mv -f op-dir/op /usr/local/bin + rm -r op.zip op-dir [Pipeline] } [Pipeline] // stage [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS ``` 8. Save the build. **Freestyle job:** :::warning[caution] Freestyle jobs don't let you set both the configuration and secrets at the job level. 1Password recommends using a Jenkinsfile rather than a Freestyle job. See [Migrating from chained Freestyle jobs to Pipelines ](https://www.jenkins.io/blog/2016/06/29/from-freestyle-to-pipeline/). ::: To install 1Password CLI using a Freestyle job: 1. Sign in to your Jenkins instance. 2. Select **New Item**. 3. Enter the job name, then select **Freestyle project**. 4. Configure the job details. 5. Scroll to **Build Steps**, then select **Add build step** > **Execute shell**. 6. Add the following commands to the **Execute shell** build step. ```shell ARCH="amd64" curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" unzip -o op.zip -d op-dir mv -f op-dir/op /usr/local/bin rm -r op.zip op-dir # code-result Running as SYSTEM Building in workspace /config/workspace/Example [Test 1Password Secrets Freestyle] $ /bin/sh -xe /tmp/jenkins14763651031574634007.sh + ARCH=amd64 + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip + unzip -o op.zip -d op-dir Archive: op.zip extracting: op-dir/op.sig inflating: op-dir/op + mv -f op-dir/op /usr/local/bin + rm -r op.zip op-dir Finished: SUCCESS ``` 7. Save the build. ### Step 3: Configure the 1Password Secrets plugin for Jenkins {#configure-plugin} You can configure the 1Password Secrets plugin for Jenkins from the Jenkins dashboard: 1. Login to your Jenkins instance. 2. Select **Manage Jenkins** > **System**. 3. Scroll to **1Password Secrets**. 4. Set the **1Password CLI path** to the location of the 1Password CLI executable. The example script uses `/usr/local/bin/op`. The remaining configuration steps depend on whether you use a service account or a Connect server. **Service account:** You must add at least one Service Account Credential to use a service account with the 1Password Secrets plugin for Jenkins. 1. Select **Add** > **Jenkins** under the Service Account Credential. 2. Set the **Domain**. 3. Set the **Kind** to **Secret text**.The plugin only supports [secret text ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile#secret-text). 4. Set the **Scope**. 5. Set the **Secret** to the service account token. 6. You can leave the **ID** and **Description** empty. 7. Select **Add**. **Connect server:** You must specify the Connect Host value and add at least one Connect Credential to use a service account with the 1Password Secrets plugin for Jenkins. 1. Set **Connect Host** to the IP address, hostname, or URL of the Connect server. 2. Select **Add** > **Jenkins** under the Connect Credential. 3. Set the **Domain**. 4. Set the **Kind** to **Secret text**.The plugin only supports [secret text ](https://www.jenkins.io/doc/book/pipeline/jenkinsfile#secret-text). 5. Set the **Scope**. 6. Set the **Secret** to the Connect server token. 7. You can leave the **ID** and **Description** empty. 8. Select **Add**. For example configurations and pipeline scripts, go to [Usage examples](#usage-examples). :::info If you configure both a Connect server and a service account, the Connect server takes precedence. ::: ## Configuration The following sections document the available [configuration options](#configuration-options) and [configuration scopes](#configuration-scope). :::info If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). ::: ### Configuration options The 1Password Secrets plugin for Jenkins has configuration options for 1Password CLI, Connect servers, and service accounts. | Setting | Description | | ------------------------------ | ------------------------------------------------------------ | | **Connect Host** | The hostname, IP address, or URL of the Connect server. | | **Connect Credential** | The [Connect server token](/docs/connect/security#connect-server-access-tokens) to authenticate with the Connect server. This setting is a [Jenkins secret text credential ](https://www.jenkins.io/doc/book/using/using-credentials/). | | **Service Account Credential** | The [service account token](/docs/service-accounts/security#service-accounts-and-token-generation) to authenticate with the service account. This setting is a [Jenkins secret text credential ](https://www.jenkins.io/doc/book/using/using-credentials). | | **1Password CLI path** | The path to the 1Password CLI executable. The default location is `/usr/local/bin/op` | ### Configuration scope You can configure the 1Password Secrets plugin for Jenkins globally, per folder, or per job. | Level | Description | | ------ | ------------------------------------------------------------ | | Global | Global-level configurations impact all jobs in all folders. To configure the 1Password Secrets plugin for Jenkins globally, add it to your global configuration. | | Folder | Folder-level configurations impact all jobs within the folder. To configure the 1Password Secrets plugin for Jenkins for a specific folder, add it to the folder configuration. | | Job | Job-level configurations only impact the jobs you configure. To configure the 1Password Secrets plugin for Jenkins for a single job, configure the plugin in the Jenkinsfile or Freestyle job. | The configuration priority is highest for job-level configurations and lowest for global configurations. The more specific the level, the higher the priority. This means you can have a default configuration at a broader level and override it at more specific levels. For example, if you configure a service account (service account A) globally, but override it with a different service account (service account B) in a job-level configuration, the job will use the second service account (service account B). :::info If you configure both a Connect server and a service account, the Connect server takes precedence. ::: ## Usage examples The following sections cover several use case examples for the 1Password Secrets plugin for Jenkins: - [Use with a Jenkinsfile](#use-with-a-jenkinsfile) - [Use with environment variables](#use-with-environment-variables) - [Use in a Freestyle job](#use-in-a-freestyle-job) ### Use with a Jenkinsfile You can access secrets within the Jenkins pipeline using [secret references](/docs/cli/secret-reference-syntax/) with the `withSecrets` function. This function receives the configuration and list of 1Password secrets and loads them as parameters. Explore the following examples to learn how to use the `withSecrets` function in various contexts. **About the configuration step...** **Service account:** The configuration at the beginning of the Jenkinsfile to configure the service account and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). Make sure to replace service-account-token with the service account token and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). ```groovy [{ "badge": "πŸ”΄", "color": "red", "lineNo": 2, "substr": "service-account-token" }, { "badge": "🟒", "color": "green", "lineNo": 3, "substr": "op-cli-path" }] def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] ``` **Connect:** The configuration at the beginning of the Jenkinsfile to configure the Connect server and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). Make sure to replace connect-server-token with the Connect server token, connect-host with the Connect server IP address, and op-cli-path with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). ```groovy [{ "badge": "πŸ”΅", "color": "blue", "lineNo": 2, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 3, "substr": "connect-server-token" }, { "badge": "🟒", "color": "green", "lineNo": 4, "substr": "op-cli-path" }] def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] ``` **Service account:** The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Service Account. **Declarative Jenkinsfile:** The following [declarative Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#declarative-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Declarative Jenkinsfile" {18-23} [{ "badge": "πŸ”΄", "color": "red", "lineNo": 3, "substr": "service-account-token" }, { "badge": "🟒", "color": "green", "lineNo": 4, "substr": "op-cli-path" }] // Configure 1Password CLI and the service account. def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] pipeline { agent any stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** The following [scripted Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#scripted-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Scripted Jenkinsfile" {15-20} [{ "badge": "πŸ”΄", "color": "red", "lineNo": 4, "substr": "service-account-token" }, { "badge": "🟒", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] node { // Configure 1Password CLI and the service account def config = [ serviceAccountCredentialId: 'service-account-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } ``` **Connect server:** The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Connect Server. **Declarative Jenkinsfile:** The following [declarative Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#declarative-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Declarative Jenkinsfile" {19-24} [{ "badge": "πŸ”΅", "color": "blue", "lineNo": 3, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 4, "substr": "connect-server-token" }, { "badge": "🟒", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] // Configure 1Password CLI and the Connect server. def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] pipeline { agent any stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** The following [scripted Jenkinsfile ](https://www.jenkins.io/doc/book/pipeline/syntax#scripted-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. ```groovy title="Scripted Jenkinsfile" {16-21} [{ "badge": "πŸ”΅", "color": "blue", "lineNo": 4, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 5, "substr": "connect-server-token" }, { "badge": "🟒", "color": "green", "lineNo": 6, "substr": "op-cli-path" }] node { // Configure 1Password CLI and the Connect server. def config = [ connectHost: 'connect-host', connectCredentialId: 'connect-server-token', opCLIPath: 'op-cli-path' ] // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. def secrets = [ [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] ] stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets(config: config, secrets: secrets) { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } ``` :::tip Jenkins Pipeline Syntax helper You can also use the [Jenkins Pipeline Syntax helper](#use-in-a-freestyle-job) to create a pipeline script. ::: ### Use with environment variables The 1Password Secrets plugin for Jenkins lets you use [environment variables ](https://www.jenkins.io/doc/pipeline/tour/environment#using-environment-variables) to get configuration and secrets. The following examples show how to use environment variables with the 1Password Secrets plugin for Jenkins. You must set the environment variables in the `environment` block. The following table describes each environment variable. | Variable | Required | Description | | -------------------------- | ------------------------------------ | ------------------------------------------------------------ | | `OP_CLI_PATH` | Always required. | The path where you installed the 1Password CLI. If you followed the 1Password CLI installation instruction, set this value to `/usr/local/bin`.The example scripts on this page set this value to `op-cli-path`. | | `OP_SERVICE_ACCOUNT_TOKEN` | Required if using a service account. | The service account token of the service account to use.The example scripts on this page set this value to `service-account-token` variable. | | `OP_CONNECT_HOST` | Required if using a Connect server. | The IP address, hostname, or URL of the Connect server to use.The example scripts on this page set this value to `connect-server-host`. | | `OP_CONNECT_TOKEN` | Required if using a Connect server. | The Connect server token of the Connect server to use.The example scripts on this page set this value to `connect-server-token`. | If you don't configure these environment variables, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). **Service account:** The following examples show how to use a service account with environment variables in a Jenkinsfile. **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" [{ "badge": "πŸ”΄", "color": "red", "lineNo": 5, "substr": "service-account-token" }, { "badge": "🟒", "color": "green", "lineNo": 6, "substr": "op-cli-path" }] pipeline { agent any environment { // Configure 1Password CLI and the service account. OP_SERVICE_ACCOUNT_TOKEN = credentials('service-account-token') OP_CLI_PATH = 'op-cli-path' // Define the environment variables using the secret reference `op:///[/section]/`. DOCKER_USERNAME = 'op://vault/item/username' DOCKER_PASSWORD = 'op://vault/item/password' } stages{ stage('Push latest docker image') { steps { // Access 1Password secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" [{ "badge": "🟒", "color": "green", "lineNo": 4, "substr": "op-cli-path" }, { "badge": "πŸ”΄", "color": "red", "lineNo": 12, "substr": "service-account-token" }] node { def environment = [ // Configure 1Password CLI. 'OP_CLI_PATH = op-cli-path', // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. 'DOCKER_USERNAME=op://vault/item/username', 'DOCKER_PASSWORD=op://vault/item/password' ] // Define the service account token. def credentials = [ string(credentialsId: 'service-account-token', variable: 'OP_SERVICE_ACCOUNT_TOKEN') ] withEnv(environment) { withCredentials(credentials) { stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Connect server:** The following examples show how to use a Connect server with environment variables in a Jenkinsfile. **Declarative Jenkinsfile:** ```groovy title="Declarative Jenkinsfile" [{ "badge": "πŸ”΅", "color": "blue", "lineNo": 5, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 6, "substr": "connect-server-token" }, { "badge": "🟒", "color": "green", "lineNo": 7, "substr": "op-cli-path" }] pipeline { agent any environment { // Configure 1Password CLI and the Connect server. OP_CONNECT_HOST = 'connect-host' OP_CONNECT_TOKEN = credentials('connect-server-token') OP_CLI_PATH = 'op-cli-path' // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. DOCKER_USERNAME = 'op://vault/item/username' DOCKER_PASSWORD = 'op://vault/item/password' } stages{ stage('Push latest docker image') { steps { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` **Scripted Jenkinsfile:** ```groovy title="Scripted Jenkinsfile" [{ "badge": "πŸ”΅", "color": "blue", "lineNo": 4, "substr": "connect-host" }, { "badge": "🟣", "color": "purple", "lineNo": 12, "substr": "connect-server-token" }, { "badge": "🟒", "color": "green", "lineNo": 5, "substr": "op-cli-path" }] node { def environment = [ // Configure 1Password CLI and the Connect server. 'OP_CONNECT_HOST=connect-host', 'OP_CLI_PATH = op-cli-path', // Define the environment variables for the values of the secrets. // Use the secret reference syntax: `op:///[/section]/`. 'DOCKER_USERNAME=op://vault/item/username', 'DOCKER_PASSWORD=op://vault/item/password' ] def credentials = [ string(credentialsId: 'connect-server-token', variable: 'OP_CONNECT_TOKEN') ] withEnv(environment) { withCredentials(credentials) { stage('Push latest docker image') { // Use the `withSecrets` function to access secrets. withSecrets() { docker.withRegistry('http://somehost:5100') { sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' def image = docker.build('somebuild') image.push 'latest' } } } } } } ``` ### Use in a Freestyle Job You can use the Jenkins Pipeline Syntax helper to set [environment variables ](https://www.jenkins.io/doc/pipeline/tour/environment#using-environment-variables) and access secrets in a Freestyle job. **Service account:** Use the Jenkins Pipeline Syntax helper to use a service account in a Freestyle job: 1. From the Freestyle job in Jenkins, go to the **Steps** section. 2. Set **1Password CLI path** to the location where you installed 1Password CLI. The example script uses `/usr/local/bin/op`. 3. Set **Service Account Credential** to the service account token. 4. Select **Add a 1Password secret**. 5. Set the **Environment variable** for the secret. 6. Set **Secret reference**. Use the [secret reference syntax](/docs/cli/secret-reference-syntax/) to point to the 1Password secret. 7. Select **Generate Pipeline Script**. **Connect server:** Use the Jenkins Pipeline Syntax helper to use a Connect server in a Freestyle job: 1. From the Freestyle job in Jenkins, go to the **Steps** section. 2. Set **1Password CLI path** to the location where you installed 1Password CLI. The example script uses `/usr/local/bin/op`. 3. Set **Connect Host** to the Connect server IP address or hostname. 4. Set **Connect Credential** to the Connect server token. 5. Select **Add a 1Password secret**. 6. Set the **Environment variable** for the secret. 7. Set **Secret reference**. Use [secret references](/docs/cli/secret-reference-syntax/) to point to the 1Password secret. 8. Select **Generate Pipeline Script**. --- ## 1Password CI/CD Integrations You can use 1Password integrations to securely access secrets from 1Password in your CI/CD pipeline without exposing any plaintext secrets in code, and rotate secrets without having to update your CI/CD environment. ## Get started Select the CI/CD tool you use to get started. All integrations support authentication with both [1Password Connect Servers](/docs/connect/) and [1Password Service Accounts](/docs/service-accounts/). --- ## Use Connect with Ansible The [1Password Connect Ansible collection ](https://github.com/1Password/ansible-onepasswordconnect-collection) contains modules that allow you to interact with your 1Password Connect deployment from [Ansible ](https://docs.ansible.com/ansible/latest/getting_started/basic_concepts.html) playbooks. The modules communicate with the [Connect API](/docs/connect/api-reference/) 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.](/docs/connect/get-started/) - Install [Ansible ](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 7.x or later. - Install [Ansible Core ](https://docs.ansible.com/core.html) version 2.14 or later. - Install [Python ](https://www.python.org/downloads/) version 3.8 or later. ## Get started Use the following instructions to get started with the 1Password Ansible collection: 1. [Install the 1Password collection.](#step-1) 2. [Use the 1Password collection in an Ansible playbook.](#step-2) 3. Explore the [example playbooks](#examples). ### Step 1: Install the collection {#step-1} Install the `onepassword.connect` collection from [Ansible Galaxy. ](https://galaxy.ansible.com/onepassword/connect) ```shell ansible-galaxy collection install onepassword.connect ``` :::info The 1Password Ansible collection is also available for the [Red Hat Ansible Automation Platform. ](https://www.redhat.com/en/technologies/management/ansible) ::: ### Step 2: Use the collection in an Ansible task {#step-2} Use the `onepassword.connect` collection in an Ansible task: 1. Add `onepassword.connect` to the task `collections`. ```yaml {2} title="playbook.yaml" collections: - onepassword.connect # Specify the 1Password collection ``` 2. Provide the [Connect server access token](/docs/connect/concepts#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](#sensitive-data) to use a local variable to provide the Connect server access token because it's [more secure. ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) The following example sets the `connect_token` variable to the Connect token value, then references it for the token field. ```yaml {2,7} title="playbook.yaml" vars: connect_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. ```yaml {2} title="playbook.yaml" environment: OP_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.](#create-item) - [Update an item.](#update-item) - [Find an item by name.](#find-item-by-name) - [Get the value of a field.](#get-field-value) ### Create an item {#create-item} The following example uses the [`generic_item` module](#generic-item) to create a 1Password item. It also creates the `Random Code` value with a custom `generator_recipe`. ```yaml title="playbook.yaml" - name: Create 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_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: "" # 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 {#update-item} The following example uses the [`generic_item` module](#generic-item) 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. :::warning[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. ::: ```yaml title="playbook.yaml" - name: Update a 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname OP_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 {#find-item-by-name} The following example uses the [`item_info` module](#item-info) to find a 1Password item by name. ```yaml title="playbook.yaml" hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_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 {#get-field-value} The following example uses the [`field_info` module](#field-info) to get the value of a specific field in a 1Password item. ```yaml title="playbook.yaml" hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_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: # 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](#variables) and [modules](#modules). ### Variables All [modules](#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 access 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. | :::warning[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](#generic-item) - [`item_info` module](#item-info) - [`field_info` module](#field-info) #### `generic_item` {#generic-item} You can use the `generic_item` module to create, update, and delete 1Password items. :::warning[State is important] The `generic_item` module follows [Ansible's `present`/`absent` state pattern. ](https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#always-mention-the-state) 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`. ```yaml {20-24} title="playbook.yaml" - name: Create 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_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: "" # 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` {#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` {#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` ](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) function and the `NKFD` form. ## Best practices Consider the following best practices when using the 1Password Ansible collection. - [Turn off task logging.](#turn-off-logging) - [Avoid using environment variables for sensitive information.](#sensitive-data) ### Turn off task logging {#turn-off-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`: ```yaml {9} title="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 {#sensitive-data} It's best practice to use a local variable to set sensitive information, such as the Connect server access token, because [Ansible environment variables ](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) are normally passed in plain text. --- ## 1Password Connect Server API reference :::info If you're new to 1Password Secrets Automation and 1Password Connect Server, [learn how to get started with a Secrets Automation workflow](/docs/connect/get-started/). ::: You can use the Connect API to work with the vaults and items in your account, and to list API activity on a Connect server: - [List vaults](#list-vaults) - [Get vault details](#get-vault-details) - [List items](#list-items) - [Add an item](#add-an-item) - [Get item details](#get-item-details) - [Replace an item](#replace-an-item) - [Delete an item](#delete-an-item) - [Update a subset of item attributes](#update-a-subset-of-item-attributes) - [List files](#list-files) - [Get file details](#get-file-details) - [Get file content](#get-file-content) - [List API activity](#list-api-activity) To view the API in another tool, download the [1Password Connect API specification file (1.8.1)](https://i.1password.com/media/1password-connect/1password-connect-api_1.8.1.yaml). ## Requirements Before you can use the 1Password Connect Server API, you'll need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - [Set up a Secrets Automation workflow.](/docs/connect/get-started#step-1). - [Deploy 1Password Connect](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. ## Request headers Each request to the API has to be authenticated with an [access token](/docs/connect/manage-connect#manage-access-tokens). Provide it and specify the content type: ``` Authorization: Bearer Content-type: application/json ``` ## List vaults ``` GET /v1/vaults ``` ### Path parameters No path parameters ### Query parameters Parameter Type Description `filter` string Filter the vault collection using SCIM-style filters. Vaults can only be filtered by `name`. Optional. For example: `name eq "Demo Vault"` ### Responses
200
Returns an array of vault names and IDs
401
Invalid or missing token
## Get vault details ``` GET /v1/vaults/{vaultUUID} ``` ### Path parameters {#get-vaults-vaultuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve items from. ### Query parameters {#get-vaults-vaultuuid-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-responses}
200
Returns a Vault object
401
Invalid or missing token
403
Unauthorized access
404
Vault not found
## List items ``` GET /v1/vaults/{vaultUUID}/items ``` ### Path parameters {#get-vaults-vaultuuid-items-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to get the details of. ### Query parameters {#get-vaults-vaultuuid-items-query-parameters} Parameter Type Description `filter` string Filter the item collection using SCIM-style filters . Items can only be filtered by `title` or `tag`. Optional. For example: `title eq "Example Item"` or `tag eq "banking"` ### Responses
200
Returns an array of Item objects that don't include sections and fields
401
Invalid or missing token
404
Vault not found
## Add an item ``` POST /v1/vaults/{vaultUUID}/items ``` The request must include a FullItem object, containing the information to create the item. For example: ```json { "vault": { "id": "ftz4pm2xxwmwrsd7rjqn7grzfz" }, "title": "Secrets Automation Item", "category": "LOGIN", "tags": [ "connect", "\ud83d\udc27" ], "sections": [ { "label": "Security Questions", "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" } ], "fields": [ { "value": "wendy", "purpose": "USERNAME" }, { "purpose": "PASSWORD", "generate": true, "recipe": { "length": 55, "characterSets": [ "LETTERS", "DIGITS" ] } }, { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "CONCEALED", "generate": true, "label": "Recovery Key" }, { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "generate": true, "label": "Random Text" }, { "type": "URL", "label": "Example", "value": "https://example.com" } ] } ``` Parameter Type Description `title` string The title of the item. `vault` object An object containing an `id` property whose value is the UUID of the vault the item is in. `category` string The category of the item. One of:
`"LOGIN"` `"PASSWORD"` `"API_CREDENTIAL"` `"SERVER"` `"DATABASE"` `"CREDIT_CARD"` `"MEMBERSHIP"` `"PASSPORT"` `"SOFTWARE_LICENSE"` `"OUTDOOR_LICENSE"` `"SECURE_NOTE"` `"WIRELESS_ROUTER"` `"BANK_ACCOUNT"` `"DRIVER_LICENSE"` `"IDENTITY"` `"REWARD_PROGRAM"` `"EMAIL_ACCOUNT"` `"SOCIAL_SECURITY_NUMBER"` `"MEDICAL_RECORD"` `"SSH_KEY"`
You can't create items using the "CUSTOM" or "DOCUMENT" categories. `urls` array Array of URL objects containing URLs for the item. `favorite` boolean Mark the item as a favorite. `tags` string An array of strings of the tags assigned to the item. `fields` array An array of Field objects of the fields to include with the item. `sections` array An array of Section objects of the sections to include with the item. ### Path parameters {#post-vaults-vaultuuid-items-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to create an item in. ### Query parameters {#post-vaults-vaultuuid-items-query-parameters} No query parameters. ### Responses
200
Returns Item object containing the new item
400
Unable to create item due to invalid input
401
Invalid or missing token
403
Unauthorized access
404
Item not found
## Get item details ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-items-itemuuid-responses}
200
Returns an Item object
401
Invalid or missing token
403
Unauthorized access
404
Item not found
## Replace an item ``` PUT /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#put-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to replace. ### Query parameters {#put-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#put-vaults-vaultuuid-items-itemuuid-responses}
200
Returns an Item object
400
Unable to create item due to invalid input
401
Invalid or missing token
403
Unauthorized access
404
Item not found
## Delete an item ``` DELETE /v1/vaults/{vaultUUID}/items/{itemUUID} ``` ### Path parameters {#delete-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to delete. ### Query parameters {#delete-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#delete-vaults-vaultuuid-items-itemuuid-responses}
204
Successfully deleted an item
401
Invalid or missing token
403
Unauthorized access
404
Item not found
## Update a subset of item attributes ``` PATCH /v1/vaults/{vaultUUID}/items/{itemUUID} ``` Applies an `add`, `remove`, or `replace` operation on an item or the fields of an item. Uses the [RFC6902 JSON Patch](https://tools.ietf.org/html/rfc6902) document standard. Parameter Type Description `op` string The kind of operation to perform. One of: `add` `remove` `replace` `path` string An RFC6901 JSON Pointer to the item, an item attribute, an item field by field ID, or an item field attribute. For example: `"/fields/vy09gd8EXAMPLE/label"` `value` any The new value to apply at the path. ### Path parameters {#patch-vaults-vaultuuid-items-itemuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault the item is in. `itemUUID` string The UUID of the item to update. ### Query parameters {#patch-vaults-vaultuuid-items-itemuuid-query-parameters} No query parameters. ### Responses {#patch-vaults-vaultuuid-items-itemuuid-responses}
200
Returns an Item object of the updated item.
401
Invalid or missing token
403
Unauthorized access
404
Item not found
## List files ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to get the details of. `itemUUID` string The UUID of the item to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-query-parameters} Parameter Type Description `inline_content` boolean Whether to return the Base-64 encoded file content. The file size must be less than `OP_MAX_INLINE_FILE_SIZE_KB`, or 100 kilobytes if the file size isn't defined. Optional. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-responses}
200
Returns an array of File objects
401
Invalid or missing token
404
Item not found
413
File too large to display inline
## Get File details ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID} ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve the file from. `fileUUID` string The UUID of the file to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-query-parameters} Parameter Type Description `inline_content` boolean Whether to return the Base-64 encoded file content. The file size must be less than `OP_MAX_INLINE_FILE_SIZE_KB`, or 100 kilobytes if the file size isn't defined. Optional. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-responses}
200
Returns a File object
401
Invalid or missing token
403
Unauthorized access
404
File not found
413
File too large to display inline
## Get file content ``` GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID}/content ``` ### Path parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-path-parameters} Parameter Type Description `vaultUUID` string The UUID of the vault to retrieve the item from. `itemUUID` string The UUID of the item to retrieve the file from. `fileUUID` string The UUID of the file to retrieve. ### Query parameters {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-query-parameters} No query parameters. ### Responses {#get-vaults-vaultuuid-items-itemuuid-files-fileuuid-content-responses}
200
Returns the content of the file
401
Invalid or missing token
403
Unauthorized access
404
File not found
## List API activity ``` GET /v1/activity ``` Retrieve a list of API Requests that have been made. ### Query parameters {#get-activity-query-parameters} Parameter Type Description `limit` integer How many API Events should be retrieved in a single request. Optional. `offset` integer How far into the collection of API Events should the response start. Optional. ## Server Heartbeat ``` GET /heartbeat ``` Simple "ping" endpoint to check whether server is active. ### Query parameters {#get-heartbeat-query-parameters} No query parameters. ### Responses {#get-heartbeat-responses}
200
Returns a `text/plain` response with a single "."
## Server Health ``` GET /health ``` Query the state of the server and its service dependencies. ### Query parameters No query parameters. ### Responses {#get-heartbeat-responses}
200
Returns a Server Health object
## Metrics ``` GET /metrics ``` Returns Prometheus metrics collected by the server. ### Query parameters No query parameters. ### Responses {#get-heartbeat-responses}
200
Returns a plaintext list of Prometheus metrics. See the Prometheus documentation for specifics.
## Response object models ### APIRequest object Parameter Type Description `requestID` string The UUID for the request. `timestamp` dateTime Date and time of the request. `action` string The action taken. One of: `"READ"` `"CREATE"` `"UPDATE"` `"DELETE"` `result` string The result of the action. One of: `"SUCCESS"` `"DENY"` `actor` object An Actor object. `resource` object A Resource object. #### APIRequest: Actor object Parameter Type Description `id` string The UUID of the Connect server that made the request. `account` string The UUID of the 1Password account the request went to. `jti` string The UUID of the access token used to authenticate the request. `userAgent` string The user agent string specified in the request. `ip` string The IP address the request originated from. #### APIRequest: Resource object Parameter Type Description `type` string The resource requested. One of: `"ITEM"` `"VAULT"` `vault` object An object containing an `id` property with the value of the UUID of the vault requested. `item` object An object containing an `id` property with the value of the UUID of the item requested. `itemVersion` integer The version of the item. ### ErrorResponse object ```json { status: 401, message: "Invalid or missing token" } ``` Parameter Type Description `status` integer The HTTP status code. `message` string A message detailing the error. ### Vault object ```json { "id": "ytrfte14kw1uex5txaore1emkz", "name": "Demo", "attributeVersion": 1, "contentVersion": 72, "items": 7, "type": "USER_CREATED", "createdAt": "2021-04-10T17:34:26Z", "updatedAt": "2021-04-13T14:33:50Z" } ``` Parameter Type Description `id` string The UUID of the vault. `name` string The name of the vault. `description` string The description for the vault. `attributeVersion` integer The version of the vault metadata. `contentVersion` integer The version of the vault contents. `items` integer Number of active items in the vault. `type` string The type of vault. One of: `"EVERYONE"`: The team Shared vault. `"PERSONAL"`: The Private vault for the Connect server. `"USER_CREATED"`: A vault created by a user. `createdAt` dateTime Date and time when the vault was created. `updatedAt` dateTime Date and time when the vault or its contents were last changed. ### Item object ```json { "id": "2fcbqwe9ndg175zg2dzwftvkpa", "title": "Secrets Automation Item", "tags": [ "connect", "\ud83d\udc27" ], "vault": { "id": "ftz4pm2xxwmwrsd7rjqn7grzfz" }, "category": "LOGIN", "sections": [ { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562", "label": "Security Questions" } ], "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "wendy" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "mjXehR*uCj!aoe!iktt9KMtWb", "entropy": 148.0838165283203, "passwordDetails": { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain" }, { "id": "a6cvmeqakbxoflkgmor4haji7y", "type": "URL", "label": "Example", "value": "https://example.com" }, { "id": "boot3vsxwhuht6g7cmcx4m6rcm", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "CONCEALED", "label": "Recovery Key", "value": "s=^J@GhHP_isYP>LCq?vv8u7T:*wBP.c" }, { "id": "axwtgyjrvwfp5ij7mtkw2zvijy", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "label": "Random Text", "value": "R)D~KZdV!8?51QoCibDUse7=n@wKR_}]" } ], "files": [ { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", }, { "id": "oyez5gf6xjfptlhc3o4n6o6hvm", "name": "samplefile.png", "size": 296639, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/oyez5gf6xjfptlhc3o4n6o6hvm/content", } ], "createdAt": "2021-04-10T17:20:05.98944527Z", "updatedAt": "2021-04-13T17:20:05.989445411Z" } ``` Parameter Type Description `id` string The UUID of the item. `title` string The title of the item. `vault` object An object containing an `id` property whose value is the UUID of the vault the item is in. `category` string The category of the item. One of:
`"LOGIN"` `"PASSWORD"` `"API_CREDENTIAL"` `"SERVER"` `"DATABASE"` `"CREDIT_CARD"` `"MEMBERSHIP"` `"PASSPORT"` `"SOFTWARE_LICENSE"` `"OUTDOOR_LICENSE"` `"SECURE_NOTE"` `"WIRELESS_ROUTER"` `"BANK_ACCOUNT"` `"DRIVER_LICENSE"` `"IDENTITY"` `"REWARD_PROGRAM"` `"DOCUMENT"` `"EMAIL_ACCOUNT"` `"SOCIAL_SECURITY_NUMBER"` `"MEDICAL_RECORD"` `"SSH_KEY"`
You can't create items using the "CUSTOM" or "DOCUMENT" categories. `urls` array Array of URL objects containing URLs for the item. `favorite` boolean Whether the item is marked as a favorite. `tags` array An array of strings of the tags assigned to the item. `version` integer The version of the item. `createdAt` dateTime Date and time when the item was created. `updatedAt` dateTime Date and time when the vault or its contents were last changed. `lastEditedBy` string UUID of the account that last changed the item. #### Item: Field object ```json { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "generate": true, "label": "Random Text" } ``` Parameter Type Description `purpose` or `type` string Use `purpose` for the username, password, and notes fields. Possible values:
`"USERNAME"` `"PASSWORD"` `"NOTES"`
Use `type` for all other fields. Possible values are:
`"STRING"` `"EMAIL"` `"CONCEALED"` `"URL"` `"OTP"` (format: `otpauth://`) `"DATE"` (format: `YYYY-MM-DD`) `"MONTH_YEAR"` (format: `YYYYMM` or `YYYY/MM`) `"MENU"`
`value` string The value to save for the field. You can specify a `generate` field instead of `value` to create a password or other random information for the value. `generate` boolean Generate a password and save in the value for the field. By default, the password is a 32-characters long, made up of letters, numbers, and symbols. To customize the password, include a `recipe` field. `recipe` object A GeneratorRecipe object. `section` object An object containing the UUID of a section in the item. #### Item: File object ```json { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", "content": "VGhlIGZ1dHVyZSBiZWxvbmdzIHRvIHRoZSBjdXJpb3VzLgo=", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, } ``` Name Type Description `id` string The UUID of the file. `name` string The name of the file. `size` integer The size of the file in bytes. `content_path` string The path to download the contents of the file. `content` string The Base64-encoded contents of the file, if `inline_files` is set to `true`. `section` object An object containing the UUID of a section in the item. #### Item: GeneratorRecipe object The recipe is used in conjunction with the "generate" property to set the character set used to generate a new secure value. ```json { "length": 55, "characterSets": [ "LETTERS", "DIGITS" ] } ``` Name Type Description `length` integer The length of the password to generate. Optional. `characterSets` array An array containing of the kinds of characters to include. Optional. Possible values: `"LETTERS"` `"DIGITS"` `"SYMBOLS"` `excludeCharacters` string A list of all characters that should be excluded from generated passwords. Optional. #### Item: PasswordDetails object ```json { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } ``` Name Type Description `entropy` integer The unpredictability of the password, measured in bits. `generated` boolean Whether the password was generated using the password generator. `strength` string The strength of the password. One of: `"TERRIBLE"` `"WEAK"` `"FAIR"` `"GOOD"` `"VERY_GOOD"` `"EXCELLENT"` `"FANTASTIC"` `history` array An array of strings containing the previous passwords of the item. #### Item: Section object ```json { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" "label": "Security Questions", } ``` Name Type Description `id` string A unique identifier for the section. `label` string The label for the section. #### Item: URL object ```json { "label": "website", "primary": true, "href": "https://example.com" } ``` Name Type Description `label` string The label for the URL. `primary` boolean Whether this is the primary URL for the item. `href` string The address. ### Server Health object ```json { "name": "1Password Connect API", "version": "1.2.1", "dependencies": [ { "service": "sync", "status": "TOKEN_NEEDED" }, { "service": "sqlite", "status": "ACTIVE", "message": "Connected to ~/1password.sqlite" } ] } ``` Name Type Description `name` string Name of the server `version` string Version info of the Connect server `dependencies` array An array of Service Dependencies. #### Server Health: Dependency object {#server-health-dependency-object} Name Type Description `service` string Name of the dependency `status` string The service's reported status `message` string Extra information about the dependency's status. Optional. --- ## AWS ECS Fargate # Deploy 1Password Connect Server on AWS ECS Fargate with CloudFormation 1Password Connect works with [AWS Fargate ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html). AWS Fargate lets you leverage Amazon Elastic Container Service (ECS) to run containers without the need to manage clusters. ## Requirements Before you can use 1Password CLI with your Connect server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Create a 1Password Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) in your infrastructure. - Sign up with [AWS Fargate ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html). ## Example You can use 1Password's [example CloudFormation template (`connect.yaml`) ](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect.yaml) as a starting place for deploying Connect on AWS Fargate. The example [CloudFormation template ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-templates) creates the necessary networking resources, ECS resources, rules, groups, and policies. See [Resources](#resources) for more details. The result is a publicly accessible hostname that routes requests to a 1Password Connect Server deployment running in AWS Fargate. :::tip You can also use this example CloudFormation file to deploy into an existing [AWS virtual private cloud (VPC) ](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html) or an existing [Amazon Elastic Container (AWS ECS) ](https://docs.aws.amazon.com/ecs/) cluster. You can modify it using a text editor or using Amazon's [CloudFormation Designer ](https://console.aws.amazon.com/cloudformation/designer) tool. ::: ### Resources The example CloudFormation template creates the following network resources: - A virtual private cloud (VPC) - Two public subnets - An [Internet gateway ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-internetgateway.html) - An [Application Load Balancer (ALB) ](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) The example CloudFormation template creates the following ECS resources: - An [ECS cluster ](https://docs.aws.amazon.com/AmazonECS/latest/userguide/clusters-concepts.html) - Two [task definitions ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-tasks-services.html) - A `1password/connect-api` container - A `1password/connect-sync` container ## Get started To use the example `connect.yaml` file to deploy a Connect server on AWS Fargate (using CloudFormation): 1. [Start the **AWS Create Stack** wizard. ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html#cfn-using-console-initiating-stack-creation) 2. Select the example [`connect.yaml` file ](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect.yaml) as the stack template. See [Selecting a stack template ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-console-create-stack-template.html). 3. Provide a Base64 URL encoded version of your Connect server's `1password-credentials.json` file. When importing this CloudFormation template, it prompts you to provide a Base64 URL encoded version of the `1password-credentials.json`. You can generate this encoded value with the following shell command: ```shell cat 1password-credentials.json | base64 | tr '/+' '_-' | tr -d '=' | tr -d '\n' ``` --- ## Use 1Password CLI with a Connect server You can use 1Password CLI with a [Connect server](/docs/connect/) to provision secrets and retrieve items on the command line. ## Requirements Before you can use 1Password CLI with a Connect server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Deploy 1Password Connect](/docs/connect/get-started#step-2-deploy-a-1password-connect-server). - Make a Connect server accessible to your production environment. - [Install 1Password CLI in your production environment.](/docs/cli/install-server/) - Set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to a Connect server's credentials in your production environment. ## Get started After you complete the requirement steps, you can use the following 1Password CLI commands with a Connect server: - [`op run`](/docs/cli/reference/commands/run/) - [`op inject`](/docs/cli/reference/commands/inject/) - [`op read`](/docs/cli/reference/commands/read/) - [`op item get --format json`](/docs/cli/reference/management-commands/item#item-get) Vist the command documentation for more information. ## Continuous integration (CI) environments You can also use 1Password CLI with a Connect server in a continuous integration (CI) pipeline. 1Password CLI allows you to use [secret references](/docs/cli/secret-references/) in place of plaintext secrets in code. You can configure a CI environment to pass different sets of secrets for different environments. Secret references work well within infrastructure as code tools and CI configurations because you can define them alongside other configurations. ### GitLab CI example The following code block shows an example GitLab CI configuration file that implements a MySQL service. See [GitLabs `.gitlab-ci.yml` documentation ](https://docs.gitlab.com/ee/ci/yaml/). ```yaml title=".gitlab-ci.yml" services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password connect: image: mysql script: - echo "SELECT 'OK';" | op run -- mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` To authenticate 1Password CLI in the CI pipeline, add the OP_CONNECT_HOST and OP_CONNECT_TOKEN environment variables to a CI configuration file. The presence of these environment variables tells 1Password CLI to use the Connect server to fetch secrets. The following code block expands the GitLab CI example to include the Connect environment variables. ```yaml [{ "color": "bitsblue", "lineNo": 10, "substr": "OP_CONNECT_HOST" }, { "color": "lagoon", "lineNo": 11, "substr": "OP_CONNECT_TOKEN" }] title=".gitlab-ci.yml" services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password # Configure 1Password CLI to use Connect OP_CONNECT_HOST: :8080 OP_CONNECT_TOKEN: token connect: image: mysql script: - echo "SELECT 'OK';" | mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` ## Learn more ### [Replace plaintext secrets with secret references](/docs/cli/secret-references/) Learn how to create and use secret references to avoid putting plaintext secrets in code. ### [Load secrets into the environment](/docs/cli/secrets-environment-variables/) Learn how to source secrets from the environment into your applications. ### [Load secrets into config files](/docs/cli/secrets-config-files/) Learn how to load secrets automatically into config files without putting any plaintext secrets in code. --- ## Connect concepts Learn about the concepts involved with 1Password Connect. ## Connect servers {#servers} A Connect server is a tool you can deploy in your network that allows you to manage and sync 1Password items from within your infrastructure. ## Credentials {#credentials} There are two important pieces of information for authenticating Connect servers: - The `1password-credentials.json` file - The Connect server access token ### `1password-credentials.json` When you create a Connect server, a credentials file named `1password-credentials.json` is generated uniquely for that Connect server. It contains all the information you need to [deploy the Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server). ### Connect server access token A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password services, such as the [Connect REST API](/docs/connect/api-reference/). When you create a Connect server, you select the vaults that it can access. Connect servers can only access the vaults you explicitly allow them to access through a Connect server token. Each Connect server can have one or more access tokens, which allows for more fine-tuned [access control](/docs/connect/security#access-control). Connect server access tokens can only access information in the vaults you grant them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect token access to a specific subset of the vaults the Connect server has access to. Learn more about [how to manage access tokens](/docs/connect/manage-connect#manage-access-tokens). Learn more about [1Password Connect server security](/docs/connect/security/). ## Connect containers {#containers} Each Connect server deployment consists of two Docker containers running in the same network: - The [Connect sync container](#connect-sync-container) - The [Connect API container](#connect-api-container) Both containers require a shared volume to store an encrypted copy of your data. Learn more about [configuring your Connect server](/docs/connect/server-configuration/). ### Connect sync container The Connect sync container keeps information on the Connect server in sync with 1Password.com. View it on Docker Hub: [`1password/connect-sync`](https://hub.docker.com/r/1password/connect-sync). ### Connect API container The Connect API container serves [Connect REST API](/docs/connect/api-reference/). View it on Docker Hub: [`1password/connect-api`](https://hub.docker.com/r/1password/connect-api). ## Environment variables {#environment-variables} Connect servers have a collection of environment variables you can use to provide information about the Connect server to integrations, such as [1Password CLI](/docs/connect/cli/) or [CI/CD pipeline tools](/docs/ci-cd/). These environment variables are distinct from the [configuration environment variables](/docs/connect/server-configuration#environment-variables). | Environment variable | Description | Example | | -------------------- | ------------------------------------------------------------ | ----------------------- | | `OP_CONNECT_HOST` | Specifies the hostname, IP address, or URL where your Connect server is deployed. | `http://localhost:8080` | | `OP_CONNECT_TOKEN` | Specifies the string value of your Connect server token. | N/A | --- ## Get started with a 1Password Connect server 1Password Connect servers are a type of [Secrets Automation workflow](/docs/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. ## Requirements Before you can create a 1Password Secrets Automation workflow as a Connect server, make sure you complete the prerequisite tasks. The tasks vary depending on how you plan to deploy. **Docker:** - [Sign up for a 1Password account](https://1password.com/pricing/password-manager). - [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Make sure you belong to [a group with permission to manage Secrets Automation](/docs/connect/manage-connect/). - Make sure you have a deployment environment for Docker. You can use a cloud service provider or your local machine. **Kubernetes:** - [Sign up for a 1Password account](https://1password.com/pricing/password-manager). - [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Make sure you belong to [a group with permission to manage Secrets Automation](/docs/connect/manage-connect/). - Make sure you have a deployment environment for Kubernetes with [kubectl ](https://kubernetes.io/docs/tasks/tools/install-kubectl/), and [Helm ](https://helm.sh/) installed. You can use a cloud service provider or your local machine. ## Deployment Use the following instructions to deploy a 1Password Connect Server. ### Step 1: Create a Secrets Automation workflow {#step-1} You can create a Connect server Secrets Automation workflow through the 1Password.com dashboard or 1Password CLI. Following these instructions creates: - A `1password-credentials.json` file. It contains the credentials necessary to deploy 1Password Connect Server. - An access token. Use this in your applications or services to authenticate with the [Connect REST API](/docs/connect/api-reference/). You can [issue additional tokens later](/docs/connect/manage-connect#create-a-token). **1Password.com:** 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Open the [Secrets Automation workflow creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/connect). Or, navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Connect server**. 3. Follow the onscreen instructions to create a Secrets Automation environment, set up your first access token, and deploy a Connect server. Make sure to save your credentials file and token in 1Password. You can find your new Secrets Automation workflow under "Connect servers" on the [**Developer**](https://start.1password.com/developer-tools/active) page. **1Password CLI:** You can use the [1Password CLI](https://1password.com/downloads/command-line) [`op connect` command](/docs/cli/reference/management-commands/connect/) to set up a Secrets Automation workflow with a Connect server. 1. Make sure you have the latest version of [1Password CLI](/docs/cli/get-started/) on your machine. 2. Switch to the directory where you want to create the `1password-credentials.json`. Creating a Connect server automatically generates the `1password-credentials.json` file in the current directory. This file contains the credentials you'll need to deploy the Connect server. If a `1password-credentials.json` file already exists in the current directory, 1Password CLI will ask if you want to overwrite it. 3. Create a Connect server and grant it access to a shared vault using the [`op connect server create` command](/docs/cli/reference/management-commands/connect#connect-server-create). ```shell op connect server create --vaults ``` :::tip Omit the `--vaults` flag to create a Connect server without granting it access to a vault. You can grant the Connect server access to shared vaults later using the [`op connect vault grant` command](/docs/cli/reference/management-commands/connect#connect-vault-grant). ::: If the Connect server or vault name contains one or more spaces, enclose the name in quotation marks (for example, `β€œMy Server Name”`). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, `myServerName`). ``` op connect server create "My Server Name" --vault "My Vault Name" ``` 4. Create a token for the Connect server using the [`op connect token create` command](/docs/cli/reference/management-commands/connect#connect-token). ```shell op connect token create --server --vault ``` :::tip Looking up a Connect server by its ID is more efficient than using the Connect server's name. See [Unique identifiers (IDs)](/docs/cli/reference#unique-identifiers-ids). You can find the ID of a Connect server by running [`op connect server list`](/docs/cli/reference/management-commands/connect#connect-server-list). ::: If successful, 1Password CLI returns a token string that you can use in your applications or services to authenticate with the [Connect server REST API](/docs/connect/api-reference/). You can [issue additional tokens later.](/docs/connect/manage-connect#create-a-token) 5. Save the token in 1Password so you don't lose it. You can have multiple tokens for the same Connect server but each Connect server has its own distinct set of tokens. See the [`op connect token` command reference](/docs/cli/reference/management-commands/connect#connect-token). :::tip Export your Connect server access token as an environment variable. Doing so might prove useful if you decide to configure another tool like the [Kubernetes Injector](/docs/k8s/injector/), [Kubernetes Operator](/docs/k8s/operator/), or other integrations. However, keep in mind that the recommended way to use the Connect server token with Kubernetes is as a Kubernetes Secret. ```shell export OP_CONNECT_TOKEN= ``` ::: ### Step 2: Deploy a 1Password Connect Server **Docker:** To deploy a Connect server using a Docker Compose file, you'll need to start two Docker images: - [1password/connect-api ](https://hub.docker.com/r/1password/connect-api) serves the Connect server REST API. - [1password/connect-sync ](https://hub.docker.com/r/1password/connect-sync) keeps the information available on the Connect server in sync with 1Password.com. :::info If you aren't familiar with Docker or Docker Compose, refer to the [Docker Compose documentation ](https://docs.docker.com/compose/) for more information. ::: 1. Make sure you have [Docker ](https://docs.docker.com/engine/install/) and [Docker Compose ](https://docs.docker.com/compose/install/) on your machine. 2. Create a Docker Compose file to deploy the 1Password Connect Server containers in the directory where you saved your `1password-credentials.json` file. You can also use the example [`docker-compose.yaml` file](https://i.1password.com/media/1password-connect/docker-compose.yaml). If the credentials file is in the other directory, update the `volumes` section to point to the correct credentials file location. :::tip You can set any of the [Connect server environment variables](/docs/connect/server-configuration/) in the `docker-compose.yaml` file by adding an environment attribute to each container. Doing so lets you specify things like the `1password-credentials.json` file location, the log level, and the HTTP port. Refer to the [Docker environment attribute documentation ](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for more information. ::: 3. Make sure Docker is running. You can [check if the Docker daemon is running ](https://docs.docker.com/config/daemon/troubleshoot#check-whether-docker-is-running) with the `docker info` command in a terminal application. 4. Start the Docker containers with Docker Compose. Run the following command in the directory with the `docker-compose.yaml` file. ```shell docker compose up ``` :::tip You can run the containers in the background using the `-detach` flag or the `-d` flag. Refer to the [`docker compose up` reference ](https://docs.docker.com/engine/reference/commandline/compose_up/) for more information. ::: By default, you can access the Connect REST API through port `8080` on the local host. Refer to the [1Password Connect server API reference](/docs/connect/api-reference/) for more information. #### Test the Connect server REST API You can make sure the [Connect server REST API](/docs/connect/api-reference/) is accessible using a [`curl` ](https://curl.se/docs/manpage.html) command, one of the 1Password Connect server API endpoints, and the token you created. 1. Export the Connect server access token as an environment variable. This is the same token you created in [Step 1](#step-1). Alternatively, you can replace `$OP_API_TOKEN` with the token string in the `curl` request. :::tip If you forgot your token, you can create another one with the [`op connect token create` command](/docs/cli/reference/management-commands/connect#connect-token-create). ::: ```shell export OP_API_TOKEN="" ``` 2. Use the following example [`curl` ](https://curl.se/docs/manpage.html) command to list the vaults connected to the Connect server. ```shell curl \ -H "Accept: application/json" \ -H "Authorization: Bearer $OP_API_TOKEN" \ http://localhost:8080/v1/vaults ``` To stop the Docker containers, run `docker compose down`. **Kubernetes:** You can deploy a Connect server with Kubernetes. The easiest way to do this is with the [1Password Connect and Operator Helm chart](/docs/k8s/helm/). :::warning[caution] Before you start, you must have a Kubernetes cluster deployed. If you don't already have a cluster, you can create one locally using [minikube ](https://minikube.sigs.k8s.io/docs/start/) or use the [Play with Kubernetes ](https://labs.play-with-k8s.com/) playground. ::: 1. Make sure you have [Docker ](https://docs.docker.com/engine/install/) installed and running on your machine. 2. Install the latest [Helm ](https://helm.sh) release. 3. Add the 1Password Helm chart repository. The following command adds the [1Password Helm chart repository](/docs/k8s/helm/) to your local instance of Helm. This allows you to download and install all the charts from 1Password's GitHub repository. ```shell helm repo add 1password https://1password.github.io/connect-helm-charts/ ``` 4. Install the 1Password Connect server using Helm. The following command deploys the 1Password Connect server using the `1password-credentials.json` file. :::tip You can find the `1password-credentials.json` file in the directory where you created the Connect server. ::: ```shell helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json ``` #### Other ways to deploy Here are some ways you can deploy a Connect server on a Kubernetes cluster: ##### Deploy without Helm You can deploy a Connect server on a Kubernetes cluster without using Helm charts. See the [sample Kubernetes deployment ](https://github.com/1Password/connect/tree/main/examples/kubernetes) on 1Password's GitHub that uses [cert-manager](https://cert-manager.io/) to provision a TLS (transport layer security) certificate for an external domain. ##### Deploy alongside the Kubernetes Operator {#with-operator} The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password. It also auto-restarts deployments when 1Password items are updated. [Learn more about the Kubernetes Operator](/docs/k8s/operator/). ### Step 3: Set up applications and services to get information from 1Password Applications and services get information from 1Password through REST API requests to a Connect server. The requests are authenticated with an access token. [Create a new token](/docs/connect/manage-connect#create-a-token) for each application or service you use. #### Languages [_[]_ Go](https://github.com/1Password/connect-sdk-go) [_[]_ Node.js](https://github.com/1Password/connect-sdk-js) [_[]_ Python](https://github.com/1Password/connect-sdk-python) #### Plugins [_[]_ Terraform provider](https://github.com/1Password/terraform-provider-onepassword) [_[]_ Kubernetes integrations](/docs/k8s/integrations/) [_[]_ Hashicorp Vault backend](https://github.com/1Password/vault-plugin-secrets-onepassword) [_[]_ Ansible collection](/docs/connect/ansible-collection/) If your language or platform isn't listed, you can [build your own client using the 1Password Connect Server REST API](/docs/connect/api-reference/). You can also [use 1Password CLI](/docs/connect/cli/) with your Connect server to provision secrets and retrieve item information on the command line. ## Get help To change the vaults a token has access to, [issue a new token](/docs/connect/manage-connect#create-a-token). To get help and share feedback, join the discussion with the [1Password Support Community](https://1password.community/categories/secrets-automation/). --- ## Manage Connect servers :::info As of Feb 27, 2025, all 1Password customers have unlimited access to Connect. ::: A Connect server is a type of [Secrets Automation workflow](/docs/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API provided by 1Password Connect Server. You can use 1Password.com or the [Connect REST API](/docs/connect/api-reference/) to: Control which team members and applications have access to which Connect server access tokens. Monitor and audit access and item usage. Secure applications by choosing when Connect server access tokens expire. Create and revoke Connect server access tokens. _[]_ ## Manage permissions {#manage-access} With 1Password Business or 1Password Teams, you can manage Connect server permissions with [groups](#global-permissions), or more granularly, with [environments](#environment-permissions). This allows for enforcement of security best practices. [Learn more about Connect security.](/docs/connect/security/) :::tip You can also manage group access using [automated provisioning](https://support.1password.com/scim/). ::: ### Manage global permissions {#global-permissions} Groups allow you to specify one or more users who can access Connect servers. To assign groups (such as Owners and Administrators) to manage Connect servers: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Managers section, select **Manage**, then choose the groups you want to manage Connect servers. 5. Select **Update Groups**. _[Manage Secrets Automation managers]_ ### Manage environment permissions {#environment-permissions} Environments allow you to override global permissions (with groups) for a specific Connect server environment. To assign groups (such as Owners and Administrators) to manage a specific Connect server: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/) in the sidebar. 3. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Environments section, select **Manage**. 5. In the Permissions section, select **Manage**, then choose the groups you want to manage Connect servers in the environment. 6. Select **Update Groups**. ## Manage access tokens You can use [Connect server access tokens](/docs/connect/concepts#connect-server-access-token) to authenticate with your Connect server in your applications and services. - [Create an access token.](#create-a-token) - [Set an access token expiration.](#set-a-token-expiration) - [Revoke an access token.](#revoke-a-token) - [Rename an access token.](#rename-a-token) ### Create a token To create a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Follow the onscreen instructions to issue the token. :::warning[caution] You can't edit the vaults a token can access after you create it. If you want to change the vaults a token can access, you must revoke the token and create a new one. ::: Connect server access tokens support up to 100 vaults each. If you grant a Connect token access to more than 100 vaults, the server may reject requests. ### Set a token expiration When you create a Connect server access token, you can set the token's expiration time to 30, 90, or 180 days. When the expiration time elapses, 1Password revokes the token. To create a token with an expiration date: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Set the "Expires After" to **30 days**, **90 days**, or **180 days**. 6. Follow the onscreen instructions. ### Revoke a token To revoke a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to revoke, then select **Revoke**. ### Rename a token To rename a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active/) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to rename, then select **Rename** and enter a new name. ## Grant or revoke access to vaults {#vault-access} To grant or revoke access to vaults: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to grant or revoke access to vaults. 4. In the Vaults section, select **Manage** and choose the vaults you want to add or remove. 5. Select **Update Vaults**. You can't grant Connect servers access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. _[Manage which vaults have access to each token]_ ## Monitor item usage Connect servers send [reports about item usage](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) to the 1Password server every time an item is accessed so you can monitor item usage. :::info Item usage information might take a few hours to sync with 1Password.com. ::: To view item usage for a Connect server: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment (Connect server) you want to monitor. 4. Under Version, select **More Actions** > **View Item Usage Report**. For more information, visit [Create reports in 1Password Business](https://support.1password.com/reports/). ### About Connect server item usage Items accessed through a Connect server update specific fields in the following manner: - The **Action** field in the report always shows Display. - The **Used by** field always includes the name of the Connect server (not the Connect server access token). Connect servers only report item usage when they have a working connection to the 1Password server. If a Connect server can't reach the 1Password server (for example, when it updates or restarts), it might lose item usage information from that time period. Item usage reporting continues when the Connect server has a working connection to the 1Password server again. --- ## 1Password Connect 1Password Connect Servers allow you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API. Because Connect servers cache your data in your infrastructure, they allow unlimited re-requests after the server fetches your secrets. The only request quotas that apply to Connect servers are the internal rate limits 1Password employs to keep our services stable and available. These only apply when a Connect server fetches secrets for the first time, like when the Connect server starts. You can integrate a Connect server into your infrastructure and communicate with it over HTTP using one of the Connect SDK libraries (such as [Go](https://github.com/1Password/connect-sdk-go), [Python](https://github.com/1Password/connect-sdk-python), or [JavaScript](https://github.com/1Password/connect-sdk-js)) or using a custom integration. :::tip Not sure if Connect servers are for you? See the [Secrets Automation comparison table](/docs/secrets-automation#comparison). ::: _[The Connect server is part of your environment, and communicates to Your Apps using access tokens and a REST API.]_ ## Use cases You can use 1Password Connect to accomplish a variety of tasks: - **Reduce latency and downtime**: Deploy a Connect server in your infrastructure, giving you complete control. Self-hosting also reduces latency and has security benefits, as only your services can interact with Connect. You can also deploy redundant Connect servers to further increase availability. - **Provision web services with secrets**: Use a Connect server to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a Connect server to provision an account with the needed secret and allow the web service to access the secret during test runs. - **Automate secrets management**: Use a Connect server to automate scripts to manage secrets. Using a Connect server helps you implement the principle of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). - **Load secrets into CI/CD pipelines**: Use a Connect server to automatically access your secrets in continuous integration environments. You can use a Connect server to use 1Password items in your CI/CD pipeline for testing and deploying code. Doing so maintains security and avoids using sensitive information with a personal account. - **Secure infrastructure secrets**: Use a Connect server to make sure infrastructure secrets aren't tied to a personal user account. - **Streamline development workflows**: Use a Connect server to securely share and manage infrastructure secrets to streamline development workflows. - **Secure Kubernetes environments**: Use a Connect server to access and sync 1Password secrets in a Kubernetes environment. ## Get started Learn how to get started and how to create, manage, and integrate with Connect servers. Get started --- ## About 1Password Connect Server security You can deploy one or more 1Password Connect servers in your infrastructure to act as a bridge between your applications and the 1Password service. Connect servers allow you to securely share information from 1Password with your applications, tools, and pipelines through the [Connect REST API](/docs/connect/api-reference/). Review the sections on the page to learn more about Connect server security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When you [create a Connect server](/docs/connect/get-started/), you select the vaults it can access. Connect servers can only access the vaults you explicitly allow them to access through a [Connect server access token](#connect-server-access-tokens). ### Authorization Only authorized clients can get information from a Connect server. When a client application, service, or API requests information from a Connect server, the HTTP request must have an `Authorization` header containing an authorization token. Otherwise, the Connect server rejects the request. Authorization tokens are only valid for the Connect server they're created for. They're signed by the key for the 1Password account the Connect server uses, using the [ES256 signing algorithm ](https://datatracker.ietf.org/doc/html/rfc7518). ### Usage reports [Usage reports](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) can be created for users or vaults. Usage reports for team members include information on the number of vaults, groups, and items a team member can access, an overview of vaults where a team member has accessed items, when those items were last accessed, and the action performed. Usage reports for vaults include a list of items showing when they were last accessed, the action performed, and the team member who performed the action. These reports can be helpful when offboarding team members. ## Connect server access tokens A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password. Each Connect server can have one or more Connect server access tokens, which allows for more fine tuned [access control](#access-control). Connect server tokens can only access information in the vaults you granted them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect server token access to a specific subset of the vaults the Connect server has access to. ### Token rotation You can't change or update Connect server access tokens. If a Connect server token becomes compromised, you must create a new token. To rotate a Connect server access token: 1. [Create a new Connect server access token.](/docs/connect/manage-connect#create-a-token) 2. Update all references to the old Connect token. 3. [Revoke access to the old Connect token.](/docs/connect/manage-connect#revoke-a-token) ## Security model The Connect server security model has the following guarantees: - A Connect server access token can only read items from vaults you've explicitly given it `READ` access to. - A Connect server access token can only update, delete, and create items for vaults it has you've given it `WRITE` access to. - You can only give a Connect token access to vaults that you have access to. - A Connect server access token associated with a deleted account can't authenticate. - You can't use a Connect server access token to create another Connect server access token. ## Credentials file Creating a Connect server generates a credentials file named `1password-credentials.json`. This file has the following components: | Component | Description | | ---------------- | ------------------------------------------------------------ | | `verifier` | Connect servers use the `verifier` as part of an additional authentication of the bearer token. | | `encCredentials` | The `encCredentials` contains the encrypted credentials necessary for the associated service account. | | `uniqueKey` | The `uniqueKey` identifies the Connect server between its two running processes: the client-facing service and the synchronization service. | | `version` | The `version` indicates the Connect server version number. | | `deviceUuid` | The `deviceUuid` contains the UUID of the device. | ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne. ](https://hackerone.com/1password) --- ## Configure your Connect server This article documents Connect server [environment variables](#environment-variables) and special configuration options, such as [TLS](#tls) and [manual bus configuration](#manual-bus-configuration). 1Password Connect Server consists of two containers running in the same network: - The Connect API container ([`1password/connect-api` ](https://hub.docker.com/r/1password/connect-api)) - The Connect sync container ([`1password/connect-sync` ](https://hub.docker.com/r/1password/connect-sync)) Both containers require a shared volume to store an encrypted copy of your data. ## Requirements Before you can configure your 1Password Connect Server, you must: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - [Setup a Connect server](/docs/connect/get-started/). ## Environment variables The following table lists the available environment variables, their description, and the containers that support them. Most of the environment variables apply to the Connect API and Connect sync containers, but some only apply to the Connect API container. | **Environment variable** | **Description** | **Container support** | | ------------------------ | ------------------------------------------------------------ | ------------------------------------------- | | `OP_SESSION` | The path to the `1password-credentials.json` file. You can also set the value to the [Base64-encoded content of the `1password-credentials.json` file](/docs/connect/aws-ecs-fargate#get-started). **Acceptable values**: A full file path to the `1password-credentials.json` file. **Default value**: `~/.op/1password-credentials.json` | • Connect API• Connect sync | | `OP_HTTP_PORT` | The port for the HTTP server. **Acceptable values**: Any available port number. **Default value**: `8080` | • Connect API• Connect sync | | `OP_LOG_LEVEL` | The logging level of the container. **Acceptable values**: `info`, `error`, `debug`**Default value**: `info` | • Connect API• Connect sync | | `XDG_DATA_HOME` | The path in which to create the `.op/data/` directory. See [Data volume](#data-volume). **Acceptable values**: A valid file path. **Default value**: `/home/opuser/.op/data` | • Connect API• Connect sync | | `OP_BUS_PORT` | The port for listening to incoming bus connections from other containers. See [Manual bus configuration](#manual-bus-configuration) for more details.**Acceptable values**: Any available port number. **Default value**: A random free port | • Connect API• Connect sync | | `OP_BUS_PEERS` | A comma-separated list of `[hostname]:[bus port]` pairs of other containers to connect to. See [Manual bus configuration](#manual-bus-configuration) for more details.**Acceptable values**: A comma-separated list of `[hostname]:[bus port]` pairs. **Default value**: No default because this variable is optional. | • Connect API• Connect sync | | `OP_HTTPS_PORT` | The port for the HTTP server when using [TLS](#tls). **Acceptable values**: Any available port number.**Default value**: `8443` | • Connect API | | `OP_SYNC_TIMEOUT` | The time (in seconds) to wait for the initial sync to complete. **Acceptable values**: A time duration (for example, `1h`, `30m`, `20s`).**Default value**: `10s` (10 seconds) | • Connect API | | `OP_TLS_KEY_FILE` | The path to the private key file. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom).**Acceptable values**: A valid file path.**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_CERT_FILE` | The path to the certificate file. This should be the full certificate chain. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom).**Acceptable values**: A valid file path.**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_USE_LETSENCRYPT` | Only use this environment variable if you want to [use TLS with a Lets Encrypt certificate](#tls-lets-encrypt).**Acceptable values**: Any value (for example, `1`, `true`, or `yes`).**Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_DOMAIN` | The (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. See [TLS](#tls).**Acceptable values**: Any domain (or subdomain) name.**Default value**: No default because this variable is optional. | • Connect API | ### Data volume The default location of the shared volume is `/home/opuser/.op/data`. If you set the `XDG_DATA_HOME` environment variable to a path other than `/home/opuser/`, make sure you mount your data volume at the same path. ### TLS By default, 1Password Connect Server is configured for use within a trusted network. If you plan to use Connect outside a trusted network, consider configuring [Transport Layer Security (TLS) ](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/). You can configure TLS for the connection between your application and Connect by [providing your own certificate](#tls-custom) or letting Connect request a certificate [using Let's Encrypt](#tls-lets-encrypt). Connect listens on the port defined by the `OP_HTTPS_PORT` environment variable (default `8443`) when you use TLS. #### Use your own certificate {#tls-custom} Connect can use a PEM-encoded private key and certificate by setting the following two environment variables for the Connect API container: 1. Set `OP_TLS_KEY_FILE` to the path to the private key file. 2. Set `OP_TLS_CERT_FILE` to the path to the certificate file. This should be the full certificate chain. #### Use Let's Encrypt {#tls-lets-encrypt} Connect can also request a certificate from the [Let's Encrypt ](https://letsencrypt.org/) Certificate Authority (CA). For this, you must set two environment variables for the Connect API container: 1. Set `OP_TLS_USE_LETSENCRYPT` to any value. 2. Set `OP_TLS_DOMAIN` to the (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. As long as Connect is running, its HTTPS listener must be reachable on a public IP at port `443` (either by setting `OP_HTTPS_PORT=443` or by forwarding traffic at port `443` to the Connect server's `OP_HTTPS_PORT` value). This makes sure the Connect server can refresh its Let's Encrypt certificate. ### Manual bus configuration :::warning[caution] Manual bus configuration only works with Connect server [version 1.5.0 ](https://github.com/1Password/connect/blob/main/CHANGELOG.md#v150) and later. ::: By default, the two containers (Connect API and Connect sync) automatically discover and connect to the shared bus. This discovery mechanism requires the `NET_BROADCAST` capability, which you can't always grant to containers. However, it’s possible to manually configure the shared bus. To manually configure the shared bus: 1. Assign a static port for the bus by setting the `OP_BUS_PORT` environment variable to a free port for both containers. 2. Set the `OP_BUS_PEERS` environment variable for the Connect API container to `[hostname]:[bus port]`, where `hostname` is the name of the Connect sync container and `bus port` the value of `OP_BUS_PORT` for the Connect sync container. 3. Set the `OP_BUS_PEERS` environment variable for the Connect sync container to `[hostname]:[bus port]`, where `hostname` is the name of the application container and `bus port` is the value of `OP_BUS_PORT` for the Connect API container. The following examples show the configuration values necessary for the Connect API container and the Connect sync container. **Connect API container:** The following example sets environment variables for a Connect API container called op-connect-api. ```txt [{ "color": "bitsblue", "lineNo": 2, "substr": "op-connect-api" }] OP_BUS_PORT=11223 OP_BUS_PEERS=op-connect-api:11223 ``` **Connect sync container:** The following example sets environment variables for a Connect sync container called op-connect-sync. ```txt [{ "color": "lagoon", "lineNo": 2, "substr": "op-connect-sync" }] OP_BUS_PORT=11223 OP_BUS_PEERS=op-connect-sync:11223 ``` ## Examples The [1Password Connect repository ](https://github.com/1Password/connect) has example Connect server configurations using Kubernetes, Docker Compose, and AWS Fargate. - [Example Kubernetes deployment ](https://github.com/1Password/connect/tree/main/examples/kubernetes) - [Example Docker Compose deployment ](https://github.com/1Password/connect/tree/main/examples/docker/compose) - [Example AWS Fargate deployment ](https://github.com/1Password/connect/tree/main/examples/aws-ecs-fargate) --- ## Helm chart configuration This page documents the configuration options for the 1Password Helm charts: - [Connect and Operator Helm chart](#connect-and-operator-helm-chart) - [Secrets Injector Helm chart](#secrets-injector-helm-chart) ## Connect and Operator Helm chart The 1Password Connect and Operator Helm chart allows you to use Helm to deploy [Connect](/docs/connect/get-started/), the [Kubernetes Operator](/docs/k8s/operator/), or both. You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `connect.applicationName` configuration value: ```shell helm install --set connect.applicationName=connect connect 1password/connect ``` Refer to the [official `helm install` documentation ](https://helm.sh/docs/helm/helm_install/) for more information. :::info By default, installing a 1Password Helm chart also installs the `OnePasswordItem` database operations for CRD (Custom Resource Definition). If you don't want to install the `OnePasswordItem` custom resource definitions (CRD), run `helm install` with the [`--skip-crds` flag ](https://helm.sh/docs/chart_best_practices/custom_resource_definitions#method-1-let-helm-do-it-for-you). ::: ### Configuration options The following table documents the available configuration options for the 1Password Connect and Operator Helm chart. :::tip If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). For example: ``` $ helm install -f myvalues.yaml injector 1password/secrets-injector ``` ::: | Key | Type | Default | Description | | ------------------------------------- | ---------- | ---------------------------------- | ------------------------------------------------------------ | | `connect.create` | boolean | `true` | Denotes whether to deploy the 1Password Connect server. Set this value to `false` and `operator.create` to `true` to only deploy the Kubernetes Operator. See [Deploy without Connect](/docs/k8s/operator?deployment-type=helm#helm-step-2). | | `connect.replicas` | integer | `1` | The number of replicas to run the 1Password Connect deployment. | | `connect.applicationName` | string | `"onepassword-connect"` | The name of 1Password Connect application. | | `connect.host` | string | `"onepassword-connect"` | The name of 1Password Connect host. | | `connect.api.imageRepository` | string | `"1password/connect-api` | The 1Password Connect API repository. | | `connect.api.name` | string | `"connect-api"` | The name of the 1Password Connect API container. | | `connect.api.resources` | object | `{}` | The resources requests/limits for the 1Password Connect API pod. | | `connect.api.httpPort` | integer | `8080` | The port the Connect API is served on when not using TLS. | | `connect.api.httpsPort` | integer | `8443` | The port the Connect API is served on when using TLS. | | `connect.api.logLevel` | string | `info` | The log level of the Connect API container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.credentials` | jsonString | | The contents of the `1password-credentials.json` file for Connect. You can set it by adding `--set-file connect.credentials=` to your `helm install` command. | | `connect.credentials_base64` | string | | The base64-encoded contents of the `1password-credentials.json` file for Connect. You can use this instead of `connect.credentials` if supplying raw JSON to `connect.credentials` lead to issues. | | `connect.credentialsKey` | string | `"1password-credentials.json"` | The key for the 1Password Connect credentials (stored in the credentials secret). The credentials must be encoded as a base64 string. | | `connect.credentialsName` | string | `"op-credentials"` | The name of Kubernetes Secret containing the 1Password Connect credentials. | | `connect.dataVolume.name` | string | `"shared-data"` | The name of the shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.type` | string | `"emptyDir"` | The type of shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.values` | object | `{}` | Describes the fields and values for the configuration of the shared [volume ](https://kubernetes.io/docs/concepts/storage/volumes/) for 1Password Connect. | | `connect.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Connect API image pull policy. | | `connect.ingress.annotations` | object | `{}` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) annotations. | | `connect.ingress.enabled` | bool | `false` | Whether to enable 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) traffic. | | `connect.ingress.extraPaths` | list | `[]` | Additional [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) paths. | | `connect.ingress.hosts[0].host` | string | `"chart-example.local"` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) hostname. | | `connect.ingress.hosts[0].paths` | list | `[]` | The 1Password Connect [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) path. | | `connect.ingress.ingressClassName` | string | `""` | Optionally use `ingressClassName` instead of a deprecated annotation. | | `connect.ingress.labels` | object | `{}` | [Ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/) labels for 1Password Connect. | | `connect.ingress.pathType` | string | `"Prefix"` | Ingress [PathType ](https://kubernetes.io/docs/concepts/services-networking/ingress#path-types). | | `connect.ingress.tls` | list | `[]` | [Ingress TLS ](https://kubernetes.io/docs/concepts/services-networking/ingress#tls). | | `connect.nodeSelector` | object | `{}` | The [Node selector ](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node#nodeselector) stanza for the Connect pod. | | `connect.probes.readiness` | boolean | `true` | Denotes whether the 1Password Connect API readiness probe operates and ensures the pod is ready before serving traffic. | | `connect.probes.liveness` | boolean | `true` | Denotes whether Kubernetes continually checks the 1Password Connect API for liveness and restarts if the pod becomes unresponsive. | | `connect.annotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Connect API deployment resource. | | `connect.labels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Connect API deployment resource. | | `connect.podAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the Connect API pods. | | `connect.podLabels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Connect API pods. | | `connect.serviceType` | string | `NodePort` | The type of Service resource to create for the Connect API and Connect Sync services. | | `connect.serviceAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the service. | | `connect.sync.imageRepository` | string | `"1password/connect-sync"` | The 1Password Connect Sync repository. | | `connect.sync.name` | string | `"connect-sync"` | The name of the 1Password Connect Sync container. | | `connect.sync.resources` | object | `{}` | The resources requests/limits for the 1Password Connect Sync pod. | | `connect.sync.httpPort` | integer | `8081` | The port serving the health of the Connect Sync container. | | `connect.sync.logLevel` | string | `info` | The log level of the Connect Sync container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.tls.enabled` | boolean | `false` | Denotes whether the Connect API is secured with TLS. | | `connect.tls.secret` | string | `"op-connect-tls"` | The name of the secret containing the TLS key (`tls.key`) and certificate (`tls.crt`). | | `connect.tolerations` | list | `[]` | A list of tolerations to be added to the Connect API pods. | | `connect.version` | string | `{{.Chart.AppVersion}}` | The 1Password Connect version to pull. | | `operator.autoRestart` | boolean | `false` | Denotes whether the Kubernetes Operator automatically restarts deployments based on associated updated secrets. See [Automatic redeployment](/docs/k8s/operator#enable-auto-redeployment). | | `operator.create` | boolean | `false` | Denotes whether to deploy the Kubernetes Operator. You can set this to `false` to only deploy Connect. | | `operator.imagePullPolicy` | string | `"IfNotPresent"` | The Kubernetes Operator image pull policy. | | `operator.imageRepository` | string | `"1password/onepassword-operator"` | The Kubernetes Operator repository. | | `operator.nodeSelector` | object | `{}` | [Node selector ](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node#nodeselector) stanza for the Kubernetes Operator pod. | | `operator.annotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator deployment resource. | | `operator.labels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Operator deployment resource. | | `operator.logLevel` | string | `info` | The log level of the Kubernetes Operator container. Valid options are: `debug`, `info`, and `error`. | | `operator.podAnnotations` | object | `{}` | Additional [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator pods. | | `operator.podLabels` | object | `{}` | Additional [labels ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Kubernetes Operator pods. | | `operator.pollingInterval` | integer | `600` | The interval at which the Kubernetes Operator polls for secrets updates. | | `operator.clusterRole.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a cluster role for the Kubernetes Operator. | | `operator.clusterRole.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator [Cluster Role ](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). | | `operator.clusterRoleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [ClusterRole binding ](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the Kubernetes Operator Service Account. | | `operator.roleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a role binding for each Namespace for the Kubernetes Operator Service Account. | | `operator.roleBinding.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator Role Binding. | | `operator.serviceAccount.annotations` | object | `{}` | The [annotations ](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) for the 1Password Connect Service Account. | | `operator.serviceAccount.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [Service Account](/docs/service-accounts/get-started/) for the Kubernetes Operator. | | `operator.serviceAccount.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator. | | `operator.tolerations` | list | `[]` | A list of tolerations to add to the Kubernetes Operator pods. | | `operator.version` | string | `"1.8.0"` | The Kubernetes Operator version to pull. It defaults to the latest version. | | `operator.token.key` | string | `"token"` | The key for the 1Password Connect token (stored in the 1Password token secret). | | `operator.token.name` | string | `"onepassword-token"` | The name of Kubernetes Secret containing the 1Password Connect API token. | | `operator.token.value` | string | `"onepassword-token"` | An API token generated for 1Password Connect to be used by the Kubernetes Operator. | | `operator.watchNamespace` | list | `[]` | A list of namespaces for the Kubernetes Operator to watch and manage. Use the empty list to watch all namespaces. | | `operator.resources` | object | `{}` | The resources requests/limits for the Kubernetes Operator pod. | ## Secrets Injector Helm chart The 1Password Secrets Injector Helm chart allows you to use Helm to deploy the [Kubernetes Secrets Injector](/docs/k8s/injector/). You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `injector.applicationName` configuration value: ```shell helm install --set injector.applicationName=injector injector 1password/secrets-injector ``` Refer to the [official `helm install` documentation ](https://helm.sh/docs/helm/helm_install/) for more information. ### Configuration options The following table documents the available configuration options for the Secrets Injector Helm chart. :::tip If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). For example: ``` $ helm install -f myvalues.yaml injector 1password/secrets-injector ``` ::: | Key | Type | Default | Description | | -------------------------- | ------- | ----------------------------------------- | ------------------------------------------------------------ | | `injector.applicationName` | string | `"secrets-injector"` | The name of 1Password Kubernetes Secrets Injector Application. | | `injector.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Secrets Injector Docker image policy. `"IfNotPresent"` means the image is pulled only if it is not already present locally. | | `injector.imageRepository` | string | `"1password/kubernetes-secrets-injector"` | The 1Password Secrets Injector docker image repository. | | `injector.port` | string | `443` | The port the Secrets Injector exposes. | | `injector.targetPort` | integer | `8443` | The port the Secrets Injector API sends requests to the pod. | | `injector.version` | string | `{{.Chart.AppVersion}}` | The 1Password Secrets Injector version to pull. | --- ## 1Password Helm charts Helm is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. Refer to [Helm ](https://helm.sh) to learn more. The 1Password Helm charts allow you to use Helm to deploy a [Secrets Automation workflow](/docs/secrets-automation/). 1Password offers two Helm charts: - The [1Password Connect and Kubernetes Operator Helm chart ](https://github.com/1Password/connect-helm-charts/blob/main/charts/connect) runs a Connect server by itself or alongside the Kubernetes Operator. - The [1Password Secrets Injector Helm chart ](https://github.com/1Password/connect-helm-charts/blob/main/charts/secrets-injector) runs the Kubernetes Secrets Injector, which works with both service accounts and Connect servers. See the following comparison table to learn which Helm chart is right for the environment you want to run. | Environment | Connect and Operator | Secrets Injector | | ----------- | -------------------------------------- | -------------------------------------- | | Connect server (without the Kubernetes Operator) | Yes | No | | Connect server and the Kubernetes Operator | Yes | No | | Kubernetes Injector | No | Yes | ### Requirements Make sure you complete the requirements for the Helm chart you intend to use before continuing. **Connect Kubernetes Operator:** Before you use the 1Password Connect and Operator Helm chart, make sure you: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. Install kubectl . Install Helm . Create a Secrets Automation workflow as a Connect server. **Kubernetes Secrets Injector:** Before you use the 1Password Kubernetes Secrets Injector Helm chart, make sure you: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. Install kubectl . Install Helm . Create a Secrets Automation workflow as a Connect server or a service account. ### Deployment The deployment process for the 1Password Helm charts depends on multiple factors, including: - The type of secrets automation workflow. - Whether you want to use the Kubernetes Operator, the Kubernetes Injector, or neither. **Connect Kubernetes Operator:** There are multiple ways to use the Helm chart for 1Password Connect and the Kubernetes Operator. Select one to get started: 1. [Deploy a Connect server.](/docs/connect/get-started/?deploy-type=kubernetes#step-2-deploy-a-1password-connect-server) 2. [Deploy a Connect server and the Kubernetes Operator.](/docs/k8s/operator/?requirements=deploy-with-helm&deployment=helm#deployment) 3. [Deploy the Kubernetes Operator.](/docs/k8s/operator/?requirements=deploy-with-helm&deployment=helm#deployment) **Kubernetes Secrets Injector:** There are two ways to use the 1Password Connect and Operator Helm chart. Select one to get started: 1. [Deploy the Kubernetes Secrets Injector for a Connect server.](/docs/k8s/injector/?workflow-type=connect#deployment) 2. [Deploy the Kubernetes Secrets Injector for a service account.](/docs/k8s/injector/?workflow-type=service-account#deployment) ### Configuration See the [Helm chart configuration values reference](/docs/k8s/helm/) documentation. --- ## Kubernetes Injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets using a [service account](/docs/service-accounts/) or a [Connect server](/docs/connect/) to authenticate to 1Password. Unlike the 1Password [Kubernetes Operator](/docs/k8s/operator/), the Secrets Injector doesn't create a Kubernetes Secret when assigning secrets to your resource. See [Kubernetes integrations](/docs/k8s/integrations/) to compare the Kubernetes Operator and the Kubernetes Injector. :::tip Learn how to use the Kubernetes Secrets Injector with a 1Password Service Account. ::: ## Requirements Before using the Kubernetes Injector, make sure you: - [Sign up for 1Password](https://1password.com/pricing/password-manager). - Have a Kubernetes deployment. You can also use [minikube ](https://minikube.sigs.k8s.io/docs/start/) to test locally. - Create either a [service account](/docs/service-accounts/get-started/) or a [Connect server](/docs/connect/get-started#step-2-deploy-a-1password-connect-server) to authenticate to 1Password. ## Limitations There are some limitations and nuances to consider about the Kubernetes Injector. For example: - The Kubernetes Injector requires deployment specifications to use the `command` field. - Secrets aren't available to all a container's sessions by default. ### The `command` field The Kubernetes Secrets Injector works by changing the `command` value on initialization. As a result, the pod you want to inject secrets into must have a `command` value defined in its [deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) file (as shown in the following code block). See the `command` field in the code block below. In this example, a 1Password Service Account injects secrets into the application run by npm start. ```yaml [{ "badge": "1", "color": "sunbeam", "lineNo": 7, "substr": "npm" }, { "badge": "2", "color": "bitsblue", "lineNo": 8, "substr": "start" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` If the deployments you're using aren't designed to have a command field specified in the deployment, then the 1Password [Kubernetes Operator](/docs/k8s/operator/) might be a better fit for your use case. ### Session availability Injected secrets are available only in the current pod's session. You can only access the secrets for the command listed in the container specification. To access it in any other session, for example, using `kubectl`, it's necessary to prepend `op run --` to the command. In the [service account example deployment specification](#usage-examples), the app-example1 container will have injected the `DB_USERNAME` and `DB_PASSWORD` values in the session executed by the command `npm start`. Another way to have secrets available in all sessions for a container is by using the [Kubernetes Operator](/docs/k8s/operator/). ## Deployment Use the following instructions to configure and deploy the Kubernetes Injector with your service account or Connect server and Kubernetes deployment. **Notes about strings and variables used in these code examples.** Some strings used throughout the code examples on this page are variable and arbitrary. Other strings have specific meanings within the context of 1Password. The following strings used in the code examples on this page have very specific and hard-coded meanings within the context of 1Password: - `OP_CONNECT_HOST` - `OP_CONNECT_TOKEN` - `OP_SERVICE_ACCOUNT_TOKEN` The following strings used in the code examples on this page have are variables and don't have specific meanings within the context of 1Password: - `DB_PASSWORD` - `DB_USERNAME` ### Step 1: Enable secrets injection Use kubectl to enable secrets injection by adding the `secrets-injection=enabled` label to your namespace (NAMESPACE) . The Kubernetes Injector uses the `default` namespace unless you specify a custom namespace. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "NAMESPACE" }] kubectl label namespace NAMESPACE secrets-injection=enabled ``` ### Step 2: Deploy the injector Use the `kubectl apply` command to the deployment specification files. When you use manual deployment, you must apply each deployment specification file separately. In the following example, INJECTOR.yaml is the name of the Kubernetes Injector deployment specification file and CONNECT.yaml is the name of the Connect deployment specification file. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "INJECTOR.yaml" },{ "color": "dahlia", "lineNo": 2, "substr": "CONNECT.yaml" }] kubectl apply -f INJECTOR.yaml kubectl apply -f CONNECT.yaml ``` To undeploy, use `kubectl delete`. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "INJECTOR.yaml" },{ "color": "dahlia", "lineNo": 2, "substr": "CONNECT.yaml" }] kubectl delete -f INJECTOR.yaml kubectl delete -f CONNECT.yaml ``` The commands in this example only deploy the Kubernetes Injector and Connect. They don't handle additional configuration you might need, like [permissions ](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/), [namespaces ](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), and [custom resource definitions (CRD) ](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). :::tip You can deploy and configure the Kubernetes Injector in one command if you use the [1Password Secrets Injector Helm chart](/docs/k8s/helm/). ::: :::info The Kubernetes Injector creates the necessary [TLS certificate ](https://en.wikipedia.org/wiki/Public_key_certificate) for the webhook when it's deployed ([`deployment.yaml` ](https://github.com/1Password/kubernetes-secrets-injector/blob/main/deploy/deployment.yaml)). If you remove the Kubernetes Injector from the cluster, it automatically deletes the TLS certificate. ::: ### Step 3: Annotate your deployment specification Annotate your [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with `operator.1password.io/inject:` followed by a comma-separated list of the containers you want to mutate and inject secrets into. 1. Edit your deployment specification file and add the following annotation: ```yaml title="deployment-specification.yaml" annotations: operator.1password.io/inject: "app-example1, app-example2" ``` ### Step 4: Configure the resource environment Add an environment variable to your pod or [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with a value referencing your 1Password item using a [secret reference](/docs/cli/secret-reference-syntax/). 1. Edit your deployment specification file and add an environment variable containing the path to the 1Password item. Make sure to replace VAULT , ITEM, SECTION, and FIELD with the correct values. ```yaml [{ "color": "tangerine", "lineNo": 3, "substr": "VAULT" }, { "color": "dahlia", "lineNo": 3, "substr": "ITEM" }, { "color": "sunbeam", "lineNo": 3, "substr": "SECTION" }, { "color": "bitsblue", "lineNo": 3, "substr": "FIELD" }] title="deployment-specification.yaml" env: - name: DB_USERNAME value: op://VAULT/ITEM[/SECTION]/FIELD ``` The value should look something like the text in the following code block: ```yaml title="deployment-specification.yaml" env: - name: DB_USERNAME value: op://my-vault/sql/username ``` ### Step 5: Add your 1Password credentials to your deployment #### Step 5.1: Create a Kubernetes Secret with your authentication token To authenticate to 1Password, you'll need to create a [Kubernetes Secret ](https://kubernetes.io/docs/concepts/configuration/secret/) that contains your service account or Connect server token. **Service account:** You can pass your service account token to Kubernetes using the `kubectl create secret` command: :::note Your service account token is generated automatically during the service account creation process. If you lose the token, you must [create a new service account](/docs/service-accounts/get-started/). ::: ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "YOUR_SERVICE_ACCOUNT_TOKEN" }] kubectl create secret generic op-service-account --from-literal=token=YOUR_SERVICE_ACCOUNT_TOKEN ``` This creates a generic Secret named `op-service-account` with a key named `token` that contains your service account token. **Connect:** You can pass your Connect server access token token to Kubernetes using the `kubectl create secret` command: ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "YOUR_CONNECT_TOKEN" }] kubectl create secret generic connect-token --from-literal=token=YOUR_CONNECT_TOKEN ``` This creates a generic Secret named `connect-token` with a key named `token` that contains your Connect server access token. #### Step 5.2: Add the Secret to your Kubernetes deployment specification file You can reference the Secret you created for your service account or Connect server token in your [Kubernetes deployment specification file ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) using an environment variable. Kubernetes will automatically inject the authentication token into your pod or deployment when it starts. **Service account:** Add an environment variable named `OP_SERVICE_ACCOUNT_TOKEN` to your deployment specification file, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. ```yaml [{ "color": "tangerine", "lineNo": 13, "substr": "op-service-account" }, { "color": "bitsblue", "lineNo": 14, "substr": "token" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token ``` **Connect:** 1. Add an environment variable named `OP_CONNECT_HOST` to your deployment specification file for your Connect server host. Set the `value` to the URL where your Connect server is deployed. 2. Add an environment variable named `OP_CONNECT_TOKEN`, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. ```yaml [{ "color": "tangerine", "lineNo": 15, "substr": "connect-token" }, { "color": "bitsblue", "lineNo": 16, "substr": "token" }] title="deployment-specification.yaml" spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_CONNECT_HOST value: http://onepassword-connect:8080 - name: OP_CONNECT_TOKEN valueFrom: secretKeyRef: name: connect-token key: token ``` :::caution If you configure the Kubernetes Injector to authenticate with both a service account and a Connect server, the Connect server will take precedence. ::: ## Usage examples The following Kubernetes deployment specification files show what your deployment file should look like. **Service account:** The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Service Account. In this example, the Kubernetes Injector injects secrets into APP_1, but not APP_2. ```yaml [{ "color": "sunbeam", "lineNo": 12, "substr": "APP_1" },{ "color": "sunbeam", "lineNo": 17, "substr": "APP_1" }, { "color": "tangerine", "lineNo": 33, "substr": "APP_2" }] title="deployment-specification.yaml" apiVersion: apps/v1 kind: Deployment metadata: name: app-example spec: selector: matchLabels: app: app-example template: metadata: annotations: operator.1password.io/inject: APP_1 labels: app: app-example spec: containers: - name: APP_1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password - name: APP_2 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` **Connect:** The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Connect Server. In this example, the Kubernetes Injector injects secrets into APP_1, but not APP_2. ```yaml [{ "color": "sunbeam", "lineNo": 12, "substr": "APP_1" },{ "color": "sunbeam", "lineNo": 17, "substr": "APP_1" }, { "color": "tangerine", "lineNo": 35, "substr": "APP_2" }] title="deployment-specification.yaml" apiVersion: apps/v1 kind: Deployment metadata: name: app-example spec: selector: matchLabels: app: app-example template: metadata: annotations: operator.1password.io/inject: APP_1 labels: app: app-example spec: containers: - name: APP_1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_CONNECT_HOST value: http://onepassword-connect:8080 - name: OP_CONNECT_TOKEN valueFrom: secretKeyRef: name: connect-token key: token-value - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password - name: APP_2 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` --- ## Kubernetes integrations You can use Kubernetes integrations to deploy a [1Password Connect Server](/docs/connect/) or a [1Password Service Account](/docs/service-accounts/) to a Kubernetes cluster. 1Password offers multiple Kubernetes integrations, including the [Kubernetes Secrets Injector](#kubernetes-injector), the [Kubernetes Operator](#kubernetes-operator), and [Helm charts](#1password-helm-charts) (which support both the Kubernetes Injector and the Kubernetes Operator). The best integration option depends on your unique environment. ## Comparison Both the Kubernetes Injector and the Kubernetes Operator work by allowing you to inject secrets from 1Password into a Kubernetes environment. However, they vary slightly based on your intended use case and their requirements. The 1Password Helm charts allow you to more easily deploy a Connect server, the Kubernetes Operator, or the Kubernetes Injector. Refer to the following table to learn the differences between the integrations. | **Feature** | [**Kubernetes Injector**](#kubernetes-injector) | [**Kubernetes Operator**](#kubernetes-operator) | | ----------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- | | Supports service accounts | Yes | Yes | | Supports Connect servers | Yes | Yes | | Allows for granular selection of secrets | Yes | No | | Uses Kubernetes Secrets | No | Yes | | Injects 1Password items directly into Kubernetes pods | Yes | No | | Works with multiple credentials simultaneously | Yes | No | | Supports automatic redeployment when 1Password items change | No | Yes | | Requires a Connect token to deploy | No | Yes | ### Kubernetes Injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets as environment variables into a Kubernetes pod or deployment. You can use the Kubernetes Injector with [Connect servers](/docs/connect/) or [service accounts](/docs/service-accounts/). Get started with the Kubernetes Injector ### Kubernetes Operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers or service accounts. It allows you to: - Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. - Automatically restart deployments when 1Password items update. Get started with the Kubernetes Operator ### 1Password Helm charts [Helm ](https://helm.sh/) is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. The official 1Password Helm charts allow you to create a Secrets Automation workflow deployment using a predefined specification. Get started 1Password Helm charts --- ## Kubernetes Operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers. It allows you to: - Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. - Automatically restart deployments when 1Password items update. ## Requirements Before using the Kubernetes Operator, make sure you finish the requirement steps. The requirements vary slightly depending on how you plan to deploy the Kubernetes Operator. **Deploy with Helm:** Before you can deploy the Kubernetes Operator with the 1Password Connect and Operator Helm chart, you must: Sign up for 1Password. Install 1Password CLI. Have a Kubernetes deployment. You can also use minikube to test locally. Install Helm . Create a Secrets Automation workflow as a Connect server. You need the Connect server's `1password-credentials.json` file. **Deploy manually with Connect:** Before you can deploy the Kubernetes Operator with a Kubernetes deployment specification file, you must: Sign up for 1Password. Install 1Password CLI. Have a Kubernetes deployment. You can also use minikube to test locally. Create a Secrets Automation workflow as a Connect server. You need the Connect server's `1password-credentials.json` file. **Deploy manually with a service account:** Before you can deploy the Kubernetes Operator with a service account, you must: Sign up for 1Password. Have a Kubernetes deployment. You can also use minikube to test locally. ## Limitations The Kubernetes Operator supports Connect servers and service accounts. Additionally, the Operator doesn't allow you to select secrets granularly or use multiple credentials simultaneously. For a complete comparison of features and functionality, see [Kubernetes integrations](/docs/k8s/integrations/). ## Deployment There are two ways to deploy the Kubernetes Operator: 1. Using the 1Password Connect and Operator Helm chart. 2. Manually using a Kubernetes deployment specification file. :::warning[caution] The recommended way to deploy the Kubernetes Operator is with Helm. Deploying manually is a much more involved and complicated process. ::: **Deploy with Helm:** The following instructions cover deploying the Kubernetes Operator using the [1Password Connect and Operator Helm chart](/docs/k8s/helm/). You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes alongside Connect or without Connect. ### Step 1. Add the 1Password Helm chart repository {#helm-step-1} The following command adds the [1Password Helm chart repository ](https://github.com/1Password/connect-helm-charts) to your local instance of Helm. This allows you to download and install all charts from 1Password's GitHub repository. ```shell helm repo add 1password https://1password.github.io/connect-helm-charts/ ``` ### Step 2. Install the Kubernetes Operator using Helm {#helm-step-2} You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes Operator with Connect or without Connect. In most cases, it makes sense to deploy the Kubernetes Operator alongside Connect because it simplifies the setup and communication between Connect and the Operator. However, it might make more sense to deploy only the Kubernetes Operator if you already have a Connect deployment in production. **With Connect:** To install the Kubernetes Operator with Connect, use the following command. It deploys the Kubernetes Operator with a 1Password Connect server using the `1password-credentials.json` file. ```shell [{ "color": "tangerine", "lineNo": 1, "substr": "OP_CONNECT_TOKEN" }] helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=OP_CONNECT_TOKEN ``` If you don't already have a Connect token, use the following command instead. Make sure to replace SERVER and VAULT with the correct values. ```shell [{ "color": "sunbeam", "lineNo": 1, "substr": "SERVER" },{ "color": "dahlia", "lineNo": 1, "substr": "VAULT" }] helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) ``` **Without Connect:** To install the Kubernetes Operator without Connect, set `operator.create` to `true` and `connect.create` to `false`. ```shell helm install connect 1password/connect --set operator.create=true --set operator.token.value= --set connect.create=false ``` If you don't already have a Connect token, use the following command instead. Make sure to replace SERVER and VAULT with the correct values. ```shell [{ "color": "sunbeam", "lineNo": 1, "substr": "SERVER" },{ "color": "dahlia", "lineNo": 1, "substr": "VAULT" }] helm install connect 1password/connect --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) --set connect.create=false ``` **With a service account:** To install the Kubernetes Operator with a service account, set `operator.create` to `true`, `connect.create` to `false`, and `operator.authMethod` to `service-account`. ```shell helm install connect 1password/connect --set operator.create=true --set connect.create=false --set operator.authMethod=service-account --set operator.serviceAccountToken.value= ``` **Deploy manually with Connect:** The following instructions cover deploying the Kubernetes Operator manually, using a [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). 1. [Create a deployment specification.](#manual-step-1) 2. [Create a Kubernetes Secret from the Connect server credentials.](#manual-step-2) 3. [Add the `MANAGE_CONNECT` environment variable.](#manual-step-3) 4. [Create a Kubernetes Secret for the Connect server token.](#manual-step-4) 5. [Deploy the Kubernetes Operator.](#manual-step-5) ### Step 1: Create a deployment specification {#manual-step-1} 1. Create a [Kubernetes deployment specification ](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) YAML file. You can use the example [`manager.yaml` ](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) file from the Kubernetes Operator repository on GitHub. You can also update an existing Kubernetes deployment specification to include the `1password/onepassword-operator` container image and options. ### Step 2: Create a Kubernetes Secret from the Connect server credentials {#manual-step-2} 1. Encode the `1password-credentials.json` file you generated when you created your Connect server and name it FILE_NAME. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "FILE_NAME"}] cat 1password-credentials.json | base64 | \ tr '/+' '_-' | tr -d '=' | tr -d '\n' > FILE_NAME ``` 2. Use `kubectl` to create a Kubernetes Secret from the encoded FILE_NAME file. ```shell [{ "color": "lagoon", "lineNo": 1, "substr": "FILE_NAME"}] kubectl create secret generic op-credentials --from-file=FILE_NAME ``` ### Step 3: Add the `MANAGE_CONNECT` environment variable {#manual-step-3} 1. Add the `MANAGE_CONNECT` environment variable to the Kubernetes Operator container (`onepassword-connect-operator`) in the deployment specification file and set it to `true`. The `MANAGE_CONNECT` environment variable tells the Kubernetes Operator to automatically deploy a default configuration of the 1Password Connect server to the current namespace. ```yaml title="deployment-specification.yaml" - name: MANAGE_CONNECT value: "true" ``` ### Step 4: Create a Kubernetes Secret for the Connect server token {#manual-step-4} Create a Kubernetes Secret for your Connect server token. Replace OP_CONNECT_TOKEN with the Connect token string or an environment variable that contains the Connect token string. ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "OP_CONNECT_TOKEN"}] kubectl create secret generic onepassword-token --from-literal=token="OP_CONNECT_TOKEN" ``` :::tip If you don't already have a Connect server token for the Kubernetes Operator, you can use the following command to create a token and save it as a Kubernetes Secret. ```shell [{ "color": "bitsblue", "lineNo": 1, "substr": "SERVER"}, { "color": "sunbeam", "lineNo": 1, "substr": "VAULT"}] kubectl create secret generic onepassword-token --from-literal=token=$(op connect token create op-k8s-operator --server SERVER --vault VAULT) ``` Make sure to replace SERVER with the name (or ID) of the Connect server and VAULT with the name (or ID) of the vault. ::: ### Step 5: Deploy the Kubernetes Operator and Connect server {#manual-step-5} Finally, manually deploy the Kubernetes Operator by running `make deploy`. :::warning[caution] You must clone the [Kubernetes Operator repository ](https://github.com/1Password/onepassword-operator) before you can manually deploy the Kubernetes Operator. ::: 1. Clone the [Kubernetes Operator repository ](https://github.com/1Password/onepassword-operator). 2. Run `make deploy`. :::tip Run the following command to check if the CRDs installed correctly: ```shell kubectl get crd onepassworditems.onepassword.com ``` ::: **Deploy manually with a service account:** To deploy the Kubernetes Operator with a service account, first [create a service account](/docs/service-accounts/get-started#create-a-service-account). Then follow these steps: ### 1. Create a Kubernetes secret for the service account 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token you created in step 1. This token will be used by the Operator to access 1Password items. 2. Create a Kubernetes secret: ```shell kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN" ``` ### 2. Deploy the Operator To use the Operator with a service account, you need to set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable in the `/config/manager/manager.yaml` file and remove the environment variables `OP_CONNECT_TOKEN` and `OP_CONNECT_HOST`. To configure the 1Password Kubernetes Operator, the following environment variables can be set in the Operator YAML file: - `OP_SERVICE_ACCOUNT_TOKEN` (required): Specifies a service account token within Kubernetes to access the 1Password items. - `WATCH_NAMESPACE`: A comma-separated list of namespaces to watch for changes. The default is `watch all namespaces`. - `POLLING_INTERVAL`: The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password. The default is `600`. - `AUTO_RESTART`: If set to true, the Operator will restart any deployment using a secret from 1Password. This can be overwritten by a namespace, deployment, or individual secret. The default is `false`. After you've set the environment variables, run the following command to deploy the Operator: ```shell make deploy ``` You can view a sample YAML file [in the onepassword-operator repository on GitHub. ](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) ## Usage examples Use the following usage examples to help you get started: - [Create a Kubernetes Secret from a 1Password item](#kubernetes-secret-from-item) - [Deploy with a single Kubernetes Secret](#deploy-single) - [Ignore updates for a Kubernetes Secret](#ignore-updates) - [Enable automatic redeployment](#enable-auto-redeployment) - [Per Kubernetes Operator](#per-kubernetes-operator) - [Per namespace](#per-namespace) - [Per Kubernetes deployment](#per-kubernetes-deployment) - [Per OnePasswordItem](#per-onepassworditem) ### Create a Kubernetes Secret from a 1Password item {#kubernetes-secret-from-item} With the Kubernetes Operator deployed, you can create [Kubernetes Secrets ](https://kubernetes.io/docs/concepts/configuration/secret/) from 1Password items by creating a YAML file and then using `kubectl` to deploy it to your Kubernetes cluster. The YAML file tells the Kubernetes Operator to create a Kubernetes Secret from a `OnePasswordItem` (a 1Password item) and specifies the item name and the path of the item. 1. Create a YAML file (`1password-item.yaml`) for the 1Password item using the following template. Replace `SECRET_NAME`, `VAULT`, and `ITEM` with the correct values for your 1Password item. - Replace SECRET_NAME with the name to use to create the Kubernetes Secret. - Replace VAULT with the name or ID of the vault. - Replace ITEM with the ID or title of the 1Password item. ```yaml title="1password-item.yaml" [{ "color": "dahlia", "lineNo": 4, "substr": "SECRET_NAME" }, { "color": "sunbeam", "lineNo": 6, "substr": "VAULT" }, { "color": "bitsblue", "lineNo": 6, "substr": "ITEM" }] apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: SECRET_NAME spec: itemPath: "vaults/VAULT/items/ITEM" ``` 1. Use `kubectl` to deploy the `1password-item.yaml` file. ```shell kubectl apply -f 1password-item.yaml ``` ```shell kubectl get secret 1password-item.yaml ``` :::warning[caution] If you delete the 1Password item you created, the Kubernetes Operator automatically deletes the corresponding Kubernetes Secret. ::: #### Deploy with a single Kubernetes Secret {#deploy-single} You can also create a single Kubernetes Secret for a Kubernetes deployment by adding specific metadata to the deployment specification file and then applying it. 1. Add the following annotations to the deployment specification file: ```yaml title="deployment-specification.yaml" [{"badge": "🟣", "color": "dahlia", "lineNo": 6, "substr": "VAULT" }, { "color": "bitsblue", "lineNo": 6, "substr": "ITEM" }, { "color": "tangerine", "lineNo": 7, "substr": "SECRET_NAME" }] apiVersion: apps/v1 kind: Deployment metadata: name: deployment-example annotations: operator.1password.io/item-path: "vaults/VAULT/items/ITEM" operator.1password.io/item-name: "SECRET_NAME" ``` Replace `VAULT`, `ITEM`, and `SECRET_NAME`, with the correct values for your 1Password item. - Replace VAULT with the name or ID of the vault. - Replace ITEM with the ID or title of the 1Password item. - Replace SECRET_NAME with the name to use to create the Kubernetes Secret. 2. Apply the YAML file. This creates a Kubernetes Secret named SECRET_NAME with the content from the 1Password item specified in the `operator.1password.io/item-path`. ```shell kubectl apply -f deployment-specification.yaml ``` ### Ignore updates for a Kubernetes Secret {#ignore-updates} The Kubernetes Operator automatically keeps Kubernetes Secrets in sync with the corresponding 1Password items. If a 1Password Item linked to a Kubernetes Secret changes within the `POLLING_INTERVAL`, the associated Kubernetes Secret automatically updates. You can prevent a specific Kubernetes Secret from updating by adding the annotation `operator.1password.io:ignore-secret` to the item stored in 1Password. While this annotation is in place, the Kubernetes Secret won't update when the associated 1Password item updates. ### Enable automatic redeployment {#enable-auto-redeployment} The Kubernetes Operator supports automatic redeployment, which automatically restarts Kubernetes deployments when it detects that a 1Password item linked to a Kubernetes Secret has been updated. When enabled, the Kubernetes Operator restarts Kubernetes deployments that meet the following criteria each time the Connect server polls for updates: - Its scope is configured to automatically restart. - It's using a Kubernetes Secret linked to a 1Password item that's been updated. You can configure automatic redeployment for different scopes: - [Per Kubernetes Operator](#per-kubernetes-operator) - [Per namespace](#per-namespace) - [Per Kubernetes deployment](#per-kubernetes-deployment) - [Per OnePasswordItem](#per-onepassworditem) When you configure automatic deployment in a scope (such as per namespace), the configuration applies to all downstream scopes unless you explicitly specify a different configuration for the scope. #### Per Kubernetes Operator You can configure automatic redeployment per Kubernetes Operator, which includes all Kubernetes deployments within the namespaces watched by the Kubernetes Operator instance. The Kubernetes Operator automatic redeployment setting is controlled by the `AUTO_RESTART` environment variable. By default, it's set to `false`. To enable automatic redeployment, set it to `true`. #### Per namespace You can configure automatic redeployment per namespace, which includes all Kubernetes deployments within the namespace. - To turn on automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `true`. - To turn off automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `false`. Each namespace uses the Kubernetes Operator setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example namespace configuration with automatic redeployment enabled for all Kubernetes deployments within the namespace. ```yaml title="deployment-specification.yaml" {6} apiVersion: v1 kind: Namespace metadata: name: "example-namespace" annotations: operator.1password.io/auto-restart: "true" ``` #### Per Kubernetes deployment You can configure automatic redeployment per individual Kubernetes deployment: - To turn on automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `true`. - To turn off automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `false`. Each Kubernetes deployment uses the namespace setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example deployment configuration with automatic redeployment enabled. ```yaml title="deployment-specification.yaml" {6} apiVersion: v1 kind: Deployment metadata: name: "example-deployment" annotations: operator.1password.io/auto-restart: "true" ``` #### Per OnePasswordItem You can configure automatic redeployment for a specific 1Password item (`OnePasswordItem`) custom resource: - To turn on automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `true`. - To turn off automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `false`. Each 1Password item (`OnePasswordItem`) uses the Kubernetes deployment setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example of a 1Password item configuration with automatic redeployment enabled. ```yaml title="deployment-specification.yaml" {6} apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: example annotations: operator.1password.io/auto-restart: "true" ``` ## Behavior The 1Password Kubernetes Connect Operator follows the Kubernetes Operator pattern. It uses Controllers, which provide a reconcile function that synchronizes resources until it reaches the desired cluster state. Visit the Kubernetes documentation to learn more about the [Operator pattern ](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and [Controllers ](https://kubernetes.io/docs/concepts/architecture/controller/). The information in this section documents some of the behavior of the Kubernetes Operator in specific scenarios. - [Deployment deletion](#deployment-deletion) - [Fields storing files](#fields-storing-files) - [Whitespace characters](#whitespace-characters) ### Deployment deletion Deleting the Deployment you've created deletes the Kubernetes Secret deployment if all the following are true: 1. The deployment has the `operator.1password.io/item-path` and `operator.1password.io/item-name` annotations. 2. No other deployments are using the secret. ### Fields storing files If a 1Password item field stores a file, the corresponding Kubernetes Secret uses the file's contents as the value. If a single 1Password item has a field storing a file and a field storing another type of data, the Kubernetes Operator prefers the non-file field and ignores the field containing a file. ### Whitespace characters Titles and field names that include whitespace characters (or any other characters invalid for DNS subdomain names) result in the Kubernetes Operator changing the titles (or fields) in the following manner when creating Kubernetes Secrets: - Remove invalid characters before the first alphanumeric character. - Remove invalid characters after the last alphanumeric character. - Replace whitespace characters between words with a dash (`-`). - Convert letters to lowercase. ## Configuration The following section describes the Kubernetes Operator (`1password/onepassword-operator`) container configuration options and their default values. The [example Kubernetes deployment specification file ](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure#define-container-environment-variables-using-secret-data) shows these configuration values in context. ### Environment variables | **Environment variable** | **Description** | **Required** | **Default value** | | ------------------------ | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------ | | `OP_CONNECT_HOST` | The hostname of the Connect server within Kubernetes. | Yes | `http://onepassword-connect:8080` | | `WATCH_NAMESPACE` | A comma-separated list of namespaces to watch for changes. By default, it watches all namespaces. | No | default (watch all namespaces) | | `POLLING_INTERVAL` | The number of seconds the Kubernetes Operator should wait before checking for updates from the Connect server. | No | `600` | | `MANAGE_CONNECT` | Whether or not the Kubernetes Operator should deploy with the Connect server in the current namespace with the default configuration. | No | `false` | | `AUTO_RESTART` | Whether or not the Kubernetes Operator should redeploy when it detects a secret change from the Connect server. You can overwrite this value by namespace, deployment, or individual secret. | No | `false` | | `OP_CONNECT_TOKEN` | A reference to the Kubernetes Secret that contains your Connect server token. | Yes | [secretKeyRef ](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure#define-container-environment-variables-using-secret-data) | ### Command arguments | **Argument** | **Description** | **Default value** | | ----------------- | ------------------------------------------------------------ | ----------------- | | `--zap-log-level` | Specify the logging level of detail for the Kubernetes Operator. The available options are `debug`, `info`, and `error`. | `debug` | --- ## 1Password Secrets Automation Manage your secrets with a Secrets Automation workflow that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. You can manage secrets with [1Password Service Accounts](#1password-service-accounts) or [1Password Connect servers](#1password-connect-servers). ## 1Password Service Accounts [Service accounts](/docs/service-accounts/) allow you to automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for 1Password CLI that isn't associated with an individual. Get started with service accounts ## 1Password Connect Servers Alternatively, secure your infrastructure secrets with one or more self-hosted [Connect servers](/docs/connect/). Connect servers allow for more control, scalability, and reduced dependency on the availability of the 1Password API. While 1Password Service Accounts are capped with strict [rate limits](/docs/service-accounts/rate-limits), Connect servers cache your data in your infrastructure. This enables unlimited re-requests after the server fetches your secrets for the first time. 1Password also maintains several SDK libraries for the [Connect API](/docs/connect/api-reference/) so you can integrate with your existing applications. Get started with Connect ## Comparison Review the following comparison table to learn about the different features and limitations of service accounts and Connect servers. | | Service accounts | Connect servers | | ------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------- | | [1Password CLI](/docs/connect/cli/) | Yes | Yes | | REST API | No | Yes | | Self-hosted | No | Yes | | Infrastructure requirements | No | Yes | | Low overhead | Yes | No | | Low latency | No | Yes | | [Kubernetes integrations](/docs/k8s/integrations/) | Yes | Yes | | [CI/CD integrations](/docs/ci-cd/) | Yes | Yes | | Rate limits | Yes | No | | Request quotas | Yes | No | | Included with 1Password subscription | Yes | Yes | --- ## Get started with 1Password Service Accounts With 1Password Service Accounts, you can build tools to automate secrets management in your applications and infrastructure without deploying additional services. Service accounts can: - Create, fetch, edit, delete, and share items. - Read environment variables from [1Password Environments](/docs/environments). - Create vaults. - Delete vaults. A service account can only delete a vault it created. See service account security. - Retrieve information about users and groups. Each service account has a [service account token](/docs/service-accounts/security#service-accounts-and-token-generation) that you can provide as an environment variable for authentication. You can choose which vaults and [Environments](/docs/environments) the service account can access and its permissions in each vault. **Limitations** Service accounts have the following limitations: - Service accounts have [rate limits and request quotes](/docs/service-accounts/rate-limits/). - You can't grant a service account access to your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, or your default [Shared](https://support.1password.com/1password-glossary#shared-vault) vault. - Service accounts can only be granted read access to Environments. - Service accounts only work with 1Password CLI version 2.18.0 or later. See [Use service accounts with 1Password CLI](/docs/service-accounts/use-with-1password-cli/). - You can't use service accounts with the [Kubernetes Operator](/docs/k8s/operator/) (only the [Kubernetes Secrets Injector](/docs/k8s/injector/)). ## Requirements Before you can create and use service accounts, you'll need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - Have adequate account permissions to create service accounts. If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). ## Create a service account You can create a service account on 1Password.com or with [1Password CLI](/docs/cli/). Service account permissions, vault access, and Environment access are immutable. If you want to grant a service account access to additional vaults or Environments, change the permissions it has in the vaults it can access, or change its ability to create new vaults, you'll need to create a new service account with the appropriate permissions and access. **1Password.com:** To create a service account on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Open the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal).Or navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Service Account**. 3. Follow the onscreen instructions: 1. Choose a name for the service account. 2. Choose whether the service account can create vaults. 3. Choose the vaults the service account can access.You can't grant a service account access to your built-in Personal, Private, or Employee vault, or your default Shared vault. 4. Select the settings icon next to each vault to choose the permissions the service account has in the vault. This can't be changed later. 5. Choose which [1Password Environments](/docs/environments) the service account can access. This can't be changed later. 5. Select **Create Account** to create the service account. 6. Select **Save in 1Password** to save the service account token in your 1Password account. In the next window, enter a name for the item and choose the vault where you want to save it. :::danger The service account creation wizard only shows the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. ::: You can find your new service account under "Service accounts" on the [**Developer**](https://start.1password.com/developer-tools/active) page. **1Password CLI:** :::note Use the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal) on 1Password.com if you want to create a service account that can access 1Password Environments. ::: To create a service account with 1Password CLI: 1. Make sure you have the latest version of [1Password CLI](/docs/cli/get-started/) on your machine. 2. Create a new service account using the [`op service-account create` command](/docs/cli/reference/management-commands/service-account#service-account-create): ```shell op service-account create --expires-in --vault , ``` Available permissions: `read_items`, `write_items` (requires `read_items`), `share_items` (requires `read_items`) Include the `--can-create-vaults` flag to allow the service account to create new vaults. If the service account or vault name contains one or more spaces, enclose the name in quotation marks (for example, β€œMy Service Account”). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, myServerName). Service accounts can't be modified after they're created. If you need to make changes, revoke the service account and create a new one. 3. Save the service account token in your 1Password account. 4. If you want to start using the service account with 1Password CLI, [export the token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable](/docs/service-accounts/use-with-1password-cli#get-started). For example, to create a service account named `My Service Account` that has read and write permissions in a vault named `Production`, can create new vaults, and expires in 24 hours: ```shell op service-account create "My Service Account" --can-create-vaults --expires-in 24h --vault Production:read_items,write_items ``` :::danger 1Password CLI only returns the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. ::: :::caution If your [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) changes, you'll need to [rotate your service account tokens](/docs/service-accounts/manage-service-accounts#rotate-token). ::: ## Next steps Explore the following to learn about how you can use service accounts. - [Use a service account with 1Password CLI.](/docs/service-accounts/use-with-1password-cli/) - [Manage a service account.](/docs/service-accounts/manage-service-accounts/) - [Integrate a service account with a CI/CD pipeline.](/docs/ci-cd/) - [Integrate a service account with Kubernetes.](/docs/k8s/integrations/) :::tip Need help? [Join our Developer Slack workspace](https://developer.1password.com/joinslack) to ask questions and provide feedback. ::: --- ## Manage service accounts ## Manage active service accounts Owners and administrators can manage all service accounts created by their team. Other team members with the [permission to create service accounts](#manage-who-can-create-service-accounts) can manage their own service accounts, but not service accounts created by other people. You can view and manage a service account from its overview page on 1Password.com. The service account overview page shows information about the service account, such as the vaults and [1Password Environments](/docs/environments) it can access, vault permissions, and recent activity. To manage a service account, go to the service account overview: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose the service account you want to manage. ### Create a usage report for a service account To create a [usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault) for a service account: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. On the service account overview page, select **View Item Usage Report**. Usage reports for service accounts include information on the number of vaults and items a service account can access, an overview of vaults where a service account has accessed items, when those items were last accessed, and the action performed. ### Change a service account's name {#change-name} To change a service account's name: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Select **Edit Details**. 5. Type a new name, then select **Save**. ### Rotate a service account token {#rotate-token} Rotating a service account token generates a new token with the same permissions. You can also specify an expiration for the current token, so you have time to update to the new token without any interruption in service. Take note of any places where you may need to update a service account token before you rotate it. This helps you set a more reasonable expiration time. To rotate a service account token: 1. [Sign in](https://start.1password.com/sign-in/) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Rotate Token**. 5. Select a value for **Expire existing token** to set when the token will expire. For example, you can set the existing token to expire **now** (immediately), in **1 hour**, or in **3 days**. 6. Enter the service account name to confirm. 7. Select **Rotate Token**. 8. Select **Save in 1Password** to save the new token value in 1Password. :::caution If your [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) changes, make sure to rotate your service account tokens. Your tokens will redirect to the new sign-in address for 30 days. ::: ### Revoke a service account token {#revoke-token} Revoking a service account token immediately removes its access to 1Password vaults. You might want to revoke a token if it becomes compromised or unnecessary. To revoke a service account token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Revoke Token**. 5. Enter the service account name to confirm, then select **Revoke Token**. ## Manage service account settings With 1Password Teams and 1Password Business, you can manage who on your team can create service accounts and which vaults the service accounts can access. ### Manage who can create service accounts By default, only [owners and administrators](https://support.1password.com/groups/) can create and manage service accounts in 1Password Teams and 1Password Business. To allow other groups to create service accounts, an owner or administrator can: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Permissions** at the top of the Developer page, then select **Service Account**. 4. Select **Manage groups**, choose the groups you want to allow to create service accounts, then select **Update Groups**. Team members in the selected groups will be able to create service accounts. To manage which individual team members can create service accounts, change from the Groups tab to the People tab. Select **Manage People**, choose the team members you want to allow to create service accounts, then select **Update People**. Each team member with permission to create service accounts will only be able to manage their own service accounts, not service accounts created by other people. ### Manage which vaults team members can grant access to Team members can only grant service accounts access to a vault if they have the appropriate permissions in the vault: | Account type | Permission | | --- | --- | | 1Password Teams | `Allow Managing` | | 1Password Business | `Manage Vault` | You can manage team members' permissions in vaults [with 1Password CLI](/docs/cli/grant-revoke-vault-permissions) or [on 1Password.com](https://support.1password.com/create-share-vaults-teams#manage-permissions). ### Manage service account access to vaults Team administrators can control service account access to 1Password vaults by turning access to a vault off or on. A vault's service account access setting applies to all service accounts. If you turn off service account access in a vault, existing service accounts will lose access to that vault and new service accounts can't be granted access. After you create a service account, you can't add additional vaults or edit any vault permissions it has. To turn service account access on or off for a vault: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Choose the vault you want to change service account access to. 3. Select **Manage**. 4. Under Service Account Access, select the toggle to turn access on or off. ## Get help ### If you need to change a service account's permissions or access After you create a service account, you can't give it access to additional vaults or [1Password Environments](/docs/environments), change its permissions in the vaults it can access, or change its ability to create new vaults. If you want to edit a service account's access or permissions, you'll need to create a new service account. You can [create a service account](/docs/service-accounts/get-started#create-a-service-account) on 1Password.com or with 1Password CLI. --- ## 1Password Service Accounts 1Password Service Accounts help automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for [1Password CLI](/docs/cli/) that isn't associated with an individual. You control which vaults and Environments are accessible and which actions the service account can perform. And you can see what items a service account accesses by creating a [usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault). You can create up to 100 service accounts. :::tip Not sure if service accounts are for you? See the [secrets automation comparison table](/docs/secrets-automation#comparison). ::: ## Use cases You can use 1Password Service Accounts to accomplish a variety of tasks: - **Provision web services with secrets**: Use a service account to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a service account to provision an account with the needed secret and allow the web service to access the secret during test runs. - **Load secrets into CI/CD pipelines**: Use a service account to automatically access your secrets in continuous integration environments. If you've committed code and want to automatically run your CI/CD pipeline with credentials stored in a 1Password vault, you can use a service account to automatically access your secrets and use them for testing and deploying code while maintaining security without tying sensitive information to a personal user account. - **Automate secrets management**: Use service accounts to automate scripts to manage secrets. Using a service account helps you implement the principal of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). - **Create a test environment**: Use a service account in a test environment while using Connect in production. Using a service account for your test environment allows you to create a similar test environment while keeping secrets or access compartmentalized. You can use service accounts to automatically access secrets in the test environment without having to set up Connect. - **Secure infrastructure secrets**: Use service accounts to make sure infrastructure secrets aren't tied to a personal user account. - **Streamline development workflows**: Use service accounts to securely share and manage infrastructure secrets to streamline development workflows. ## Get started Learn how to get started and how to create, manage, and integrate with service accounts. Get started --- ## Service account rate limits 1Password Service Accounts have hourly limits and daily limits. [Hourly limits](#hourly-limits) control the number of read and write actions a service account can perform within a 60-minute window. [Daily limits](#daily-limits) determine the total number of requests that all service accounts within a 1Password account can make in a 24-hour window. Some 1Password CLI commands make more than one request. You can use [`op service-account ratelimit`](/docs/cli/reference/management-commands/service-account#service-account-ratelimit) to get rate limit usage data for the service account currently set with the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. To get information about a specific service account, specify a service account by its name or ID. ```bash op service-account ratelimit #code-result TYPE ACTION LIMIT USED REMAINING RESET token write 1000 0 1000 N/A token read 10000 3 9997 59 minutes from now account read_write 50000 3 49997 23 hours from now ``` :::tip Learn which 1Password CLI commands [make multiple requests](/docs/service-accounts/use-with-1password-cli#commands-that-make-multiple-requests). ::: ## Hourly limits Service account tokens have hourly limits applied to both read and write actions independently. The 60-minute time window begins after 1Password receives the first request. Your 1Password account type determines the hourly limits. | Account type | Action | Limit | Period | Scope | | -------------------------------------------------- | ------ | ------ | ------ | ------------------------- | | [1Password Business](https://support.1password.com/explore/business/) | Read | 10,000 | 1 hour | Per service account token | | | Write | 1,000 | 1 hour | Per service account token | | 1Password, [1Password Families](https://support.1password.com/explore/families/), and [1Password Teams](https://support.1password.com/explore/team-admin/) | Read | 1,000 | 1 hour | Per service account token | | | Write | 100 | 1 hour | Per service account token | If you exceed the hourly limit, you'll receive the following error: ```text variant="bad" Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this service account is allowed to make. Please retry in 59 minutes or try other requests. ``` :::tip If you hit an hourly limit, you can: - Wait for the 60-minute window to reset. - [Change your 1Password account type.](https://support.1password.com/change-account-type/) - [Contact 1Password support.](https://support.1password.com/contact/) - [Create a new service account.](/docs/service-accounts/get-started/) Hourly limits are scoped per service account token. ::: ## Daily limits 1Password has daily limits in place that determine the total number of requests that all service accounts can make over a 24-hour period. Your 1Password account type determines the daily limit. | Account type | Action | Limit | Period | Scope | | -------------------------------- | ---------- | ------ | -------- | --------------------- | | [1Password Business](https://support.1password.com/explore/business/) | Read/Write | 50,000 | 24 hours | Per 1Password account | | [1Password Teams](https://support.1password.com/explore/team-admin/) | Read/Write | 5,000 | 24 hours | Per 1Password account | | 1Password and [1Password Families](https://support.1password.com/explore/families/) | Read/Write | 1,000 | 24 hours | Per 1Password account | If you exceed the daily limit, you'll receive the following error: ```text variant="bad" Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this 1Password account is allowed to make. Please retry in 23 hours and 59 minutes or try other requests. ``` :::tip If you hit a daily limit, you can: - Wait for the 24-hour window to reset. - [Change your 1Password account type.](https://support.1password.com/change-account-type/) - [Contact 1Password support.](https://support.1password.com/contact/) ::: --- ## 1Password Service Account security You can automate managing secrets in your apps and systems with [1Password Service Accounts](/docs/service-accounts/). No need for extra services. Explore the sections on this page to learn more about service account security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When creating a service account, you choose the vaults it can access and its level of access. The service account only returns information from vaults it can access. You can also give service accounts permission to create and manage vaults. ## Service accounts and token generation A service account is a type of user account that's meant for programmatic access. Service accounts differ from regular 1Password accounts in that you don't need to provide an email or an [account password](https://support.1password.com/1password-glossary#1password-account-password). When a regular user account creates a master key, the user must provide an email, a [Secret Key](https://support.1password.com/1password-glossary#secret-key), and an account password. When a service account user creates a master key, 1Password generates all the input. | Element | Regular user | Service account | |------------|--------------|-----------------| | Secret Key | Generated | Generated | | Password | User provided | Generated | 1Password uses the Secret Key and the password as part of the [two-secret key derivation (2SKD)](#2skd) process to create the following: - [Account Unlock Key (AUK)](#auk) - [Secure Remote Password (SRP)](#srp) After deriving these two items, 1Password discards the password used to create them. Each user, whether a regular user or a service account user, has a [personal keyset](#personal-keyset) that 1Password generates when you create the user account. The AUK encrypts the personal keyset, and 1Password uses the personal keyset to encrypt and decrypt vaults. A service account token is an authentication string that represents an SRPx object that's serialized and Base64 URL encoded. The service account token allows a service account to authenticate with 1Password CLI. 1Password creates the service account token by serializing the Account Unlock Key (AUK), Secure Remote Password (SRP), and the personal keyset into a [JSON Web Token (JWT) ](https://jwt.io/), then Base64 encoding it. See the following examples of a service account token encoded and decoded. **Encoded:** Encoded service account token: ```jwt ops_eyJlbWFpbCI6ImVqd2U2NHFtbHhocmlAMXBhc3N3b3Jkc2VydmljZWFjY291bnRzLmxjbCIsIm11ayI6eyJhbGciOiJBMjU2R0NNIiwiZXh0Ijp0cnVlLCJrIjoiTThWUGZJYzhWRWZUaGNNWExhS0NLRjhzTWg1Sk1ac1BBdHU5MmZRTmItbyIsImtleV9vcHMiOlsiZW5jcnlwdCIsImRlY3J5cHQiXSwia3R5Ijoib2N0Iiwia2lkIjoibXAifSwic2VjcmV0S2V5IjoiQTMtQzRaSk1OLVBRVFpUTC1IR0w4NC1HNjRNNy1LVlpSTi00WlZQNiIsInNycFgiOiI4NzBkNjdhOWU2MjY2MjVkOWUzNjg1MDc4MDRjOWMzMmU2NjFjNTdlN2U1NTg3NzgyOTFiZjI5ZDVhMjc5YWUxIiwic2lnbkluQWRkcmVzcyI6ImdvdGhhbS5iNWxvY2FsLmNvbTo0MDAwIiwidXNlckF1dGgiOnsibWV0aG9kIjoiU1JQZy00MDk2IiwiYWxnIjoiUEJFUzJnLUhTMjU2IiwiaXRlcmF0aW9ucyI6MTAwMDAwLCJzYWx0IjoiRk1SVVBpeXJONFhmXzhIb2g2WVJYUSJ9fQ ``` **Decoded:** Decoded service account token: ```json { "email": "ejwe64qmlxhri@1passwordserviceaccounts.lcl", "muk": { "alg": "A256GCM", "ext": true, "k": "M8VPfIc8VEfThcMXLaKCKF8sMh5JMZsPAtu92fQNb-o", "key_ops": [ "encrypt", "decrypt" ], "kty": "oct", "kid": "mp" }, "secretKey": "A3-C4ZJMN-PQTZTL-HGL84-G64M7-KVZRN-4ZVP6", "srpX": "870d67a9e626625d9e368507804c9c32e661c57e7e558778291bf29d5a279ae1", "signInAddress": "gotham.b5local.com:4000", "userAuth": { "method": "SRPg-4096", "alg": "PBES2g-HS256", "iterations": 100000, "salt": "FMRUPiyrN4Xf_8Hoh6YRXQ" }, "throttleSecret": { "seed": "ddc20da89d71ff640f36bb6c446c64d56a2123eb4e7bd9c89ce303075eea5780", "uuid": "TP4Z5ZB7IJABDPGIVSUZLY4T5A" }, "deviceUuid": "ay5shynibdyqisjz3j63b7uygy" } ``` :::info 1Password uses a unique string format to help code analyzers find accidental credential exposure. The format uses "`ops_`" as the token prefix. ::: The steps to create the token happen on your device (client-side); nothing sensitive goes to 1Password's servers. It's up to you to save and protect the service account token. ### Token rotation and revocation {#token-rotation} You can rotate or revoke service account tokens. You might want to revoke or rotate a service account token if a service account token became compromised or you need to comply with a security policy that requires regular token rotation. - [Learn how to revoke a service account token.](/docs/service-accounts/manage-service-accounts#revoke-token) - [Learn how to rotate a service account token.](/docs/service-accounts/manage-service-accounts#rotate-token) ## Security model The 1Password Service Account security model has the following guarantees: - A service account can only read items from vaults it has READ access to. - A service account can only update, delete, and create items for vaults it has WRITE access to. - The creator of a service account can only grant the service account access to vaults that the creator has access to. - You can't grant a service account access to vaults that have service accounts turned off, even if the creator of the service account has permissions to manage the vault. - Disabling service accounts for a vault removes access to that vault from all pre-existing service accounts. - By default, account [owners](https://support.1password.com/1password-glossary#owner) and [administrators](https://support.1password.com/1password-glossary#administrator) can create service accounts. - All owners and administrators can view service account details and delete service accounts, but they can't view the generated service account token. - Owners and administrators can [give other team members access](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts) to create and manage their own service accounts. - Team members can only grant service accounts access to a vault if they have the `Manage Vault` permission for that vault. - A service account token associated with a deleted service account can't authenticate. - You can't add vault access to a generated service account after creation. - A service account can't create another service account. - A service account can't manage users. ## Terminology ##### Account Unlock Key {#auk} The Account Unlock Key (AUK) is a key derived from the [2SKD process](#2skd). It's used to decrypt a user's [personal keyset](#personal-keyset). It's derived from the user's account password and Secret Key. Previously known as the β€œMaster Unlock Key”. ##### Personal keyset Each user account (whether a regular user or a service account) has a personal keyset that consists of a public and private key pair that's used to encrypt and decrypt vaults. ##### Secure Remote Password {#srp} The Secure Remote Password (SRP) is a key derived from the [2SKD process](#2skd). It's used for the Secure Remote Password protocol, which is a method for both a client and a server to authenticate each other without either revealing any secrets. ##### Service account token {#service-account-token} A service account token is an authentication string that grants a service account access to one or more 1Password vaults. You can use service account tokens to authenticate services and tools, such as the 1Password CLI. ##### Two-secret key derivation {#2skd} Two-secret key derivation (2SKD) is a type of key derivation function that uses two user secrets (the Account password and Secret Key) to derive two independent keys (the [Account Unlock Key](#auk) and the [Secure Remote Password](#srp)). ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne. ](https://hackerone.com/1password) --- ## Use service accounts with 1Password CLI You can use 1Password Service Accounts with 1Password CLI to manage vaults and items. See [supported commands](#supported-commands). ## Requirements Before you use service accounts with 1Password CLI, you need to: - [Sign up for 1Password.](https://1password.com/pricing/password-manager) - Install [1Password CLI](/docs/cli/get-started/). Service Accounts require 1Password CLI version 2.18.0 or later. - [Create a service account.](/docs/service-accounts/get-started#create-a-service-account) ## Get started To use a service account with 1Password CLI: 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token: **bash, sh, zsh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **Powershell:** ```shell $Env:OP_SERVICE_ACCOUNT_TOKEN = "" ``` 2. Run the following command to make sure the service account is configured: ```shell {9} op user get --me # code-result ID: Name: Email: State: ACTIVE Type: SERVICE_ACCOUNT Created: 2 minutes ago Updated: 2 minutes ago Last Authentication: now ``` :::warning[caution] If you have 1Password CLI configured to work with [1Password Connect](/docs/connect/), the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables take precedence over `OP_SERVICE_ACCOUNT_TOKEN`. Clear the Connect environment variables to configure a service account instead. ::: ### Supported commands You can now run supported 1Password CLI commands authenticated as the service account: - [`op read`](/docs/cli/reference/commands/read/) - [`op inject`](/docs/cli/reference/commands/inject/) - [`op service-account ratelimit`](/docs/cli/reference/management-commands/service-account#service-account-ratelimit) - [`op run`](/docs/cli/reference/commands/run/) - [`op vault create`](/docs/cli/reference/management-commands/vault#vault-create) To use the following commands, you must specify a vault with the `--vault` flag if the service account has access to more than one vault: - [`op item`](/docs/cli/reference/management-commands/item/) - [`op document`](/docs/cli/reference/management-commands/document/) The following commands are only supported for vaults created by the service account: - [`op vault delete`](/docs/cli/reference/management-commands/vault#vault-delete) - [`op vault group grant`](/docs/cli/reference/management-commands/vault#vault-group-grant) - [`op vault user grant`](/docs/cli/reference/management-commands/vault#vault-user-grant) - [`op vault group revoke`](/docs/cli/reference/management-commands/vault#vault-group-revoke) - [`op vault user revoke`](/docs/cli/reference/management-commands/vault#vault-user-revoke) **Unsupported commands** When using a service account, the following commands aren't supported: - [`op connect`](/docs/cli/reference/management-commands/connect) - [`op group`](/docs/cli/reference/management-commands/group/) - [`op user provision`](/docs/cli/reference/management-commands/user#user-provision) - [`op user confirm`](/docs/cli/reference/management-commands/user#user-confirm) - [`op user suspend`](/docs/cli/reference/management-commands/user#user-suspend) - [`op user delete`](/docs/cli/reference/management-commands/user#user-delete) - [`op user recovery`](/docs/cli/reference/management-commands/user#user-recovery) - [`op events-api`](/docs/cli/reference/management-commands/events-api/) - [`op vault edit`](/docs/cli/reference/management-commands/vault#vault-edit) Although service accounts support some user, group, and vault management commands, we recommend against using them because a full provisioning workflow isn't supported: - [`op user get`](/docs/cli/reference/management-commands/user#user-get) - [`op user list`](/docs/cli/reference/management-commands/user#user-list) - [`op group get`](/docs/cli/reference/management-commands/group#group-get) - [`op group list`](/docs/cli/reference/management-commands/group#group-list) ### Commands that make multiple requests Service accounts have [hourly and daily limits](/docs/service-accounts/rate-limits) on the total number of requests the service account can make. You can sometimes reduce the number of requests made by passing a vault or item's [unique identifier (ID)](/docs/cli/reference#unique-identifiers-ids) instead of its name. 1Password CLI commands make one request unless otherwise noted. The following commands make more than one request: | Command | Total requests | Notes | | --- | --- | --- | | `op item list` | 1 + 1 per vault the service account has access to | To limit total requests to 3, list items in a specific vault using the `--vault` flag. Pass the vault's ID to further limit requests to 2. | | `op item get` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op item create` | 1 read and 1 write | To reduce to 1 request, pass the vault ID. | | `op item delete` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op item edit` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op read` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op vault delete` | 2 reads + 1 write | To reduce the read requests by 1, pass the vault ID. | | `op vault edit` | up to 3 writes | The number of requests may vary depending on how many changes are made with a single command. | | `op vault get` | 2 reads | To reduce the read requests by 1, pass the vault ID. |