Skip to content
This repository has been archived by the owner on Jun 16, 2023. It is now read-only.

Latest commit

 

History

History
 
 

kubernetes

README.md

Deploying the 1Password SCIM bridge on Kubernetes

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:

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

Structure

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

For Google Workspace customers only

This section is only relevant if Google Workspace is your identity provider. If you are not connecting 1Password to Google Workspace, please proceed to Deploy to the Kubernetes cluster.

Create a Google service account

Create a Google service account and key as outlined in the 1Password support article Connect Google Workspace to 1Password SCIM Bridge.

Download the credentials file provided by Google and save a copy to your 1Password account.

Create a Kubernetes secret for the Google service account credential

Using the credential file you just downloaded, create a kubernetes secret, substituting <keyfile> with the filename generated by Google for your Google Service Account.

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

Create a Workspace settings Kubernetes secret

In order to provide the SCIM bridge with necessary information about your Google Workspace account, you’ll need to edit the file located at scim-examples/beta/workspace-settings.json, filling in correct values for:

  • Actor: the email address of the administrator in Google Workspace that the service account is acting on behalf of.
  • Bridge Address: the URL you will use for your SCIM bridge (not your 1Password account sign-in address). This is most often a subdomain of your choosing on a domain you own. For example: https://scim.example.com.

Once you have edited the file, save it and run the following command to create a kubernetes secret from the settings file.

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

Deploy to the Kubernetes cluster

Run the following command deploy SCIM bridge:

kubectl apply -f .

If you are a Google Workspace customer and have stored your workspace-credentials.json and workspace-settings.json files in the same directory as your deployment files, you may see the following error after running kubectl apply -f .:

error validating "workspace-credentials.json": error validating data: [apiVersion not set, kind not set]; if you choose to ignore these errors, turn validation off with --validate=false
error validating "workspace-settings.json": error validating data: [apiVersion not set, kind not set]; if you choose to ignore these errors, turn validation off with --validate=false

You can safely ignore these errors, or move the workspace-credentials.json and workspace-settings.json to a different directory before running 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_TLS_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_TLS_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.8.1

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_TLS_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

Resource Recommendations

The default resource recommendations for the SCIM bridge and Redis deployments are acceptable in most scenarios, but they fall short in high volume deployments where there is a large number of users and/or groups. We strongly recommend increasing both the SCIM bridge and Redis deployments.

Expected Provisioned Users Resources
1-1000 Default
1000-5000 High Volume Deployment
5000+ Very High Volume Deployment

Our current default resource requirements (defined in op-scim-deployment and redis-deployment.yaml) are:

Default 
requests:
  cpu: 125m
  memory: 256M

limits:
  cpu: 250m
  memory: 512M

Note that these are the recommended requests and limits values for both the SCIM bridge and Redis containers. These values can be scaled down again to the default values after the initial large provisioning event.

High Volume Deployment 
requests:
  cpu: 500m
  memory: 512M

limits:
  cpu: 1000m
  memory: 1024M
Very High Volume Deployment 
requests:
  cpu: 1000m
  memory: 1024M

limits:
  cpu: 2000m
  memory: 2048M

Configuring these values can be done with Kubernetes commands. You can get the names of the deployments with kubectl get deployments.

# scale down deployment
kubectl scale --replicas=0 deployment/op-scim-bridge

# scale down redis deployment
kubectl scale --replicas=0 deployment/op-scim-bridge-redis-master

# update op-scim-redis resources
kubectl set resources deployment op-scim-bridge-redis-master -c=redis --requests=cpu=250m,memory=512M --limits=cpu=500m,memory=1024M

# update op-scim-bridge resources
kubectl set resources deployment op-scim-bridge -c=op-scim-bridge --requests=cpu=500m,memory=512M --limits=cpu=1000m,memory=1024M

# scale up deployment
kubectl scale --replicas=1 deployment/op-scim-bridge-redis-master

# scale up deployment
kubectl scale --replicas=1 deployment/op-scim-bridge

Please reach out to our support team if you need help with the configuration or to tweak the values for your deployment.

Advanced deployments

Here are some helpful tips for customizing your 1Password SCIM bridge deployment:

Self-Managed TLS

There are two ways to use a self-managed TLS certificate, which disables Let's Encrypt functionality.

Load Balancer

The first is to terminate TLS traffic on a public-facing load balancer or reverse proxy and redirect HTTP traffic to SCIM bridge within your private network. Skip the step to configure Let's Encrypt, or revert to the default state by setting OP_TLS_DOMAIN to "":

kubectl set env deploy/op-scim-bridge OP_TLS_DOMAIN=""

Modify op-scim-service.yaml to use the alternate http port for the Service as noted within the manifest. Traffic from your TLS endpoint should be directed to this port (80, by default). If SCIM bridge has already been deployed, apply the amended Service manifest:

kubectl apply -f ./op-scim-service.yaml

In this configuration, 1Password SCIM bridge will listen for unencrypted traffic on the http port of the Pod.

Manually-Provided Key/Certificate

Alternatively, you can create a TLS Secret containing your key and certificate files, which can then be used by your SCIM bridge. This will also disable Let's Encrypt functionality.

Assuming these files exist in the working directory, create the Secret and set the OP_TLS_CERT_FILE and OP_TLS_KEY_FILE variables to redeploy SCIM bridge using your certificate:

kubectl create secret tls op-scim-tls --cert=./certificate.pem --key=./key.pem
kubectl set env deploy op-scim-bridge \
  OP_TLS_CERT_FILE="/secrets/tls.crt" \
  OP_TLS_KEY_FILE="/secrets/tls.key"

Note

If your certificate and key files are located elsewhere or have different names, replace ./certificate.pem and ./key.pem with the paths to these files, i.e.:

kubectl create secret tls op-scim-tls --cert=path/to/cert/file --key=path/to/key/file

External Redis

If you prefer to use an existing Redis cache, omit the the redis-*.yaml files when deploying to your Kubernetes cluster. If you have already deployed SCIM bridge, you can delete the objects associated with Redis:

kubectl delete \
  -f redis-config.yaml \
  -f redis-deployment.yaml \
  -f redis-service.yaml

Edit the value of the OP_REDIS_URL environment variable in op-scim-config.yaml, or set it directly if you have already deployed 1Password SCIM bridge:

kubectl set env deploy/op-scim-bridge OP_REDIS_URL="redis[s]://server:port"

Human-Readable Logs

Set OP_PRETTY_LOGS to 1 if you would like the SCIM bridge to output logs in a human-readable format:

kubectl set env deploy/op-scim-bridge OP_PRETTY_LOGS=1

This may be helpful if you aren’t planning on doing custom log ingestion in your environment.

Debug Mode

Set OP_DEBUG to 1 to enable debug output in the logs:

kubectl set env deploy/op-scim-bridge OP_DEBUG=1

This may be useful for troubleshooting, or when contacting 1Password Support.

Trace Mode

Set OP_TRACE to 1 to enable Trace-level debug output in the logs:

kubectl set env deploy/op-scim-bridge OP_TRACE=1

This may be useful for troubleshooting Let’s Encrypt integration issues.

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. Set OP_PING_SERVER to 1 to enable a /ping endpoint on port 80 so that health checks will always be brought online:

kubectl set env deploy/op-scim-bridge OP_PING_SERVER=1

No other endpoints (such as /scim) are exposed through this port.