1Password Configuration#

Cartography reads snapshots that the open source 1Password collector, maintained by Subimage, produces. Run the collector first, then point Cartography at its output.

Prerequisites#

A 1Password Business account
The 1Password collector, running on a schedule in your environment. See its setup guide.

Authentication#

Cartography never authenticates to 1Password. The collector uses a 1Password service account token. Cartography authenticates only to the storage that holds the snapshots, with its usual provider credentials.

Required Permissions#

Source	Permissions required
Local file or directory	Read access to the files
Amazon S3	`s3:ListBucket` on the bucket and `s3:GetObject` on the prefix
Google Cloud Storage	`storage.objects.list` and `storage.objects.get` on the bucket
Azure Blob Storage	Storage Blob Data Reader on the container

Configure Cartography#

Set --onepassword-source to one of the following:

A snapshot .json file
A local directory that contains snapshots
An s3://bucket/prefix, gs://bucket/prefix, or azblob://account/container/prefix URI

Use a prefix that contains only 1Password snapshots. Cartography reads every .json object under it on each sync, so have the collector overwrite one fixed object per account rather than keep timestamped copies.

Note

The module is named onepassword because identifiers can’t start with a digit. 1password isn’t a valid Python module name or keyword argument, and Neo4j labels such as 1PasswordUser would need backticks in every query. Use onepassword in --selected-modules, --onepassword-source, and the OnePassword* node labels. 1Password’s own Python SDK uses the same name.

Run Cartography#

cartography --selected-modules onepassword,ontology \
    --onepassword-source s3://example-snapshots/onepassword/

To test with a local snapshot:

cartography --selected-modules onepassword,ontology \
    --onepassword-source ./output/onepassword.json

Include ontology after onepassword to link 1Password users to canonical users from your other identity sources.

Input Artifacts#

Generate Input Artifacts#

The collector writes one snapshot per run:

onepassword-collector \
    --account-id <account-uuid> \
    --vault-id <vault-uuid> \
    --output s3://example-snapshots/onepassword/snapshot.json

Repeat --vault-id for every vault to cover. The service account must have Read Items access to each one.

Input Format#

Cartography accepts snapshots that use schema version 1.x and have the status complete. The collector repository documents the snapshot format.

Each snapshot covers one account and the vaults the collector was configured to read. Run one collector per account. When the source holds several snapshots for the same account, Cartography ingests only the most recently collected one. Anything that snapshot no longer contains is deleted from that account, so a revoked grant disappears on the next sync. After you remove a vault from the collector’s scope and delete snapshots that still list it, the next sync removes that vault from the graph.

Cartography stops before changing the graph if any snapshot in the source is incomplete, malformed, or unreadable, uses an unsupported schema version, or covers different vaults than another snapshot of the same account. It also skips an account whose snapshot is older than the one already in the graph. An older snapshot could otherwise restore access that 1Password already revoked.

OnePasswordAccount.snapshot_collected_at records when the collector finished. If it falls behind your collection schedule, the snapshot is stale: check that the collector still runs and that its output still reaches the source. The graph shows access as of that time.

Troubleshooting#

Error	Fix
`No 1Password snapshots found`	Check that the source path or prefix contains the collector’s `.json` output.
`is not a 1Password collector snapshot`	Remove other JSON files from the prefix, or point to a narrower prefix.
`uses unsupported snapshot schema version`	Upgrade Cartography to a version that supports the collector’s schema.
`cover different vaults`	Run one collector per account, and delete snapshots left from an earlier vault scope.
`Skipping 1Password account ... is older than the ingested snapshot`	Check why the source holds an older snapshot, such as a restored backup or a second collector.