From 4e0e0eacf39d54c80fc767aa8d62fea46bb8ac5b Mon Sep 17 00:00:00 2001 From: nkechi Date: Sun, 27 Jan 2019 13:23:10 -0500 Subject: [PATCH] documentation review --- build.sh | 42 ++++++++++++++++++++++++++-------------- docker-compose/README.md | 29 ++++++++++++++------------- docker-swarm/README.md | 26 +++++++++++++++---------- 3 files changed, 58 insertions(+), 39 deletions(-) diff --git a/build.sh b/build.sh index b177dcc..31ba6f2 100755 --- a/build.sh +++ b/build.sh @@ -2,27 +2,41 @@ set -e +run_docker_compose() { + cp ./scimsession ./docker-compose/scimsession + rm ./scimsession + cd docker-compose + ./generate-env.sh + + read -p 'Please enter your domain name : ' domain_name + + sed -i '' s/{YOUR-DOMAIN-HERE}/$domain_name/g docker-compose.yml + + docker-compose up --build +} + +run_docker_swarm(){ + cp ./scimsession ./docker-swarm/scimsession + rm ./scimsession + cd docker-swarm + ./generate-secret.sh + + read -p 'Please enter your domain name : ' domain_name + + sed -i '' s/{YOUR-DOMAIN-HERE}/$domain_name/g docker-compose.yml + + docker stack deploy -c docker-compose.yml op-scim +} + read -p 'Please enter the configuration you are using [docker-compose] or [docker-swarm] : ' docker_path if [ "$docker_path" == "docker-compose" ]; then - cp ./scimsession ./docker-compose/scimsession - rm ./scimsession - cd docker-compose - ./generate-env.sh + run_docker_compose elif [ "$docker_path" == "docker-swarm" ] then - cp ./scimsession ./docker-swarm/scimsession - rm ./scimsession - cd docker-swarm - ./generate-secret.sh + run_docker_swarm else echo "Invalid docker manager. Please use docker-compose or docker-swarm" exit fi - -read -p 'Please enter your domain name : ' domain_name - -sed -i '' s/{YOUR-DOMAIN-HERE}/$domain_name/g docker-compose.yml - -docker-compose up --build diff --git a/docker-compose/README.md b/docker-compose/README.md index c36b749..a74b771 100644 --- a/docker-compose/README.md +++ b/docker-compose/README.md @@ -1,18 +1,20 @@ # Deploying the 1Password SCIM Bridge using Docker Compose -This example describes the simplest method of deploying the 1Password SCIM bridge, using Docker Compose. These instructions require a remote Docker host be set up and configured to be accessed by the Docker CLI. +This example describes the simplest method of deploying the 1Password SCIM bridge, using Docker Compose. These instructions require a remote Docker host be set up and configured to be accessed by the Docker CLI. _Please refer to your cloud storage provider on how to setup a remote Docker host if you do not have one set up already._ -Note that this deployment strategy is very useful for testing, but it is not reccomended for use in a production environment. The scimsession file is passed into the container via an environment variable, which is less secure than Docker Swarm secrets or Kubernetes secrets, both of which are supported, and reccomended. +Note that this deployment 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. ## Create your DNS record -The 1Password SCIM bridge requires SSL/TLS in order to communicate with your IdP. 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 record must exist and the SCIM bridge server must be running in order for LetsEncrypt to issue a certificate. +The 1Password SCIM bridge requires SSL/TLS in order to communicate with your IdP. 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 record must exist and the SCIM bridge server must be running in order for LetsEncrypt to issue a certificate. _Please refer to your cloud storage provider on how to setup a DNS record if you do not have one set up already._ -## Create your scimsession file +## Create your scimsession file and Deploy SCIM bridge -Use the Linux Bash [scim-setup.sh](../session/scim-setup.sh) script or Windows PowerShell [create-session-file.bat](../session/create-session-file.bat) batch file while connected to the Docker host on your local machine to set up your account and generate a `scimsession` file. This script uses a Docker container to run the `op-scim setup` command and writes the scimsession file back to your local machine using a mounted volume. Your bearer token will be printed to the console. Save your bearer token, as it will be needed to authenticate with your IdP. +1. Connect to your remote Docker host from your local machine -The scimsession file is equivalent to your Master Password and Secret Key when combined with the bearer token, therefore they should never be stored in the same place. +1. Use the Linux Bash [scim-setup.sh](../session/scim-setup.sh) script to authenticate your account and generate a `scimsession` file : This script uses a Docker container to run the `op-scim setup` command and writes the scimsession file back to your local machine using a mounted volume. Your bearer token will be printed to the console. Save your bearer token, as it will be needed to authenticate with your IdP. + +_The scimsession file is equivalent to your Master Password and Secret Key when combined with the bearer token, therefore they should never be stored in the same place._ Example: ``` @@ -21,17 +23,15 @@ scim-setup.sh Bearer token: jafewnqrrupcnoiqj0829fe209fnsoudbf02efsdo ``` -## Deploy the SCIM bridge +1. Once your scimsession file has been created, use the Linux Bash `build.sh` script to deploy the SCIM bridge. Have the domain name indicated by the DNS record created for the SCIM bridge ready. This script will do the following : -Once your scimsession file has been created, copy it into this directory (next to docker-compose.yml), as we need to populate some ENV variables in the container. Linux Bash `generate-env.sh` script or Windows PowerShell `generate-env.bat` batch file will create a `scim.env` file, allowing docker-compose to pass the scimsession file into the container without writing it to the container filesystem, leading to insecure storage of the file. The scimsession is base64 encoded before being put into the .env file. + 1. For `docker-compose`, it generate a `scim.env` file that allows the scimsession file to be passed into the container without insecurely writing it to the container filesystem. For `docker-swarm`, it will create a secret called `scimsession`, which the op-scim container will then read from `/run/secrets`, as defined in docker-compose.yml. -Next, edit `docker-compose.yml`, replacing `{YOUR-DOMAIN-HERE}` with the domain name indicated by the DNS record created for your SCIM bridge. This will configure LetsEncrypt to automatically issue a certificate for your bridge. + 1. The domain name entered will configure LetsEncrypt to automatically issue a certificate for your bridge. -Running `docker-compose up --build` will now create a container from the `1password/scim` image. A redis container will also be started automatically to be used by the SCIM bridge. _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. + 1. Lastly, it will create a container from the `1password/scim` image. A redis container will also be started automatically to be used by the SCIM bridge. -Once you have tested the configuration, the bridge can be exited using ctrl/cmd-c, and restarted in daemon mode using `docker-compose up -d, or deployed for production use with Docker Swarm or Kubernetes. You can access logs using `docker-compose logs` at any point in the future. - -## Automatically starting the SCIM bridge upon startup +_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. In order to automatically launch the 1Password SCIM bridge upon startup when using docker-compose you'll need to automatically start the Docker daemon, then start op-scim. @@ -39,5 +39,4 @@ In order to automatically launch the 1Password SCIM bridge upon startup when usi 1. Install the service file for op-scim. A [sample](op-scim.service) is provided and you'll need to change the path. 2. Reload systemd: `systemctl daemon-reload` -3. Enable the op-scim service: `systemctl enable op-scim` - +3. Enable the op-scim service: `systemctl enable op-scim` \ No newline at end of file diff --git a/docker-swarm/README.md b/docker-swarm/README.md index 51ea996..5b3018f 100644 --- a/docker-swarm/README.md +++ b/docker-swarm/README.md @@ -1,16 +1,20 @@ -# Deploying the 1Password SCIM Bridge using Docker Swarm +# Deploying the 1Password SCIM Bridge using Docker Compose -This example describes deploying the 1Password SCIM bridge using Docker Swarm. These instructions require a remote Docker Swarm cluster be set up and configured to be accessed by the Docker CLI. +This example describes the simplest method of deploying the 1Password SCIM bridge, using Docker Compose. These instructions require a remote Docker host be set up and configured to be accessed by the Docker CLI. _Please refer to your cloud storage provider on how to setup a remote Docker host if you do not have one set up already._ + +Note that this deployment 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. ## Create your DNS record -The 1Password SCIM bridge requires SSL/TLS in order to communicate with your IdP. You must create a DNS record that points to your Docker cluster. _Do not attempt to perform a provisioning sync before the DNS records have been propogated_. The record must exist and the SCIM bridge server must be running in order for LetsEncrypt to issue a certificate. +The 1Password SCIM bridge requires SSL/TLS in order to communicate with your IdP. 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 record must exist and the SCIM bridge server must be running in order for LetsEncrypt to issue a certificate. _Please refer to your cloud storage provider on how to setup a DNS record if you do not have one set up already._ -## Create your scimsession file +## Create your scimsession file and Deploy SCIM bridge -Use the [scim-setup.sh](https://github.com/1Password/scim-examples/tree/master/scim-setup.sh) script while connected to the Docker host on your local machine to set up your account and generate a `scimsession` file. This script uses a Docker container to run the `op-scim setup` command and writes the scimsession file back to your local machine using a mounted volume. Your bearer token will be printed to the console. Save your bearer token, as it will be needed to authenticate with your IdP. +1. Connect to your remote Docker host from your local machine -The scimsession file is equivalent to your Master Password and Secret Key when combined with the bearer token, therefore they should never be stored in the same place. +1. Use the Linux Bash [scim-setup.sh](../session/scim-setup.sh) script to authenticate your account and generate a `scimsession` file : This script uses a Docker container to run the `op-scim setup` command and writes the scimsession file back to your local machine using a mounted volume. Your bearer token will be printed to the console. Save your bearer token, as it will be needed to authenticate with your IdP. + +_The scimsession file is equivalent to your Master Password and Secret Key when combined with the bearer token, therefore they should never be stored in the same place._ Example: ``` @@ -19,10 +23,12 @@ scim-setup.sh Bearer token: jafewnqrrupcnoiqj0829fe209fnsoudbf02efsdo ``` -## Deploy the SCIM bridge +1. Once your scimsession file has been created, use the Linux Bash `build.sh` script to deploy the SCIM bridge. Have the domain name indicated by the DNS record created for the SCIM bridge ready. This script will do the following : -Once your scimsession file has been created, copy it into this directory (next to docker-compose.yml), as we need to populate a Docker Swarm secret in order to securely deploy your scimsession. `generate-secret.sh` will create a secret called `scimsession`, which the op-scim container will then read from `/run/secrets`, as defined in docker-compose.yml. + 1. For `docker-compose`, it generate a `scim.env` file that allows the scimsession file to be passed into the container without insecurely writing it to the container filesystem. For `docker-swarm`, it will create a secret called `scimsession`, which the op-scim container will then read from `/run/secrets`, as defined in docker-compose.yml. -Next, edit `docker-compose.yml`, replacing `{YOUR-DOMAIN-HERE}` with the domain name indicated by the DNS record created for your SCIM bridge. This will configure LetsEncrypt to automatically issue a certificate for your bridge. + 1. The domain name entered will configure LetsEncrypt to automatically issue a certificate for your bridge. -Running `docker stack deploy -c docker-compose.yml op-scim` will now create a container from the `1password/scim` image. A redis container will also be started automatically to be used by the SCIM bridge. _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 using `docker service logs -f op-scim_scim`. \ No newline at end of file + 1. Lastly, it will create a container from the `1password/scim` image. A redis container will also be started automatically to be used by the SCIM bridge. + +_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. \ No newline at end of file