setup

1Password

Purpose

Shows who can reach which 1Password vaults. Subimage ingests users, guests, service accounts, groups, vault grants with their permissions, and item metadata such as category and last update time. It never reads item fields or secret values.

The open source 1Password collector runs on a schedule in your cloud and holds the 1Password credential. It writes a JSON snapshot to a bucket you own, and Subimage reads only that snapshot.

Setup takes three steps: create a 1Password service account, deploy the collector with a bucket that Subimage can read, then enter the bucket in Subimage.

Required Fields

Field Description
onepassword_source Bucket and folder where the collector writes its snapshot: s3://my-bucket/onepassword/, gs://my-bucket/onepassword/, or azblob://account/container/onepassword/.
onepassword_aws_account_id 12-digit ID of the AWS account that owns the S3 bucket. Leave empty for Google Cloud Storage or Azure Blob Storage.

The collector's deployment examples print both values as Terraform outputs.

Setup Steps

1. Create a 1Password service account

The collector reads 1Password with a service account that has Read Items access to the vaults you want covered. 1Password doesn't let service accounts access the built-in Private, Employee, or Shared vaults, and it doesn't add new vaults to a service account automatically.

  1. Find your account ID and vault IDs:

    op account get --format json   # "id" is the account ID
    op vault list
  2. Create the service account and store its token in AWS Secrets Manager. Repeat --vault for each vault. The tr command removes the trailing newline that --raw prints:

    op service-account create "Subimage collector" \
      --vault <vault-id>:read_items \
      --raw | tr -d '\n' \
      | aws secretsmanager create-secret --name onepassword-collector-token \
          --secret-string file:///dev/stdin

    For Google Cloud, store the token in Secret Manager instead. Anyone with the token can read the items in those vaults, so only the collector should be able to read the secret.

2. Deploy the collector

Pick the example for the cloud that holds the bucket. Each one creates the bucket, the scheduled collector, and its least-privilege roles, and accepts no inbound traffic.

Amazon S3 with ECS Fargate

Use the ECS example. In its terraform.tfvars, set these two values so the example also creates the read-only role that Subimage assumes:

subimage_tenant_role_arn = "arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly"
subimage_external_id     = "subimage-onepassword-<TENANT_ID>"

Google Cloud Storage with Cloud Run

Configure the GCP integration in Modules first. Then use the Cloud Run example, and add the principal of your Subimage GCP integration to snapshot_readers.

Kubernetes or another runtime

Run the published image on any schedule, such as the Kubernetes CronJob example:

docker run --rm -e OP_SERVICE_ACCOUNT_TOKEN \
  ghcr.io/subimagesec/collectors/1password:0.1.1 \
  --account-id <account-id> \
  --vault-id <vault-id> \
  --output s3://my-bucket/onepassword/snapshot.json

Repeat --vault-id for each vault, and use gs:// for Google Cloud Storage. For Azure Blob Storage, write to a local file and upload it with az storage blob upload. Then give Subimage read access to the bucket as described in Set up bucket access yourself, below.

Snapshots include vault names and item titles, so Subimage can name the vaults and items a person can reach. To leave them out, add --omit-titles; Subimage then shows only IDs.

3. Enable 1Password in Subimage

  1. In Modules → 1Password, set onepassword_source to the example's subimage_onepassword_source output.
  2. For S3, set onepassword_aws_account_id to the subimage_onepassword_aws_account_id output.
  3. Save the module and run a sync.

Set up bucket access yourself

Skip this section if you used the ECS or Cloud Run example.

Amazon S3

Create a read-only role in the bucket's AWS account. It must be named SubImageOnePasswordRole, trust your tenant's Subimage role with the external ID subimage-onepassword-<TENANT_ID>, and allow only s3:ListBucket and s3:GetObject on the snapshot folder.

AWSTemplateFormatVersion: "2010-09-09"
Description: Read-only 1Password snapshot access for Subimage

Resources:
  SubImageOnePasswordRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: SubImageOnePasswordRole
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::<ACCOUNT_ID>:role/<TENANT_ID>-subimage-readonly
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: subimage-onepassword-<TENANT_ID>
      Policies:
        - PolicyName: ReadOnePasswordSnapshots
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Sid: ListSnapshots
                Effect: Allow
                Action: s3:ListBucket
                Resource: arn:aws:s3:::{{BUCKET_NAME}}
                Condition:
                  StringLike:
                    s3:prefix: onepassword/*
              - Sid: ReadSnapshots
                Effect: Allow
                Action: s3:GetObject
                Resource: arn:aws:s3:::{{BUCKET_NAME}}/onepassword/*

If the bucket uses a customer-managed KMS key, also grant the role kms:Decrypt on that key.

Google Cloud Storage

Configure the GCP integration in Modules first. Grant its service account or Workload Identity Federation principal roles/storage.objectViewer on the bucket.

Azure Blob Storage

Configure the Azure integration in Modules first. Grant its service principal Storage Blob Data Reader on the container.

Notes

  • Each sync reads every .json object under the folder and keeps the newest snapshot for each 1Password account. Use a folder that holds only collector snapshots.
  • Run one collector per 1Password account. A sync stops if two snapshots for the same account cover different vaults, and it skips a snapshot that is older than the one Subimage already ingested.
  • Access that 1Password revoked disappears on the first sync after the collector runs.
  • The snapshot_collected_at property on OnePasswordAccount shows when the ingested snapshot was collected. If it falls behind your schedule, check that the collector still runs and that its output reaches the bucket.
  • A user can reach a vault directly or through groups. Ask the Subimage assistant, for example, "Who can reveal passwords in our infrastructure vault?"

Troubleshooting

  • No 1Password snapshot: confirm the collector ran and wrote a .json file under the configured folder.
  • Unrecognized file in 1Password prefix: move other .json files out of the folder.
  • Incomplete 1Password snapshot: delete the snapshot and rerun the collector.
  • Unsupported 1Password snapshot version: use a collector release that writes schema version 1.x.
  • Conflicting 1Password snapshot scopes: run one collector per 1Password account, and delete snapshots left from an earlier vault scope.
  • S3 AssumeRole failed: check the role name, the trusted role ARN, the external ID, and the AWS account ID against step 2.
  • GCS or Azure access failed: check that the GCP or Azure module is enabled and its principal can read the bucket.
  • Collector reports that SDK authentication failed: check that the stored token has no trailing newline, or upgrade to collector 0.1.1 or later, which strips it.
  • Collector reports that the 1Password CLI is outdated: update the collector image. 1Password rejects old CLI releases.