This example explains how to deploy the 1Password SCIM bridge on a Kubernetes cluster. It assumes your Kubernetes cluster supports "load balancer" services.

You can modify this deployment to suit your environment and needs.

If you are deploying to the Azure Kubernetes Service, you can refer to our detailed deployment guide instead.

The deployment process consists of these steps:

Create a Kubernetes Secret with your scimsession file
(Optional) Create Kubernetes Secrets for Google Workspace
Deploy 1Password SCIM bridge to your cluster
Create a DNS record for SCIM bridge
Configure Let's Encrypt

Structure

op-scim-deployment.yaml: The Deployment object for the SCIM bridge container.
op-scim-service.yaml: Public load balancer for SCIM bridge to enable connectivity for your idenitty provider.
op-scim-config.yaml: Configuration for the SCIM bridge Deployment.
redis-deployment.yaml: A Redis cache deployed in the cluster.
redis-service.yaml: Kubernetes Service for the Redis cache to enable connectivity inside the cluster.
redis-config.yaml: Configuration for the Redis cache.

Preparing

Ensure you've read through the PREPARATION.md document before beginning deployment.

Clone `scim-examples`

As seen in PREPARATION.md, you’ll need to clone this repository using git into a directory of your choice.

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

You can then browse to the Kubernetes directory:

cd scim-examples/kubernetes/

Create the `scimsession` Kubernetes Secret

The following requires that you’ve completed the initial setup of Automated User Provisioning in your 1Password account. See our support article for more details.

Once complete, create a Kubernetes Secret containing the contents of the scimsession credentials file. Using --from-file=[key=]source when creating the Kubernetes Secret, we can create the Kubernetes Secret named scimsession, specify the scimsession key, and set its value as the contents of the scimsession file in one command (replace ./scimsession if the file is saved in another directory and/or with a different filename):

kubectl create secret generic scimsession --from-file=scimsession=./scimsession

(Optional) Create the Google Workspace Kubernetes secrets

This section is only relevant to those enrolled in our Google Workspace provisioning beta. Contact your 1Password Sales Representative for more information on this initiative.

First, you’ll need to edit the file located at scim-examples/beta/workspace-settings.json, and fill in the values according to those presented in our Google Workspace documentation.

kubectl create secret generic workspace-settings --from-file=/path/to/workspace-settings.json

Then, you will need to provide the Google Service Account key file, also generated according to our documentation. Substitute <keyfile> with the filename generated by Google for your Google Service Account.

kubectl create secret generic workspace-credentials --from-file=/path/to/<keyfile>.json

Deploy to the Kubernetes cluster

Run the following command deploy SCIM bridge:

kubectl apply -f .

Create the DNS record

The op-scim-bridge Service creates a public load balancer attached to your cluster that forwards TLS traffic to SCIM bridge.

Run the following command, and copy the address listed under the External IP column for to the op-scim-bridge Service from the output:

kubectl get svc

Note: It can take a few minutes before the public address becomes available. Run the command again if doesn't appear in the output.

Create a public DNS record pointing to this address as outlined in the preparation guide.

Configure Let's Encrypt

After the DNS record above has propagated, run the following command to set the OP_LETSENCRYPT_DOMAIN environment variable to the fully-qualified domain name (FQDN) for SCIM bridge based on this record (replace scim.example.com with the FQDN):

kubectl set env deploy/op-scim-bridge OP_LETSENCRYPT_DOMAIN=scim.example.com

SCIM bridge will restart and acquire a TLS certificate using Let's Encrypt.

Testing the instance

You can test your instance by requesting https://[your-domain]/scim/Users, with the header Authorization: Bearer [bearer token] which should return a list of the users in your 1Password account.

You can do this with curl, as an example:

curl --header "Authorization: Bearer TOKEN_GOES_HERE" https://<domain>/scim/Users

You can now continue with the administration guide to configure your Identity Provider to enable provisioning with your SCIM bridge.

Updating

To update SCIM bridge, connect to your Kubernetes cluster and run the following command:

kubectl set image deploy/op-scim-bridge op-scim-bridge=1password/scim:v2.5.0

This will upgrade your SCIM bridge to the latest version, which should take about 2-3 minutes for Kubernetes to process.

October 2020 Upgrade Changes

As of October 2020, the scim-examples Kubernetes deployment now uses op-scim-config.yaml to set the configuration needed for your SCIM bridge, and has changed the deployment names from op-scim to op-scim-bridge, and redis to op-scim-redis for clarity and consistency.

You’ll need to re-configure your options in op-scim-config.yaml, particularly OP_LETSENCRYPT_DOMAIN. You may also want to delete your previous op-scim and redis deployments to prevent conflict between the two versions.

kubectl delete deployment/op-scim deployment/redis
kubectl apply -f .

You’ll then need to update your SCIM bridge’s domain name DNS record. You can find the IP for that with:

kubectl describe service/op-scim-bridge
# look for ‘LoadBalancer Ingress’

This is a one-time operation to change the deployment and service names of the SCIM bridge so they are more easily identifiable to administrators.

April 2021 Upgrade Changes (SCIM bridge 2.0)

With the release of SCIM bridge 2.0, the environment variables OP_REDIS_HOST and OP_REDIS_PORT have been deprecated and in favour of OP_REDIS_URL. Ensure that your op-scim-config.yaml file has changed to reflect this new environment variable, and reapplied to your pods with:

cd scim-examples/kubernetes
git pull
kubectl delete configmaps op-scim-configmap
kubectl apply -f .
kubectl scale deploy op-scim-bridge --replicas=0 && sleep 3 && kubectl scale deploy op-scim-bridge --replicas=1

Advanced deployments

The following are helpful tips in case you wish to perform an advanced deployment.

External load balancer

In op-scim-config.yaml, you can set the OP_LETSENCRYPT_DOMAIN variable to blank, which will have the SCIM bridge serve on port 3002. You can then map your pre-existing webserver (Apache, NGINX, etc). You will no longer be issued a certificate by LetsEncrypt.

External redis server

If you are using an existing redis instance that's not running on redis://redis:6379, you can change the OP_REDIS_URL variable in op-scim-config.yaml.

You would then omit the the redis-*.yaml files when deploying to your Kubernetes cluster.

Human-Readable Logs

You can set OP_PRETTY_LOGS to 1 if you would like the SCIM bridge to output logs in a human-readable format. This can be helpful if you aren’t planning on doing custom log ingestion in your environment.

Debug Mode

You can set OP_DEBUG to 1 to enable debug output in the logs. Useful for troubleshooting or when contacting 1Password Support.

Health Check Ping Server

When using Let’s Encrypt on some Kubernetes clusters, health checks can fail for the SCIM bridge before the bridge is able to obtain a Let’s Encrypt certificate.

You can set OP_PING_SERVER to 1 to enable a /ping endpoint on port 80 so that health checks will always be brought online. For security reasons, no other endpoints (such as /scim) are exposed through this port.

The endpoint is disabled if OP_LETSENCRYPT_DOMAIN is set to blank and TLS is not utilized.

README.md Unescape Escape

Deploying the 1Password SCIM bridge on Kubernetes