PurpleComputing/scim-examples
2
0
Fork 0
mirror of https://github.com/PurpleComputing/scim-examples.git synced 2026-09-17 01:00:41 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

more improvements to documentation

Browse Source
This commit is contained in:
alicethorne-ab
2020-11-03 14:17:23 -05:00
parent 93ce31b829
commit 85a01a4b13
5 changed files with 37 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
PREPARATION.md
View File

@@ -58,7 +58,7 @@ There are a few common issues that pop up when deploying the SCIM Bridge.
* You should only run one instance of the SCIM Bridge online at a time. The SCIM Bridge is not considered a high-availablity service. Running multiple SCIM Bridges is also not supported.
* Do not attempt to perform a provisioning sync until the setup has been completed.
* Once set up, your Identity Provider becomes the _authoritative source_ of information for your 1Password accounts. With Provisioning enabled, the ability to change the _display name_ and _account status_ are not possible through the 1Password Web UI, and must be done through your Identity Provider. You can, however, continue to issue Account Recovery requests through the 1Password Web UI with Provisioning enabled.
* E-mail addresses for provisioned users cannot be changed through the Identity Provider, due to the way their e-mail is used to generate their encryption key. Users must change their e-mail manually through the 1Password Web UI, so that they can have their encryption key and Emergency Kit regenerated.
* With v1.6.0+ of the SCIM Bridge, you can enforce e-mail address changes through your Identity Provider. Users will be required to confirm those e-mail changes the next time they log in, as their e-mail address is used when generating their encryption keys.
For more information on our security model, you can read our [security whitepaper](https://1password.com/files/1Password-White-Paper.pdf).

14
aws-terraform/README.md
View File

@@ -29,7 +29,7 @@ For most installations, one [t3.micro](https://github.com/1Password/scim-example
### AWS Components
* **AWS Elastic Compute Cloud** - Elastic Compute Cloud (EC2) provides the compute necessary to deploy the SCIM Bridge.
* **AWS Key Management Service and Secrets Manager** - Key Management Service (KMS) key is used to encrypt/decrypt Secrets Manager data. `scimsession` file must be placed into the service prior to deploying your 1Password SCIM Bridge while using this service. Additionally, the SCIM Bridge has to know where to find the `scimsession` file, so please refer to the KMS/SM documentation on how to set that up.
* **AWS Key Management Service and Secrets Manager** - Key Management Service (KMS) key is used to encrypt/decrypt Secrets Manager data. You’ll be placing the `scimsession` file (mentioned in [PREPARATION.md](/PREPARATION.md)) in the steps outlined here.
* **AWS S3 Bucket** - This can be used to store the terraform state file, load balancer logs, and so on.
* **AWS Certificate Manager** - Used to manage SSL certificates for your deployment.
@@ -54,11 +54,13 @@ Below is the overall code structure of the Terraform deployment.
## Deploying using Terraform
0. If you don’t have a region set through your `aws` command line tools, you’ll want to have an environment variable to the region your preferred region. This can solve errors such as `The argument "region" is required, but was not set.`
0. Configure AWS tools by running the command `aws configure`. It will step you through providing it with your API tokens. You’ll need to refer to [AWS’s documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) on how to get that set up.
If you don’t have a region set through your `aws` command line tools, you’ll want to have an environment variable to the region your preferred region. This can solve errors such as `The argument "region" is required, but was not set.`
```bash
# change “aws-region-x” to your preferred region, for example: export AWS_DEFAULT_REGION=”us-east-2”
export AWS_DEFAULT_REGION=”aws-region-x”
# change “us-east-1” to your preferred AWS region, i.e: “us-west-1”, “us-central-1”, etc.
export AWS_DEFAULT_REGION=”us-east-1”
```
1. Copy `deploy/example_env` to a new directory depending on the environment you wish to deploy to. (e.g: `testing`, `production`, etc)
@@ -105,6 +107,10 @@ All logs go to `/var/log/syslog` (AWS EC2 instance OS). You can use the AWS Syst
You can destroy and redeploy the instance whenever you feel the need to. No permanent data is stored within the SCIM bridge instance itself, as secrets are stored in the AWS Secrets Manager. This is useful for upgrading your SCIM bridge with important bugfix or feature releases.
```bash
terraform destroy
```
### Debian Package

53
docker/README.md
View File

@@ -28,7 +28,9 @@ For macOS users who use Homebrew, ensure you're using the _cask_ app-based versi
## Setting up Docker
### Docker Swarm
### Automatic Instructions
#### Docker Swarm
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.
@@ -45,7 +47,7 @@ The logs from the SCIM Bridge and redis containers will be streamed to your mach
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.
### Docker Compose
#### Docker Compose
You will need to have a Docker machine set up either locally or remotely. Refer to [the docker-compose documentation](https://docs.docker.com/machine/reference/create/) on how to do that. For a local installation, you can use the `virtualbox` driver.
@@ -71,48 +73,23 @@ cd scim-examples/docker/
```
#### Creating the `scim.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
```
#### Docker Compose
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
sed -i'' -e "s/OP_SESSION=$/OP_SESSION=$SESSION/" scim-examples/docker/compose/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`.
You’ll also need to set the environment variable `OP_LETSENCRYPT_DOMAIN` within `scim.env` to the URL you selected during [PREPARATION.md](/PREPARATION.md). Open that in your preferred text editor and change `OP_LETSENCRYPT_DOMAIN` to that domain name.
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:
And finally, use `docker-compose` to deploy:
```bash
# enter the compose directory
cd scim-examples/docker/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
@@ -124,6 +101,10 @@ docker-compose -f docker-compose.yml logs -f
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.
Unlike Docker Compose, you won’t need to set the `OP_SESSION` variable in `scim.env`, as we’ll be using Docker Secrets to store the `scimsession` file.
You’ll still need to set the environment variable `OP_LETSENCRYPT_DOMAIN` within `scim.env` to the URL you selected during [PREPARATION.md](/PREPARATION.md). Open that in your preferred text editor and change `OP_LETSENCRYPT_DOMAIN` to that domain name.
Once that’s set up, you can do the following:
```bash
@@ -131,8 +112,6 @@ Once that’s set up, you can do the following:
cd scim-examples/docker/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
@@ -155,9 +134,17 @@ docker-compose -f docker-compose.yml up --build -d
This should seamlessly upgrade your SCIM Bridge to the latest version. The process takes about 2-3 minutes for the Bridge to come back online.
NOTE: If you’re upgrading from a previous version of the repository, ensure that you’ve reconfigured your environment variables within `scim.env` before upgrading.
### Advanced `scim.env` file options
These should only be used for advanced setups.
* `OP_PORT` - when `OP_LETSENCRYPT_DOMAIN` is set to blank, you can use `OP_PORT` to change the default port from 3002 to one of your choosing.
* `OP_REDIS_HOST` - you can specify either a hostname or IP address here to point towards an alternative redis host. You can then strip out the sections in `docker-compose.yml` that refer to redis to not deploy that container. Note that redis is still required for the SCIM Bridge to function.
#### Generating `scim.env` file on Windows
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`.

2
docker/swarm/docker-compose.yml
View File

@@ -17,7 +17,7 @@ services:
uid: "999"
gid: "999"
mode: 0440
entrypoint: ["/op-scim/op-scim", "--session=/run/secrets/scimsession"]
entrypoint: ["/op-scim/op-scim"]
env_file: scim.env
redis:
image: redis:latest

7
kubernetes/README.md
View File

@@ -91,11 +91,12 @@ Once the DNS record has propagated, you can test your instance by requesting `ht
You can do this with `curl`, as an example:
```sh
curl --header "Authorization: Bearer <bearertoken>" https://<domain>/scim/Users
curl --header "Authorization: Bearer TOKEN_GOES_HERE" https://<domain>/scim/Users
```
You can now continue with the administration guide to configure your Identity Provider to enable provisioning with your SCIM Bridge.
## Upgrading
It should be relatively simple to upgrade the SCIM Bridge from previous versions.
@@ -113,7 +114,7 @@ This should seamlessly upgrade your SCIM Bridge to the latest version. The proce
**NOTE:** As of October 2020, the `scim-examples` Kubernetes deployment now uses `op-scim-config.yaml` to set the configuration needed for your SCIM Bridge, and has changed the deployment names from `op-scim` to `op-scim-bridge`, and `redis` to `op-scim-redis` for clarity and consistency.
You’ll need to re-configure your options in `op-scim-config.yaml`, particularly `OP_LETSENCRYPT_DOMAIN`. You may also want to delete your previous `op-scim` and `redis` deployments.
You’ll need to re-configure your options in `op-scim-config.yaml`, particularly `OP_LETSENCRYPT_DOMAIN`. You may also want to delete your previous `op-scim` and `redis` deployments to prevent conflict between the two versions.
```bash
kubectl delete deployments.apps op-scim redis
@@ -126,6 +127,8 @@ You’ll then need to update your SCIM Bridge’s domain name DNS record with it
kubectl describe service/op-scim-bridge | grep "LoadBalancer Ingress" | cut -d' ' -f7
```
This is a one-time operation to change the deployment and service names of the SCIM Bridge so they are more easily identifiable to administrators.
## Advanced deployments