Keen documentation
Open Keen ↗

Administering Keen

1Password audit, item usage and sign-in events

Chapter 34 of 40

1Password

1Password is a built-in, read-only ingester for the 1Password Events API. It collects audit events, item usage and sign-in attempts from a 1Password Business or Enterprise account, so changes to people, vaults and settings, and every sign-in, can stand as evidence.

Create the token and configure Keen

  1. In 1Password, open Integrations and set up an Events Reporting integration for Keen.
  2. Issue a bearer token for it and select the event types Keen may read: audit events, item usage, sign-in attempts. The token reads events only; it cannot open a vault.
  3. Set these in Keen's .env and recreate the API, worker and beat containers:
    KEEN_OP_EVENTS_ENABLED=true
    KEEN_OP_EVENTS_BASE_URL=https://events.1password.com
    KEEN_OP_EVENTS_TOKEN=YOUR_BEARER_TOKEN
    KEEN_OP_EVENTS_CONFIG_PATH=/app/config/op_events.yml
    KEEN_OP_EVENTS_POLL_SECONDS=900
    

The server depends on where the account is hosted:

AccountEvents API server
1password.comhttps://events.1password.com
1Password Enterprisehttps://events.ent.1password.com
1password.cahttps://events.1password.ca
1password.euhttps://events.1password.eu

Create a named 1Password source for each account and add stream inputs to each; the Environment default connection uses the deployment settings. Settings and source names use op_events, since Keen treats any setting whose name contains “password” as a secret.

Going deeper: transport security

The token travels in the Authorization header and stays out of the URL and request body. Keen sends it to those four servers alone: any other server is refused when the source is saved and again before each run. HTTPS and certificate verification are mandatory, redirects are refused, each request ends within two minutes and responses are limited to 8 MiB. A saved token is write-only, and changing the server requires it to be entered again.

Select streams in Keen

Define a 1Password source with its server and token, then select Add input on that source in Sources & evidence mapping. Enter one stream for each input:

An optional label becomes the event's system; otherwise it is 1Password. The shipped stream list is empty, so enabling the adapter alone collects nothing; add a stream, then use Ingest runners → Run 1Password or wait for the scheduled run. The token must be allowed to read each stream you add; a stream it may not read reports HTTP 401 while the other streams are collected.

Going deeper: the YAML file and its settings

Administrators can also manage config/op_events.yml; saved web-UI configuration overrides it.

ui_name: 1Password
badge_color: '#0A6ADB'
streams:
  - stream: signinattempts
    # label: Company vault
  - stream: auditevents
initial_lookback_days: 7
page_size: 100
max_pages: 100

initial_lookback_days is how far back the first run of a stream reads (0 to 365). page_size is the number of events in a page (1 to 1,000) and max_pages the pages one run reads from each stream (1 to 1,000).

Going deeper: positions, restarts and limits

1Password returns a position with every page. Keen stores each page of events, commits it with that position and only then asks for the next, so a run that fails, or is stopped at its time limit, keeps everything before the failure and the next run continues from there. A run that reaches max_pages reports that more remains, which the next run reads.

If 1Password no longer accepts a saved position, or page_size changes, Keen starts the stream again from five minutes before the newest event it has stored. Events read a second time are recognised by their identifiers and stored once. HTTP 429 and transient failures keep the position and are retried on the next scheduled run, with no rapid retry loop; 1Password allows 600 requests a minute and 30,000 an hour.

An entry that is not an event object is left out and counted as invalid_records in the run's result, and the events around it are stored. An event without a readable time is dated when it was collected. A page holding more events than were asked for, and a position that repeats, stop the stream with an error and keep its last good position.

Map 1Password evidence

Choose Create mapping, source op_events. Leave collection selection broad, or select a configured stream, and use a real event or structured conditions to refine it.

StreamEvent actionOutcomeActor
signinattemptssignin. and the category, such as signin.success, signin.credentials_failed, signin.mfa_failedsuccess for success and firewall_reported_success; otherwise failureEmail of the account signed in to
auditeventsaudit., the object type and the action, such as audit.user.suspend or audit.vault.createinfoEmail or name of the person who acted
itemusagesitem. and the action, such as item.reveal, item.fill, item.exportinfoEmail of the person who used the item

Example: source op_events, outcome failure, mapped to your authentication-monitoring control, records each failed sign-in. A second mapping on action audit.user.suspend evidences leaver handling.

Going deeper: useful JSON paths
  • event.category, event.type, event.country, event.target_user.email (sign-in attempts)
  • event.client.ip_address, event.client.app_name (sign-in attempts and item usage)
  • event.action, event.object_type, event.actor_details.email, event.session.ip (audit events)
  • event.vault_uuid, event.item_uuid, event.user.email (item usage)

The whole event 1Password returned is kept under event in the payload and in the artifact. Events use the standard Keen redaction, artifact storage, SHA-256 and framework-rule pipeline. Item usage names vaults and items by identifier; 1Password does not send item titles, usernames or secrets through this API.

Scope

This adapter reads the three event streams of the Events API. It does not read vault contents, and it cannot change anything in 1Password. The Events API requires 1Password Business or Enterprise. The source is unavailable in demo environments.

Official API documentation: