diff --git a/docker/README.md b/docker/README.md index 6c63c16..881d68f 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,6 +1,6 @@ # Deploying the 1Password SCIM Bridge using Docker -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. +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. ## Preparing @@ -10,7 +10,7 @@ Please ensure you've read through the [PREPARATION.md](/PREPARATION.md) document Using Docker, you have two different deployment options: `docker-compose` and Docker Swarm. -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._ Setting up a Swarm is beyond the scope of this documentation. +Docker Swarm is the recommended option. While setting up Swarm is beyond the scope of this documentation, you can either set one up on your own infrastructure, or on a cloud provider of your choice. While Docker Compose is useful for testing, 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, Kubernetes secrets, or AWS Secrets Manager, all of which are supported and recommended for production use. @@ -26,22 +26,19 @@ For macOS users who use Homebrew, ensure you're using the _cask_ app-based versi ## Setting up Docker - - - ### Docker Swarm -For this, you will need to have joined a Docker Swarm. Please refer to [the official Docker documentation](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/) on how to do that. +For this, you will need to have joined a Docker Swarm with the target deployment node. Please refer to [the official Docker documentation](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/) on how to do that. -Once set up and you've logged into your Swarm with `docker swarm join`, it's recommended to use the provided the bash script [./docker/deploy.sh](deploy.sh) to deploy your SCIM bridge. +Once set up and you've logged into your Swarm with `docker swarm join` or created a new one with `docker swarm init`, it's recommended to use the provided the bash script [./docker/deploy.sh](deploy.sh) to deploy your SCIM Bridge. The script will do the following: -1. Add your `scimsession` to the SCIM bridge container, using a .env file for Docker Compose or a swarm secret for Docker Swarm. -2. 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 [PREPARATION.md](/PREPARATION.md). -3. Deploy a container using `1password/scim`, and a redis container. The redis container is necessary to store LetsEncrypt certificates. +1. Add your `scimsession` file as a Docker Secret within your Swarm. +2. 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 [PREPARATION.md](/PREPARATION.md). +3. 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. If everything seems to have deployed successfully, press Ctrl+C to exit, 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. At this point you should set the DNS record for the domain name you prepared to the IP address of the `op-scim` container. You can also continue setting up your Identity Provider at this point. @@ -54,9 +51,71 @@ Once set up, ensure your environment is set up with `eval %{docker-machine env $ Run the [./docker/deploy.sh](deploy.sh) script as in the previous example. -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` +### Manual Instructions + +#### Creating the env file + +The `scim.env` file contains two environment variables: + +* `OP_SESSION` (mandatory for Docker Compose) - a `base64` encoded string of your `scimsession` file +* (OPTIONAL) `OP_LETSENCRYPT_DOMAIN` (for Docker Compose and Docker Swarm) - if set, it initiates a LetsEncrypt challenge to have your SCIM Bridge issued a valid SSL certificate, provided the DNS record is set to its IP + +To take advantage of the complimentary LetsEncrypt SSL certificate service, set the variable in the `scim.env` file: +```bash +# change ‘op-scim.example.com’ to match the domain name you’ve set aside for your SCIM Bridge +echo “OP_LETSENCRYPT_DOMAIN=op-scim.example.com” > scim.env +``` + +Alternatively, setting this variable to blank (i.e: `OP_LETSENCRYPT_DOMAIN=`) will cause the SCIM Bridge to start on port 3002. This is useful if you have a custom load balancer you want to use to terminate SSL connections rather than using LetsEncrypt. Otherwise, you should be sure to set it. This is an “advanced” option so please only try this if you are familiar with setting up your own load balancer: + +```bash +# ADVANCED: if you have your own load balancer +echo “OP_LETSENCRYPT_DOMAIN=” > scim.env +``` + +When using Docker Compose, you can create the environment variable `OP_SESSION` manually by doing the following: + +```bash +# only needed for Docker Compose - use Docker Secrets when using Swarm +SESSION=$(cat /path/to/scimsession | base64 | tr -d "\n") +echo "OP_SESSION=$SESSION" >> scim.env +``` + +On Windows, you can refer to the [./docker/compose/generate-env.bat](generate-env.bat) file on how to generate the `base64` string for `OP_SESSION`. + +Check that the `scim.env` file only has two entries (in total) - `OP_LETSENCRYPT_DOMAIN` and/or `OP_SESSION`. + +#### Docker Compose + +To use Docker Compose to deploy: + +```bash +# enter the compose directory +cd compose/ +# copy the scim.env file +cp ../scim.env ./ +# create the container +docker-compose -f docker-compose.yml up --build -d +# (optional) view the container logs +docker-compose -f docker-compose.yml logs -f +``` + +#### Docker Swarm + +To use Docker Swarm to deploy, you’ll want to have run `docker swarm init` or `docker swarm join` on the target node and completed that portion of the setup. Refer to Docker’s documentation for more details. + +Once that’s set up, you can do the following: + +```bash +# enter the swarm directory +cd swarm/ +# sets up a Docker Secret on your Swarm +cat /path/to/scimsession | docker secret create scimsession - +# copy the scim.env file +cp ../scim.env ./ +# deploy your Stack +docker stack deploy -c docker-compose.yml op-scim +# (optional) view the service logs +docker service logs --raw -f op-scim_scim +``` diff --git a/docker/compose/docker-compose.yml b/docker/compose/docker-compose.yml index de68100..7c8f127 100644 --- a/docker/compose/docker-compose.yml +++ b/docker/compose/docker-compose.yml @@ -1,14 +1,22 @@ version: '2.2' - services: - scim: - image: 1password/scim:v1.6.0 - ports: - - "80:8080" - - "443:8443" - links: - - redis - entrypoint: ["/op-scim/op-scim", "--letsencrypt-domain={YOUR-DOMAIN-HERE}"] - env_file: scim.env - redis: - image: redis:latest + scim: + image: 1password/scim:v1.6.0 + ports: + - "80:8080" + - "443:8443" + networks: + - op-scim + entrypoint: ["/op-scim/op-scim"] + env_file: scim.env + restart: always + redis: + image: redis:latest + expose: + - "6379" + networks: + - op-scim + restart: always + +networks: + op-scim: diff --git a/docker/compose/op-scim.service b/docker/compose/op-scim.service deleted file mode 100644 index dc0d3ec..0000000 --- a/docker/compose/op-scim.service +++ /dev/null @@ -1,17 +0,0 @@ -#/etc/systemd/system/op-scim.service -[Unit] -Description=1Password SCIM bridge -Requires=docker.service -After=docker.service - -[Service] -Type=simple -RemainAfterExit=yes -WorkingDirectory=/path/to/directory/containing/docker-compose.yml -ExecStart=/usr/local/bin/docker-compose up -d -ExecStop=/usr/local/bin/docker-compose down -TimeoutStartSec=0 - -[Install] -WantedBy=multi-user.target - diff --git a/docker/deploy.sh b/docker/deploy.sh index 736822d..486a131 100755 --- a/docker/deploy.sh +++ b/docker/deploy.sh @@ -14,7 +14,7 @@ run_docker_compose() { # this command populates an .env file which allows the container to have a needed environment variable without needing to store the scimsession file itself SESSION=$(cat $scimsession_file | base64 | tr -d "\n") - echo "OP_SESSION=$SESSION" > $docker_path/$docker_type/scim.env + echo "OP_SESSION=$SESSION" >> $docker_path/$docker_type/scim.env if ! docker-compose -f $docker_file up --build -d then @@ -123,7 +123,7 @@ while ! [[ "$proceed" =~ ^([yY][eE][sS]|[yY])$ ]]; do if [[ "$proceed" =~ ^([nN][oO][nN])$ ]] then echo "Exiting..." - exit 0 + exit 0 fi done @@ -132,7 +132,7 @@ docker_file_path=$docker_path/$docker_type docker_file=$docker_file_path/docker-compose.yml docker_backup_file=$docker_file_path/docker-compose.yml.bak cp $docker_file $docker_backup_file -sed s/{YOUR-DOMAIN-HERE}/$domain_name/g $docker_backup_file > $docker_file +echo "OP_LETSENCRYPT_DOMAIN=$domain_name" > $docker_path/$docker_type/scim.env # run the function associated with the Docker type selected if [[ "$docker_type" == "compose" ]] diff --git a/docker/swarm/docker-compose.yml b/docker/swarm/docker-compose.yml index fea74f9..51b60d2 100644 --- a/docker/swarm/docker-compose.yml +++ b/docker/swarm/docker-compose.yml @@ -1,29 +1,33 @@ version: '3.3' - services: - scim: - image: 1password/scim:v1.6.0 - deploy: - replicas: 1 - restart_policy: - condition: on-failure - networks: - - op-scim - ports: - - "80:8080" - - "443:8443" - secrets: - - scimsession - entrypoint: ["/op-scim/op-scim", "--session=/run/secrets/scimsession", "--letsencrypt-domain={YOUR-DOMAIN-HERE}"] - redis: - image: redis:latest - deploy: - replicas: 1 - restart_policy: - condition: on-failure - networks: - - op-scim - + scim: + image: 1password/scim:v1.6.0 + deploy: + replicas: 1 + restart_policy: + condition: on-failure + networks: + - op-scim + ports: + - "80:8080" + - "443:8443" + secrets: + - source: scimsession + target: scimsession + uid: "999" + gid: "999" + mode: 0440 + entrypoint: ["/op-scim/op-scim", "--session=/run/secrets/scimsession"] + env_file: scim.env + redis: + image: redis:latest + deploy: + replicas: 1 + restart_policy: + condition: on-failure + networks: + - op-scim + networks: op-scim: