SCIM requests must be secured via TLS using an API gateway or load balancer (transport security).
Anonymous access is not supported. A bearer token and session file is required for authentication with the SCIM Bridge and the 1Password service.
The session file is an encrypted file containing privileged 1Password account credentials. This file is created before the bridge application is deployed. The bearer token combined with the encrypted session file represent an authentication mechanism and must be treated extremely seriously in terms of security.

Session file

The session file must be generated prior to deploying and starting the endpoint service. You can generate the session file and bearer token using the create-session-file.sh script on administrator's local machine. This script uses a Docker container to run the op-scim init command and writes the scimsession file back to your local machine using a mounted volume. Your bearer token will be printed to the console. Consider using Secrets Manager to securely store and provision scimsession file during the application deployment.

As an alternative, you can generate the session file and bearer token by running the 1Password SCIM Bridge binary in init mode:

op-scim init

Note: When prompted for user credentials by the init command, use the credentials for the provision manager user and not an Owner or Administrator user.

Init mode will guide the administrator through an interactive process which generates the encrypted session file and bearer token. Although strong encryption is used to secure the session file, prevent unauthorized access to it. Never store the session file in the same place as the bearer token. The bearer token will be required to configure the identity provider (Azure, Okta, etc) to authenticate your connection.

OP-SCIM Bridge

The 1Password SCIM Bridge is distributed as the Debian package and can be installed during the deployment process using the following repo configuration: deb https://apt.agilebits.com/op-scim/ stable op-scim. Repo GPG key can be downloaded from the same repo.
Package upgrade script is included in the instance User Data and instance cron job runs that script hourly to automatically install newer version when it is available. Automatic updates can be disabled by removing the cron job:

sudo rm /etc/cron.d/50_op-scim

You can update to the later version of 1Password SCIM Bridge manually by running the following commands:

sudo apt-get update
sudo apt-get install op-scim

The bridge exposes a service listening on TCP port 3002. The bridge must be deployed and protected by an API gateway, proxy, or load balancer supporting TLS. The bridge service runs using unprivileged user/group credentials, and administrators should use a separate user/group for the bridge service. The bridge writes logs to STDOUT allowing collection with a syslog facility. A systemd unit is included in the package and used to manage service operation, service default environment variables can be altered in /etc/default/op-scim. The scimsession file and a running instance of Redis are required to start the service. By default, 'localhost' Redis server is configured. 1Password SCIM Bridge service start command example:

op-scim --redis-host={cache address} --redis-port={redis port} --session={/path/to/scimsession}

Note: If the --redis-host and/or --redis-port command flags are not passed, the bridge will default to the hostname redis, and the port number 6379, respectively.

Logs

Endpoint writes to STDOUT, thus logs can be processed in a preferred way, for example, send to a remote log collector using rsyslog. A systemd unit file configuration can be used to set a specific SyslogIdentifier in order to filter service logs.

DNS

It is recommended to deploy DNS across the infrastructure to reference cache cluster/nodes and bridge endpoint by FQDN.

TLS

TLS is not implemented on the bridge application, it is highly recommended that a load balancer or API gateway/proxy be configured to terminate TLS for the bridge endpoint. In the case of AWS, Application (ALB) or Classic (ELB) Load Balancer can terminate TLS and protect the bridge endpoint.

Additional Considerations

For most installations, one t2.micro size instance will be adequate to serve IdP requests. Ensure instance performance is monitored, and upgrade instance size if required.
Protect instance with a security group and restrict remote access, add IAM policies and roles.
Load balancer or API gateway/proxy requires a valid SSL/TLS certificate and which includes the bridge endpoint domain name.
Auto-Scaling Groups can be added to the infrastructure to provide an additional level of service availability. We recommend deploying only one instance of the SCIM bridge concurrently for various reasons. If more instances are deployed, it is important that each instance is started using the same session file (or a session file generated from the same 1Password account), as new user accounts require encryption keys from the provision manager account to be confirmed.

Deployment overview

Requirements

OP-SCIM Endpoint software, for example built into AMI or fetched from the external source during the deployment.
Linux AMI including additional software: aws cli, redis-server, apt-transport-https.
scim session file
Optional, AWS KMS and Secrets Manager
Optional, AWS S3 bucket for the terraform remote state.
Optional, AWS S3 bucket for Load Balancer logs.

Steps

OP-SCIM session file and application binary/package are created outside of the infrastructure deployment and have to be available at the time of the deployment.
S3 buckets (Optional) are deployed separately prior to the rest of the infrastructure. These buckets can be used to store terraform state file, Load balancer logs and etc.
KMS Key and Secrets Manager (Optional). KMS Key is used to encrypt/decrypt Secrets Manager data, for example, session file and must be configured prior to deploying OP-SCIM infrastructure. SCIM bridge has to know where to find the session file. Instance userdata can be utilized to configure the environment variables and securely fetch the session file. AWS KMS and AWS Secrets Manager configuration is beyond of the scope of this guide. Please make sure that deployed instances have required access level to KMS keys (if used) and Secrets Manager.
Infrastructure deployment steps.

4.1. Upload Encrypted session file to the Secrets Manager.
Example:

aws secretsmanager create-secret --name op-scim/scimsession --secret-binary file:///path/to/scimsession --region <aws_region>
aws secretsmanager describe-secret --secret-id op-scim/scimsession --region <aws_region>

Specific KMS key can be utilized --kms-key-id <kms_key_arn>, in this case make sure deployed instances have access to that key, otherwise skip this option. If you don't specify key, then Secrets Manager defaults to using the AWS account's default CMK (the one named aws/secretsmanager)

4.2. Configure Cache cluster, can be separate or deployed within the same instances. 4.3. Configure variables. 4.4. Deploy application using terraform init/plan/apply.

NOTE: Application can be redeployed at any time with minimal or no downtime. For example, new AMI is available or session file is updated.

Application logs are available with the service start up (step 4.4.). All logs go to syslog.

Terraform Code Structure

deploy - directory contains deployments/environments and separates them from each other. Example: development,staging, testing and so on.
- variables.tf - sets global variables for the specific deployment and provider configuration. This file already has default values for some of the variables, but it is recommended to review all of them.
- providers.tf - aws and terraform provider configuration.
- main.tf - invokes required modules and sets module specific variables.
- output.tf - prints out some of the resources and values.
- module_scim_app/data/user_data/03-default-users.yml - user configuration, ssh username and key.
new environment - can be created by copying an existing one to a new directory and adjusting variables.tf, main.tf, providers.tf as required.
module_scim_app - deploys the following AWS resources and their dependencies: ASG, ALB, app instances (ASG), instance IAM, instance and LB security groups, public DNS record. ASG monitors instances and automatically adjusts capacity to maintain steady, predictable performance. Capacity is configured in main.tf and instance specific configuration is in variables.tf.
module_scim_infra - deploys underlaying network infrastructure: VPC, subnets, Route Tables, route53, IGW, NGW and their dependencies.

Deploying using Terraform (ver. 0.11.x)

Copy deploy/example_env to a new directory according to the established naming conventions. Example: deploy/development.
Upload Encrypted session file to the AWS Secrets Manager (If required).
Example:

aws secretsmanager create-secret --name op-scim-dev/scimsession --secret-binary file:///path/to/scimsession --region <aws_region>

Adjust variables.tf, main.tf and providers.tf as required.
Use your favorite terraform commands to deploy, verify, and troubleshoot it.

  terraform init
  terraform plan -out=/tmp/op-scim.plan
  terraform apply /tmp/op-scim.plan

Update/Create OP-SCIM endpoint configuration in Azure AD or Okta (IdP) using ALB URL as the endpoint and generated Bearer Token.

Deprovision (destroying) and Re-deploying

Infrastructure is immutable. Instances do not accumulate changes and can be redeployed or replaced with the new ones.

terraform destroy (if target is not specified) deletes all but op-scim session file in Secrets Manager (deployed separately).