Teams and Businesses

Get started with 1Password Events Reporting and Elastic

Learn how to send your 1Password account activity to Elasticsearch using the 1Password Events API Beat.

With 1Password Business, you can send your account activity to Elasticsearch using the 1Password Events API Beat. Get reports about 1Password activity like sign-in attempts and item usage while you manage all your company’s applications and services from a central location.

With 1Password Events Reporting and Elastic, you can:

  • Control your 1Password data retention
  • Build custom graphs and dashboards
  • Set up custom alerts that trigger specific actions
  • Cross-reference 1Password events with the data from other services

You can set up Events Reporting if you’re an owner, administrator, or part of a group with the View Administrative Sidebar permission.

Step 1: Set up an Events Reporting integration

To get started, sign in to your 1Password account, click Integrations in the sidebar, and choose Elastic.

Then follow these steps to add an Elastic integration to your 1Password account and create a bearer JSON web token:

  1. Enter a name for the integration, then click Add Integration.
  2. Enter a name for the bearer token and choose when it will expire. Select the event types the token has access to, then click Issue Token.
  3. Click Save in 1Password and choose which vault to save your token to. Then click View Integration Details.

You can now use your bearer token to authenticate the 1Password Events API Beat with Elasticsearch.

You can issue or revoke bearer tokens at any time.

Step 2: Connect your 1Password account to Elastic

The 1Password Events API Beat returns information from 1Password through requests to the Events REST API and sends that data securely to Elasticsearch. Requests are authenticated with a bearer token. Issue a token for each application or service you use.

To connect your 1Password account to Elastic:

  1. Download and install the 1Password Events API Elastic Beat  from the 1Password GitHub repository.

  2. Download an example eventsapibeat.yml file  .

  3. Configure the YAML file for the Beat to include:

    • The bearer token you saved previously in the auth_token fields for each 1Password event type you plan to monitor.
    • The output for events (sent directly to Elasticsearch, or through Logstash).
    • Any other configurations you want to customize.

Step 3: Run the 1Password Events API Beat

After you’ve set up the 1Password Events Reporting integration for Elastic, installed the 1Password Events API Beat, and configured the YAML file, run the following command:

./eventsapibeat -c eventsapibeat.yml -e

You can now use Elasticsearch with the 1Password Events API Beat to monitor events from your 1Password account. The returned data will follow the Elastic Common Schema (ECS) specifications.

Appendix: Issue or revoke bearer tokens

Issue a bearer token

  1. Sign in to your account on 1Password.com and click Integrations in the sidebar.
  2. Choose the Events Reporting integration where you want to issue a token and click “Add a token”.
  3. Enter a name for the bearer token and choose when it will expire. Select the event types the token has access to, then click Issue Token.
  4. Click Save in 1Password and choose which vault to save your token to. Then click View Integration Details.

Revoke a bearer token

Important

Elasticsearch will stop ingesting events after a token is revoked. To minimize downtime, issue a replacement token before you revoke one.

  1. Sign in to your account on 1Password.com and click Integrations in the sidebar.
  2. Choose the Events Reporting integration where you want to revoke a token.
  3. Click next to the token you want to revoke, then click Revoke.

Update a bearer token in Elastic

If you issue a new bearer token in 1Password, you’ll need to update the token in the eventsapibeat.yml file, then restart the Beat.

Appendix: Elastic Beat YAML file schema

    eventsapibeat:
      insecure_skip_verify: false
      signin_attempts:
        enabled: true
        auth_token: ""
        sample_frequency: "10s"
        cursor_state_file: "signinattempts.eventsapibeatstate"
        starting_cursor: >
          { "limit": 1000, "start_time": "2020-01-01T00:00:00Z" }
      item_usages:
        enabled: true
        auth_token: ""
        sample_frequency: "10s"
        cursor_state_file: "itemusages.eventsapibeatstate"
        starting_cursor: >
          { "limit": 1000, "start_time": "2020-01-01T00:00:00Z" }

	#output.logstash:
	#  hosts: ["localhost:5044"]

	#output.console:
	#  pretty: true

	output.elasticsearch:
      hosts: ["localhost:9200"]
      index: "%{[agent.type]}-%{[agent.version]}-%{[@metadata][event_type]}-%{+yyyy.MM}"
	setup.ilm.enabled: false
	setup.template.name: "eventsapibeat"
	setup.template.pattern: "eventsapibeat-*"
Name Type Description
insecure_skip_verify boolean Whether to verify the Events API certificate chain and host name.
signin_attempts object A Sign-in attempts object.
item_usages object An Item usages object.

Sign-in attempts object

Name Type Description
enabled boolean Whether to return sign-in attempts when running the Beat.
auth_token string An Events Reporting bearer JSON web token.

The bearer token it must have access to the sign-in attempts feature.

sample_frequency string The number of seconds to wait between attempts to return new events.
cursor_state_file string A file where the last cursor position is saved, for future calling of the Events API.
starting_cursor string An Events API ResetCursor JSON string.

Item usages object

Name Type Description
enabled boolean Whether to return item usage events when running the Beat.
auth_token string An Events Reporting bearer JSON web token.

The bearer token it must have access to the item usage feature.

sample_frequency string The number of seconds to wait between attempts to return new events.
cursor_state_file string A file where the last cursor position is saved, for future calling of the Events API.
starting_cursor string An Events API ResetCursor JSON string.

Learn more about how to configure the outputs for Elasticsearch , Logstash , the Console , and more .

Appendix: List of 1Password event types

Event type Description
Item usage Returns information about items in shared vaults that have been modified, accessed, or used.
Sign-in attempts Returns information about sign-in attempts (successful and failed).

Appendix: Elastic Common Schema

The 1Password Events API Beat returns data using the Elastic Common Schema (ECS)  specifications.

Sign-in attempts

Field Description
@timestamp The date and time of the sign-in attempt. Uses the RFC 3339 standard .
event.action The category of the sign-in attempt.
user.id The UUID of the user that attempted to sign in to the account.
user.full_name The name of the user, hydrated at the time the event was generated.
user.email The email address of the user, hydrated at the time the event was generated.
os.name The name of the operating system of the user that attempted to sign in to the account.
os.version The version of the operating system of the user that attempted to sign in to the account.
source.ip The IP address that attempted to sign in to the account.
onepassword.uuid The UUID of the event.
onepassword.session_uuid The UUID of the session that created the event.
onepassword.type Details about the sign-in attempt.
onepassword.country The country code of the event. Uses the ISO 3166 standard .
onepassword.details Additional information about the sign-in attempt, such as any firewall rules that prevent a user from signing in.
onepassword.client.app_name The name of the 1Password app that attempted to sign in to the account.
onepassword.client.app_version The version number of the 1Password app.
onepassword.client.platform_name The name of the platform running the 1Password app.
onepassword.client.platform_version The version of the browser or computer where the 1Password app is installed, or the CPU of the machine where the 1Password command-line tool is installed.

Item usage

Field Description
@timestamp The date and time of the sign-in attempt. Uses the RFC 3339 standard .
user.id The UUID of the user that accessed the item.
user.full_name The name of the user, hydrated at the time the event was generated.
user.email The email address of the user, hydrated at the time the event was generated.
os.name The name of the operating system the item was accessed from.
os.version The version of the operating system the item was accessed from.
source.ip The IP address the item was accessed from.
onepassword.uuid The UUID of the event.
onepassword.used_version The version of the item that was accessed.
onepassword.vault_uuid The UUID of the vault the item is in.
onepassword.item_uuid The UUID of the item that was accessed.
onepassword.client.app_name The name of the 1Password app the item was accessed from.
onepassword.client.app_version The version number of the 1Password app.
onepassword.client.platform_name The name of the platform the item was accessed from.
onepassword.client.platform_version The version of the browser or computer where the 1Password app is installed, or the CPU of the machine where the 1Password command-line tool is installed.

Get help

To change the event types a token has access to, issue a new token.

To get help with Events Reporting, or to share feedback, contact the 1Password Business team.

Learn more

Published: