Teams and Businesses

Automate provisioning in 1Password Business using SCIM

Learn how to set up and use the 1Password SCIM bridge to integrate with your identity provider.

With 1Password Business, you can automate many common administrative tasks using the 1Password SCIM bridge. It uses the System for Cross-domain Identity Management (SCIM) protocol to connect 1Password with your existing identity provider, like Azure Active Directory or Okta, so you can:

  • Create users and groups, including automated account confirmation
  • Grant and revoke access to groups
  • Suspend deprovisioned users

You’ll set up and deploy the SCIM bridge on a server in your own environment, not on a 1Password server, so the encryption keys for your account are only available to you and no one else. To set up and deploy the SCIM bridge, you’ll need:

  • a Mac or Linux computer
  • a server with a publicly accessible static IP address
  • a DNS record to allow for encrypted (HTTPS) communication to the SCIM bridge

Then follow the steps below.

Step 1: Set up the SCIM bridge

Before you can deploy the 1Password SCIM bridge, you’ll need an OAuth bearer token and encrypted scimsession file. To securely generate them, clone the scim-examples repository and run the setup script locally on your own system.

1.1: Install Docker

The SCIM bridge setup process requires Docker. On your local system, install Docker.

1.2: Clone the scim-examples repository

All of the scripts and configuration files needed to set up and deploy the SCIM bridge are available in the scim-examples repository on GitHub.

To clone the repository, open your terminal app, switch to the directory where you want to clone the repository, and run the following command:

git clone https://github.com/1Password/scim-examples.git

1.3: Run the setup script

The setup script will create a group called “Provision Managers”, give it the required permissions for provisioning, and create a new user account in that group.

Make sure you have a separate email address (or an email alias) to use for the new user account. You can’t reuse the email address that you use for your administrator account.

To begin the setup process, run the included setup script:

./scim-setup.sh

From now on, the Provision Manager account can be used with the SCIM bridge to provision people.

Important

The bearer token and scimsession file combined can be used to sign in to your Provision Manager account. You’ll need to share the bearer token with your identity provider, but it’s important to never share it with anyone else. And never share your scimsession file with anyone at all.

Step 2: Deploy the SCIM bridge

Tip

The easiest way to install the SCIM bridge is by using a container, which can run on a Docker- or Kubernetes-based system such as Google Kubernetes Engine, Azure Container Instances, Digital Ocean Kubernetes Service, and others.

To make sure the SCIM bridge is secure and accessible, configure your deployment environment:

  • Use encrypted storage to secure the scimsession file at rest.
  • If you’re not using LetsEncrypt, configure an API gateway, proxy, or load balancer to terminate TLS for the bridge.
  • If you deploy the SCIM bridge behind a load balancer, configure it with a private subnet that allows incoming connections from the load balancer on port 3002.

The SCIM bridge writes to standard output (stdout) for easy log collection.

Learn how to deploy the SCIM bridge in your environment:

Kubernetes

Docker

AWS with Terraform

Step 3: Connect your identity provider to the SCIM bridge

Because the 1Password SCIM bridge provides a SCIM 2.0-compatible web service that accepts OAuth bearer tokens for authorization, you can use it with a variety of identity providers.

Learn how to connect your identity provider:

Azure Active Directory

Okta

Get help

The 1Password SCIM bridge requires:

  • 1Password Business
  • a deployment environment with:

    • access to port 443 and 80 to enable LetsEncrypt or a gateway with TLS termination
    • Docker or Kubernetes
    • 128 MB of RAM
    • 100 MB of available storage
  • a supported SCIM 2.0-compatible identity provider: Azure Active Directory or Okta

If you lose your bearer token or session file

Your OAuth bearer token and scimsession file are cryptographically linked. If you lose either one, you’ll need to generate a new bearer token and session file. Then deploy the SCIM bridge again.

If you change the account details for your Provision Manager account

If you change the Master Password, Secret Key, or email address for the account you created for provision management, you’ll need to generate a new bearer token and session file. Then deploy the SCIM bridge again.

If a new version of the SCIM bridge is available

If you receive an email notification about a new version of the SCIM bridge, update it:

  1. Visit 1Password SCIM bridge on Docker Hub and note the tag with the most recent version number.
  2. Edit your YAML configuration file and update it with the version number you noted:

    Deployment environment Edit this YAML file
    Docker docker-compose.yml
    Kubernetes op-scim-deployment.yaml

  3. Run one of the following commands to apply the update:

    Deployment environment Run this command
    Docker Compose docker-compose up
    Docker Swarm docker stack deploy
    Kubernetes kubectl apply

If you still need help

For more information about the SCIM bridge, contact your 1Password Business representative. To get help and share feedback, join the discussion in the 1Password Support forum.

Published: