mirror of
https://github.com/PurpleComputing/scim-examples.git
synced 2026-09-17 09:10:39 +01:00
initial commit of improved Docker documentation, move common steps to PREPARING documentation
This commit is contained in:
alicethorne-ab
74
PREPARATION.md
Normal file
74
PREPARATION.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Preparing to deploy your 1Password SCIM Bridge
|
||||
|
||||
This guide will help you prepare to deploy your 1Password SCIM Bridge.
|
||||
|
||||
|
||||
## Clone this repository
|
||||
|
||||
You should clone this repository to ensure you have all the files needed to begin deployment.
|
||||
|
||||
From the command line:
|
||||
|
||||
```
|
||||
git clone https://github.com/1Password/scim-examples.git
|
||||
```
|
||||
|
||||
Alternatively, you can download a .zip of the project by clicking the "Clone or download" button.
|
||||
|
||||
|
||||
## Decide on URL and email address
|
||||
|
||||
There are a few pieces of information you'll want to decide on before beginning the setup process:
|
||||
|
||||
* Your SCIM bridge domain name. (example: `op-scim-bridge.example.com`)
|
||||
* An email to use for the automatically-created Provision Manager user. (example: `op-scim@example.com`)
|
||||
|
||||
|
||||
## Caveats
|
||||
|
||||
There are a few common issues that pop up when deploying the SCIM Bridge.
|
||||
|
||||
* Do not create the Provision Manager user manually. Let the setup process create the Provision Manager user for you **automatically.**
|
||||
* When the Provisioning setup asks you for an email address for the new Provision Manager user it creates for you automatically, use a **dedicated email address** (for example: `op-provision-manager@example.com`) to handle this account. It is _not advised_ to use any personal email address.
|
||||
* You should **never** need to log into this Provision Manager account manually.
|
||||
* Do not attempt to perform a provisioning sync until the setup has been completed.
|
||||
|
||||
|
||||
## Prepare your 1Passsword Account
|
||||
|
||||
Log in to your 1Password account [using this link](https://start.1password.com/settings/provisioning/setup). It will take you to the setup page for the SCIM bridge. Follow the instructions there.
|
||||
|
||||
During this process, the setup will guide you through the following process:
|
||||
|
||||
* Automatically creating a Provision Managers group
|
||||
* Automatically creating a Provision Manager user
|
||||
* Generating your SCIM bridge credentials
|
||||
|
||||
|
||||
### Security (IMPORTANT)
|
||||
|
||||
There are a few specific considerations with respect to security.
|
||||
|
||||
All SCIM requests must be secured via TLS using an API gateway (self-configured web server) or the provided load balancer.
|
||||
|
||||
Anonymous access to 1Password is not supported. You must use the provided secrets to authenticate with the SCIM Bridge and 1Password service.
|
||||
|
||||
You will be provided with two separate secrets:
|
||||
|
||||
* a `scimsession` file
|
||||
* a bearer token
|
||||
|
||||
The `scimsession` file contains the credentials for the new Provision Manager user the setup process automatically created for you. This user will create, confirm, and suspend users, and create and manage access to groups.
|
||||
|
||||
**Do not share these secrets!**
|
||||
|
||||
The bearer token must be provided to your Identity Provider, but beyond that it should be kept safe and **not shared with anyone else.** The `scimsession` file should only be shared with the SCIM bridge itself.
|
||||
|
||||
These secrets can be used to authenticate as the Provision Manager user. While vaults cannot be compromised in this way, it is still a major security concern if they're not kept safe. If, for any reason, you think the secrets may have been leaked, please regenerate them by following the setup guide again through the link above.
|
||||
|
||||
**IMPORTANT:** To reiterate, please keep these secrets in a secure location, and **don't share them** with anyone unless absolutely necessary.
|
||||
|
||||
|
||||
## DNS record
|
||||
|
||||
You will need to be able to create a DNS record with the SCIM bridge domain name decided. However, you'll need to have the IP address of the host, which necessitates deploying the SCIM bridge first, unless you have a static IP already assigned. Follow the steps in each respective deployment guide on when to finish setting up your DNS record.
|
||||
28
README.md
28
README.md
@@ -2,23 +2,33 @@
|
||||
|
||||
Here you can find configuration files and best practice instructions for deploying the 1Password SCIM Bridge on various public and private clouds.
|
||||
|
||||
To streamline your setup, it is suggested to have Docker installed on your local machine.
|
||||
|
||||
|
||||
### Specific Deployment Guides
|
||||
## Automatic Deployment
|
||||
|
||||
The easiest way to deploy the SCIM bridge is with our one-click installation currently available for Google Cloud Platform. If you'd like to deploy to GCP [use this guide instead](https://support.1password.com/cs/scim-deploy-gcp/).
|
||||
|
||||
We also have specific, detailed instructions for deployments to Azure using the [Azure Kubernetes Service](https://support.1password.com/cs/scim-deploy-azure/).
|
||||
|
||||
### General Deployment Guides
|
||||
|
||||
To deploy on Kubernetes, read the [Kubernetes example](https://github.com/1Password/scim-examples/tree/master/kubernetes)
|
||||
## Advanced Deployment
|
||||
|
||||
To deploy with Docker, read the [Docker example](https://github.com/1Password/scim-examples/tree/master/docker)
|
||||
The following guides are for anyone who doesn't want to use the one-click solution available on Google Cloud Platform.
|
||||
|
||||
To deploy with AWS and Terraform, read the [AWS and Terraform example](https://github.com/1Password/scim-examples/tree/master/aws-terraform)
|
||||
|
||||
To request additional deployment examples, please open an issue explaining your deployment environment, and we will do our best to accommodate.
|
||||
### Before Deploying
|
||||
|
||||
If you encounter issues or have any questions about your SCIM bridge deployment, do not hesitate to email support+business@agilebits.com. We are happy to help in any way we can.
|
||||
Before you begin deploying the 1Password SCIM Bridge, please refer to the [Preparation Guide](https://github.com/1Password/scim-examples/tree/master/PREPARATION.md). You will need to make some decisions about certain key details, and it also contains ways to avoid common pitfalls.
|
||||
|
||||
|
||||
## General Deployment Guides
|
||||
|
||||
To deploy on Kubernetes, read the [Kubernetes example documentation](https://github.com/1Password/scim-examples/tree/master/kubernetes)
|
||||
|
||||
To deploy with Docker, read the [Docker example documentation](https://github.com/1Password/scim-examples/tree/master/docker)
|
||||
|
||||
To deploy with AWS and Terraform, read the [AWS and Terraform example documentation](https://github.com/1Password/scim-examples/tree/master/aws-terraform)
|
||||
|
||||
|
||||
## Support
|
||||
|
||||
If you require additional deployment examples, encounter any issues, or have any questions about your SCIM bridge deployment, do not hesitate to email support+business@agilebits.com and open an issue with us. We are happy to help in any way we can.
|
||||
|
||||
@@ -2,68 +2,58 @@
|
||||
|
||||
This example describes the methods of deploying the 1Password SCIM bridge using Docker. The Docker Compose and Docker Swarm managers are available and deployment using each manager is described below.
|
||||
|
||||
## Docker Compose
|
||||
## Preparing
|
||||
|
||||
This is the simplest method of deploying the SCIM bridge. These instructions require a remote Docker host be set up and configured to be accessed by the Docker CLI. _Please refer to your cloud provider on how to setup a remote Docker host if you do not have one set up already or are experiencing difficulties doing so._
|
||||
Please ensure you've read through the [Preparing](https://github.com/1Password/scim-examples/tree/master/PREPARING.md) document before beginning deployment.
|
||||
|
||||
**Note that the Docker Compose strategy is very useful for testing, but it is not recommended for use in a production environment. The scimsession file is passed into the docker container via an environment variable, which is less secure than Docker Swarm secrets or Kubernetes secrets, both of which are supported, and recommended.**
|
||||
|
||||
## Docker Swarm
|
||||
|
||||
These instructions require a remote Docker Swarm cluster be set up and configured to be accessed by the Docker CLI. _Please refer to your cloud provider on how to setup a remote Docker Swarm Cluster if you do not have one set up already or are experiencing difficulties doing so._
|
||||
|
||||
## Clone this repository
|
||||
|
||||
To make this process easier, it is recommended to clone this repository to have easy access to scripts and configuration files.
|
||||
|
||||
## Install Docker locally
|
||||
|
||||
Install [Docker for Desktop](https://www.docker.com/products/docker-desktop) on your local machine and _start Docker_ before continuing, as it will be needed to run the setup process
|
||||
Install [Docker for Desktop](https://www.docker.com/products/docker-desktop) on your local machine and _start Docker_ before continuing, as it will be needed to continue with the deployment process.
|
||||
|
||||
## Create your DNS record
|
||||
For macOS users who use Homebrew, ensure you're using the _cask_ app-based version of Docker, not the default CLI version.
|
||||
|
||||
The 1Password SCIM bridge requires SSL/TLS in order to communicate with your IdP. In order to use TLS, you must create a DNS record that points to your Docker node. _Do not attempt to perform a provisioning sync before the DNS records have been propogated_. The DNS record must exist and the SCIM bridge server must be running if you wish to have LetsEncrypt automatically issue a TLS certificate for your SCIM bridge. _Please refer to your cloud provider on how to setup a DNS record if you do not have one set up already or are experiencing difficulties doing so._
|
||||
|
||||
## Prepare your 1Password Account
|
||||
## Docker Compose vs Docker Swarm
|
||||
|
||||
Log in to your 1Password account [using this link](https://start.1password.com/settings/provisioning/setup). It will take you to the setup page for the SCIM bridge.
|
||||
Using Docker, you have two different deployment options: `docker-compose` and Docker Swarm.
|
||||
|
||||
Follow the on-screen instructions which will guide you through the following steps:
|
||||
Docker Swarm is the recommended option. _Please refer to your cloud provider on how to setup a remote Docker Swarm Cluster if you do not have one set up already or are experiencing difficulties doing so._
|
||||
|
||||
* Create a Provision Managers group
|
||||
* Create and confirm a Provision Manager user
|
||||
* Generate your SCIM bridge credentials
|
||||
|
||||
You can then download the `scimsession` file and save your bearer token. The `scimsession` file contains the credentials for the new Provision Manager user. This user will create, confirm, and suspend users, and create and manage access to groups. You should use an email address that is unique.
|
||||
|
||||
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**.
|
||||
|
||||
You should move your newly created `scimsession` file into the `scim-examples` folder (the root folder of this repository which you cloned earlier).
|
||||
`docker-compose` is very useful for testing, but it is not recommended for use in a production environment. The `scimsession` file is passed into the docker container via an environment variable, which is less secure than Docker Swarm secrets or Kubernetes secrets, both of which are supported, and recommended.
|
||||
|
||||
|
||||
## Deploy SCIM bridge
|
||||
|
||||
1. Connect to your remote Docker host from your local machine
|
||||
- Either connect using [docker-machine](https://docs.docker.com/machine/), OR use SSH to access your remote machine and clone this repo.
|
||||
Connect to your remote Docker host from your local machine using the following:
|
||||
|
||||
2. In your terminal, use the bash script [./docker/deploy.sh](deploy.sh) to deploy your SCIM bridge. If you cloned this repo on your remote machine using SSH, you should copy the `scimsession` file to the `scim-examples` folder on your server. _Have the domain name indicated by the DNS record created for the SCIM bridge ready_. This script will do the following:
|
||||
```
|
||||
eval %{docker-machine env dev}
|
||||
```
|
||||
|
||||
1. Ask if you want to deploy with Docker Swarm or Compose
|
||||
It's recommended to use the provided the bash script [./docker/deploy.sh](deploy.sh) to deploy your SCIM bridge.
|
||||
|
||||
1. Add your `scimsession` to the SCIM bridge container, using a .env file for Docker Compose or a swarm secret for Docker Swarm.
|
||||
If you cloned this repo on your remote machine using SSH, you should copy the `scimsession` file to the `scim-examples` folder on your server.
|
||||
|
||||
1. You will be prompted for your SCIM bridge domain name which will configure LetsEncrypt to automatically issue a certificate for your bridge.
|
||||
The script will do the following:
|
||||
|
||||
1. Lastly, it will deploy a container from the `1password/scim` image. A redis container will also be started automatically to be used by the SCIM bridge.
|
||||
1. Ask if you want to deploy with Docker Swarm or Compose
|
||||
2. Add your `scimsession` to the SCIM bridge container, using a .env file for Docker Compose or a swarm secret for Docker Swarm.
|
||||
3. Prompt you for your SCIM bridge domain name which will configure LetsEncrypt to automatically issue a certificate for your bridge. This is the domain you selected in [Preparing](https://github.com/1Password/scim-examples/tree/master/PREPARING.md).
|
||||
4. Deploy a container using `1password/scim`, and a redis container. The redis container is necessary to store LetsEncrypt certificates.
|
||||
|
||||
The logs from the SCIM bridge and redis containers will be streamed to your machine. When you are done, press ctrl+c to stop the logs, and the containers will remain running on the remote machine.
|
||||
The logs from the SCIM bridge and redis containers will be streamed to your machine. If everything seems to have deployed successfully, press Ctrl+C to exit, and the containers will remain running on the remote machine.
|
||||
|
||||
_After the DNS record has been propogated_, you can continue setting up your IdP with the SCIM bridge Administration Guide while monitoring the logs from the bridge on your local machine.
|
||||
At this point you should set the DNS record for the domain name you selected to the IP address of the op-scim container. You can continue setting up your Identity Provider with the SCIM Bridge Administration Guide.
|
||||
|
||||
### Systemd
|
||||
|
||||
In order to automatically launch the 1Password SCIM bridge upon startup when using **docker-compose**, you will need to configure systemd to automatically start the Docker daemon and launch op-scim.
|
||||
### Additional Docker Compose instructions
|
||||
|
||||
1. Install the service file for op-scim. A [sample](compose/op-scim.service) is provided and you'll need to change the path.
|
||||
2. Reload systemd: `systemctl daemon-reload`
|
||||
This only applies when using and testing the SCIM bridge through `docker-compose`.
|
||||
|
||||
In order to automatically launch the 1Password SCIM bridge upon startup when using `docker-compose`, you will need to configure systemd to automatically start the Docker daemon and launch op-scim.
|
||||
|
||||
1. Install the service file for op-scim. A [sample](compose/op-scim.service) is provided and you'll need to modify it to your needs.
|
||||
2. Once installed, reload systemd so that it recognizes the service: `systemctl daemon-reload`
|
||||
3. Enable the op-scim service: `systemctl enable op-scim`
|
||||
4. Start the op-scim service: `systemctl start op-scim`
|
||||
|
||||
@@ -11,7 +11,7 @@ run_docker_compose() {
|
||||
./generate-env.sh
|
||||
mv ./scimsession ../../
|
||||
|
||||
read -p 'Please enter your domain name : ' domain_name
|
||||
read -p 'Please enter your domain name: ' domain_name
|
||||
|
||||
sed -i.bak s/{YOUR-DOMAIN-HERE}/$domain_name/g docker-compose.yml
|
||||
|
||||
@@ -30,7 +30,7 @@ run_docker_swarm(){
|
||||
|
||||
mv ./scimsession ../../
|
||||
|
||||
read -p 'Please enter your domain name : ' domain_name
|
||||
read -p 'Please enter your domain name: ' domain_name
|
||||
|
||||
sed -i.bak s/{YOUR-DOMAIN-HERE}/$domain_name/g docker-compose.yml
|
||||
|
||||
@@ -40,7 +40,9 @@ run_docker_swarm(){
|
||||
docker service logs --raw -f op-scim_scim
|
||||
}
|
||||
|
||||
read -p 'Please enter the configuration you are using [compose] or [swarm] : ' docker_path
|
||||
echo 'Please ensure you have read the README before continuing.'
|
||||
echo 'Which docker deployment method are you using?'
|
||||
read -p '[compose] or [swarm]: ' docker_path
|
||||
|
||||
if [ "$docker_path" == "compose" ];
|
||||
then
|
||||
@@ -49,6 +51,6 @@ elif [ "$docker_path" == "swarm" ]
|
||||
then
|
||||
run_docker_swarm
|
||||
else
|
||||
echo "Invalid docker manager. Please use docker-compose or docker-swarm"
|
||||
echo "Invalid docker manager. Please use either docker-compose or docker-swarm."
|
||||
exit
|
||||
fi
|
||||
|
||||
@@ -4,49 +4,9 @@ This example explains how to deploy the 1Password SCIM bridge on Kubernetes runn
|
||||
|
||||
If deploying to the Azure Kubernetes Service, you can refer to our [detailed deployment guide instead](https://support.1password.com/cs/scim-deploy-azure/).
|
||||
|
||||
## Before beginning
|
||||
|
||||
There are a few pieces of information you'll want to decide on before beginning the setup process:
|
||||
|
||||
* Your SCIM bridge domain name. (example: `op-scim-bridge.example.com`)
|
||||
* An _accessible_ email to use for the automatically-created Provision Manager user. You'll be required to use a code sent to this email to complete setup of the account. (example: `op-scim@example.com`)
|
||||
|
||||
In addition, there are a few things to keep in mind before you begin deployment.
|
||||
|
||||
* Do not create the Provision Manager user manually. Let the setup process create the Provision Manager user for you **automatically.**
|
||||
* When the Provisioning setup asks you for an email address for the new Provision Manager user it creates for you automatically, use a dedicated email address (for example: `op-provision-manager@example.com`) to handle this account. It is _not advised_ to use any personal email address. At no point should you need to log into this new Provision Manager account manually.
|
||||
* Do not attempt to perform a provisioning sync before the setup has been completed.
|
||||
* **IMPORTANT:** You will be provided with two separate secrets: a `scimsession` file and a Bearer token. **Do not share these secrets!** The bearer token must be provided to your Identity Provider, but beyond that it should be kept safe and **not shared with anyone else.** The `scimsession` file should only be shared with the SCIM bridge itself.
|
||||
|
||||
|
||||
## Start creating your DNS record
|
||||
|
||||
The 1Password SCIM bridge requires SSL/TLS in order to communicate with your Identity Provider. To do that, you must create a DNS record that points to your Kubernetes load balancer.
|
||||
|
||||
This is a chicken and egg problem, as we need the load balancer online with an IP address before we can create the DNS record.
|
||||
|
||||
Please follow all of the steps until the load balancer has been created, and at the very end, you will finish setting up the DNS record with the domain you decided on in [Before beginning](#Before-beginning).
|
||||
|
||||
|
||||
## Prepare your 1Password Account
|
||||
|
||||
Log in to your 1Password account [using this link](https://start.1password.com/settings/provisioning/setup). It will take you to the setup page for the SCIM bridge. Follow the instructions there.
|
||||
|
||||
During this process, the setup will guide you through the following process:
|
||||
|
||||
* Automatically creating a Provision Managers group
|
||||
* Automatically creating a Provision Manager user
|
||||
* Generating your SCIM bridge credentials
|
||||
|
||||
The SCIM bridge credentials are split into two equally-important parts:
|
||||
|
||||
* a `scimsession` file
|
||||
* a bearer token
|
||||
|
||||
The `scimsession` file contains the credentials for the new Provision Manager user the setup process automatically created for you. This user will create, confirm, and suspend users, and create and manage access to groups.
|
||||
|
||||
**IMPORTANT:** As stated before, please keep these secrets in a secure location, and don't share them with anyone unless absolutely necessary.
|
||||
## Preparing
|
||||
|
||||
Please ensure you've read through the [Preparing](https://github.com/1Password/scim-examples/tree/master/PREPARING.md) document before beginning deployment.
|
||||
|
||||
## Create your `scimsession` Kubernetes secret
|
||||
|
||||
@@ -96,13 +56,9 @@ kubectl apply -f op-scim-service.yaml
|
||||
```
|
||||
|
||||
|
||||
## Finish configuring DNS
|
||||
## Configuring DNS
|
||||
|
||||
As mentioned before, you'll need to configure you DNS after the fact, as configuring DNS requires the IP address of the deployed container.
|
||||
|
||||
It's important that you use the IP address of the container that runs the load balancer.
|
||||
|
||||
Within your DNS provider, create the DNS record for the domain you decided on in [Start creating your DNS record](#Start-creating-your-DNS-record). You should give it a few minutes to propagate.
|
||||
At this stage, you can finish configuring your DNS entry as outlined in [Preparing](https://github.com/1Password/scim-examples/tree/master/PREPARING.md). Please ensure you're using the IP address of the op-scim service you've deployed, which should have been automatically assigned.
|
||||
|
||||
|
||||
## Test the instance
|
||||
|
||||
Reference in New Issue
Block a user