Migrate your team from SecretHub to 1Password

This guide shows you how to migrate to 1Password Secrets Automation. You can read more about the acquisition and Secrets Automation in the announcement post.

We’re available to help you plan and execute your team’s migration. Contact us to schedule a meeting: Schedule a call (EU customers) Schedule a call (US customers)

Before you begin

  1. Sign up for 1Password and invite your team.
  2. Upgrade to the latest version of the SecretHub CLI. To assist you in the migration, we’ve added some helper commands.
  3. Install the 1Password command-line tool, then run eval $(op signin) to sign in.

1. Migrate your secrets

To migrate your secrets, you’ll need to generate a migration plan. Your migration plan is a YAML file that specifies which 1Password vaults and items will be used to store your secrets. You can review and edit this plan, then apply it.

1.1 Generate a migration plan

Your migration plan will include vaults containing items with one or more fields. Vaults are used to organize items and they’re where you’ll set access rules for users and services. You can create a separate vault for each project or environment. Items are used to store related secrets together in individual fields. For example, if you used SecretHub to create four separate secrets to store the username, password, host, and port of a database connection, you’ll create a single item in 1Password and store those four secrets as individual fields within that item.

If a field contains sensitive information that should be concealed, such as a password, set the concealed key to true for that field. For example, if you create a database item with username, password, host, and port fields, you can use the concealed: true key for the password field to hide the password.

A 1Password item for a database connection, having a concealed password field and visible fields for username, host, and port.
A 1Password item for a database connection, having a concealed password field and visible fields for username, host, and port.

When you’re ready, generate a migration plan using the secrethub migrate plan command. If you run the command without any arguments, it will create a migration plan that includes all the secrets you have access to. To migrate your projects individually, add an argument with one or more paths to the command. The migration plan will then only contain the secrets you have access to in those directories or workspaces. For example:

# Include just the tst and dev environments of your-project in the plan
secrethub migrate plan your-company/tst/your-project your-company/dev/your-project

# Include just personal secrets in the plan
secrethub migrate plan your-username

# Include just secrets from your company workspace in the plan
secrethub migrate plan your-company

1.2 Review and adjust the migration plan

After you generate the migration plan, open and review it. By default, the plan is created in ./1password-migration-plan.yml.

For reference, here’s an example SecretHub tree and the corresponding migration plan:

my-company/my-project/
├── dev/
│   ├── aws/
│   │   └── secret-key
│   ├── db/
│   │   ├── host
│   │   ├── password
│   │   ├── port
│   │   └── user
│   └── stripe/
│       └── api-token
└── prd/
    ├── aws/
    │   └── secret-key
    ├── db/
    │   ├── host
    │   ├── password
    │   ├── port
    │   └── user
    └── stripe/
        └── api-token
sign-in-address: https://mycompany.1password.com
vaults:
- vault-name: my-project-prd
  items:
  - item-name: stripe
    fields:
    - field-name: api-token
      value: secrethub://my-company/my-project/prd/stripe/api-token
      concealed: true
  - item-name: db
    fields:
    - field-name: password
      value: secrethub://my-company/my-project/prd/db/password
      concealed: true
    - field-name: user
      value: secrethub://my-company/my-project/prd/db/user
      concealed: false
    - field-name: host
      value: secrethub://my-company/my-project/prd/db/host
      concealed: false
    - field-name: port
      value: secrethub://my-company/my-project/prd/db/port
      concealed: false
  - item-name: aws
    fields:
    - field-name: secret-key
      value: secrethub://my-company/my-project/prd/aws/secret-key
      concealed: true
- vault-name: my-project-dev
  items:
  - item-name: stripe
    fields:
    - field-name: api-token
      value: secrethub://my-company/my-project/dev/stripe/api-token
      concealed: true
  - item-name: db
    fields:
    - field-name: password
      value: secrethub://my-company/my-project/dev/db/password
      concealed: true
    - field-name: user
      value: secrethub://my-company/my-project/dev/db/user
      concealed: false
    - field-name: host
      value: secrethub://my-company/my-project/dev/db/host
      concealed: false
    - field-name: port
      value: secrethub://my-company/my-project/dev/db/port
      concealed: false
  - item-name: aws
    fields:
    - field-name: secret-key
      value: secrethub://my-company/my-project/dev/aws/secret-key
      concealed: true

The plan command will attempt to detect secrets that should be grouped together in an item, as well as fields that don’t need to be concealed, based on the secret names. Review the plan and make adjustments as needed. You can:

  • Merge fields that belong together into a single item
  • Change concealed of fields
  • Rename vaults, items, and fields
  • Move items between vaults
  • Create, delete or merge vaults

1.3 Apply the migration plan

When you’re ready to apply your migration plan, run secrethub migrate apply to create the resources specified in the plan. You can now access your secrets in 1Password! 🎉

2. Migrate team access

1Password lets you to manage each user’s access to vaults, similar to access rules used in SecretHub. You can also use built-in groups and set access rules for those groups, rather than the individual users. With 1Password Business you can also create custom groups, to make access control more scalable.

Invite people to join your team on 1Password, if you haven’t done so already, and share vaults with individuals or groups. Similar to SecretHub, you can manage permissions for indidivuals or groups in each vault to control the level of access they have to items.

3. Migrate integrations

After you migrate your secrets from SecretHub, you can set up your applications and services to get your secrets from 1Password. 1Password Secrets Automation offers you a whole new range of integrations that get information from 1Password through REST API requests to a Connect server. A list of integration guides is included below.

Contact us on Discord or by email if you have any questions or suggestions.

3.1 Connect

With SecretHub, all integrations connect directly to the SecretHub API. Every time a secret is used, the encrypted data is fetched from the SecretHub servers. In contrast, with 1Password Secrets Automation, you can securely access secrets in your company’s apps and cloud infrastructure using a private REST API provided by a self-hosted 1Password Connect server, which uses 1Password.com as a backend. This means secrets are served to your applications with very low latency and in the rare event that the 1Password.com API is down, your secrets are still served from the Connect server.

Your applications fetch secrets from Connect using any of the integrations or by using the Connect API directly.

Secrets served to your applications via the Connect Server.
Secrets served to your applications via the Connect Server.

3.2 Integrations