aws-ecsfargate-terraform

Deploying the 1Password SCIM Bridge on AWS Fargate with Terraform

This guide will run you through a deployment of the 1Password SCIM bridge on AWS Fargate using Terraform.

Note that due to the highly advanced and customizable nature of Amazon Web Services, this is only a suggested starting point. You may modify it to your needs to fit within your existing infrastructure.

Prerequisites

Before beginning, familiarize yourself with PREPARATION.md and complete the necessary steps there.

• Install Terraform
• Have your scimsession file and bearer token (as seen in PREPARATION.md) ready

Sign in with aws

Ensure you are authenticated with the aws tool in your local environment.

See Terraform AWS Authentication for more details.

Configuration

Copy configuration template

Copy terraform.tfvars.template to terraform.tfvars:

cp terraform.tfvars.template terraform.tfvars

Copy scimsession file

Copy the scimsession file in the Terraform code directory:

cp <path>/scimsession ./

This will automatically create an AWS secret containing the contents of the scimsession file in your instance.

Note: If you skip this step or the installation of the scimsession file is not successful, you can create the required AWS secret manually. Ensure you base64 encode the scimsession file, and store it in a secret as plain text (not as JSON, and not wrapped in quotation marks):

# only required if the automatic installation of the 'scimession' file is not successful
cat <path>/scimsession | base64
# copy the output to Secrets Manager

Region

Set the aws_region variable in terraform.tfvars to the AWS region you're deploying in (the default is us-east-1).

Domain name

This example uses AWS Certificate Manager to manage the required TLS certificate. Save the full domain name you want to use as domain_name in terraform.tfvars:

domain_name = "<scim.example.com>"

(Optional) Use an existing ACM wildcard certificate

If you would like to use an existing wildcard certificate in AWS Certificate Manager (*.example.com), uncommment this line in terraform.tfvars:

wildcard_cert = true

(Optional) External DNS

This deployment example uses Route 53 to create the required DNS record. If you are using another DNS provider, uncommment this line in terraform.tfvars:

using_route53 = false

Create a CNAME record pointing to the loadbalancer-dns-name output printed out from terraform apply.

(Optional) Use an existing VPC

This deployment example uses the default VPC for your AWS region. If you would like to specify another VPC to use instead, set the value in the vpc_name in terraform.tfvars:

vpc_name           = "<name_of_VPC>"

(Optional) Specify a name prefix

If you would like to specify a common prefix for naming all supported AWS resources created by Terraform, set the value in the name_prefix variable in terraform.tfvars:

name_prefix        = "<prefix>"

(Optional) Set a log retention period

Thw deployment example retains logs indifnietely by default. If you would like to set a differnet retention period, specify a number of days in the log_retention_days variable in terraform.tfvars:

log_retention_days = <number_of_days>

(Optional) Apply additional tags

If you would apply additional tags to all supported AWS resources created by Terraform, add some to the tags variable in terraform.tfvars:

tags = {
  <key1> = "<some_value>"
  <key2> = "<some_value>"
  …
}

Deploy

Run the following commands to create the necessary configuration settings:

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

You will now be asked to validate your configuration. Once you are sure it is correct, run the following:

terraform apply ./op-scim.plan

After a few minutes and the DNS update has had time to take effect, go to the SCIM Bridge URL you set, and you should be able to enter your bearer token to verify that your SCIM bridge is up and running.

Complete setup

Connect to your Identity Provider following the remainder of our setup guide.

Updating

To update your deployment to the latest version, edit the task-definitions/scim.json file and edit the following line:

    "image": "1password/scim:v2.x.x",

Change v2.x.x to the latest version seen here.

Then, reapply your Terraform settings:

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

December 2021 update changes

As of December 2021, the ALB health check path has changed. If you are updating from a version earlier than 2.3.0, edit your terraform.tf file to use /app instead of / for the health check before reapplying your Terraform settings.

Troubleshooting

Logs

If you want to view the logs for your SCIM bridge within AWS, go to Cloudwatch -> Log Groups and you should see the log group that was printed out at the end of your terraform apply. Look for op_scim_bridge and redis for your logs in this section.

Specific issues

Prompted to Sign In

If you browse to the domain name of your SCIM bridge and are met with a Sign In With 1Password link, this means the scimsession file was not properly installed. Due to the nature of the ECS deployment, this “sign in” option cannot be used to complete the setup of your SCIM bridge.

To fix this, be sure to retry the instructions of Step 2 of Configuration. You will also need to restart your op_scim_bridge task in order for the changes to take effect after you update the scimsession secret.