Identity Provider Installation

# Intro

This page gives you guidance on using the MIRACL Trust SSO Docker image. To get the miracl/sso docker image that is referenced in the following section, please contact MIRACL.

These instructions assume that you already followed the Installation / Quick Start instructions and learned how to successfully configure your SSO with a Service Provider.

# Environment Variables

The following environment variables are available:

MIRACLSSO_CONFIG - sets the configuration to start the service with.

MIRACLSSO_CONFIGPATH - sets the path to the configuration file to start the service with.

MIRACLSSO_LOGLEVEL - sets the Log level to be one of ERROR, WARN, INFO or DEBUG.

MIRACLSSO_DUMP - if set to JSON or YAML, outputs the full configuration, if set to SCHEMA - outputs the JSON schema.

# Docker Quick Guide

What follows is a quick step-by-step guide to getting a test Docker container running, which should give you an understanding of the necessary components and what command line options need to be passed in order to run the MIRACL Trust SSO docker image.

Assuming that you have your config files stored in a local directory such as /home/user/miracl-sso-test/ (as explained in the Installation / Quick Start instructions) you can now run:

docker run \
  --network host \
  --volume /home/user/miracl-sso-test/:/etc/miracl-sso \
  miracl/sso:latest \
  --configPath /etc/miracl-sso/config.yaml

As it is running on the host network (set by the option –network host), the service is accessible at port 8000, unless you have changed the default port in the config. If you want to share only the used port to the SSO docker container instead of the whole host network, you could do it by the option -p 8000:8000:

docker run
  --publish 8000:8000 \
  --volume /home/user/miracl-sso-test/:/etc/miracl-sso \
  miracl/sso:latest \
  --configPath /etc/miracl-sso/config.yaml

If you want to use the environment variables to pass the SSO configuration, there are two options:

  • Use MIRACLSSO_CONFIGPATH to pass the path to the SSO configuration:
export MIRACLSSO_CONFIGPATH=`/home/user/miracl-sso-test/config.yaml`
docker run \
  --network host \
  --env MIRACLSSO_CONFIGPATH \
  miracl/sso:latest
  • Use MIRACLSSO_CONFIG to pass the whole SSO configuration (to run it in CloudRun for example) - export the configuration in the MIRACLSSO_CONFIG and then pass it to the SSO container:
export MIRACLSSO_CONFIG=`cat /home/user/miracl-sso-test/config.yaml`
docker run \
  --network host \
  --volume $(pwd):/sso \
  --env MIRACLSSO_CONFIG \
  miracl/sso:latest

No matter how you run your SSO service, you should be able to access and test your running service at http://127.0.0.1:8000/services.

# Running SSO With External Memory Storage

By default MIRACL Trust SSO service works with internal session storage and doesn’t have any dependencies but if you want to use Redis as an external session storage, you could run it on your host machine by:

sudo apt update && sudo apt install redis-server

sudo service redis-server start

SSO service accesses the Redis server on port 6379 if setup to be used (see session storage) so make sure that this port is shared to the SSO docker container (either by explicit port sharing or the whole host network).

# Running Docker With Consul for Configuration Management

The steps below make use of a local config.yaml file to run a Docker container which references a set of config files stored in Consul. The local config.yaml has only one include which points to the Consul config url, while Consul stores config files just as described in the Overview and Installation / Quick Start instructions.

Run consul in a docker container:

docker run \
  --publish 8300:8300 \
  --publish 8500:8500 \
  gliderlabs/consul-server \
  -bootstrap \
  -advertise=127.0.0.1

Note that you should either share the Consul ports or use the option –net=host that means that it is connected to your host network. It is accessible to the miracl-sso docker container.

Then visit http://127.0.0.1:8500 and set up the necessary config files in key/value, including config.yaml to list the includes, core.yaml to store the server details, client id and secret; plus server certificates. As well as the relevant Service Provider config in the service_providers sub-folder:

consul

Create local file /home/user/miracl-sso-consul/config.yaml that contains the correct consul url as an include:

includes:
  - http://127.0.0.1:8500/v1/kv/config/miracl-sso/config.yaml?raw

Note that ?raw needs to be specified to access the contents of the file stored on consul.

Then run the miracl-sso container, assuming that you have your config file stored in a local directory such as /home/user/miracl-sso-consul/. Use either host network sharing:

docker run \
  --network host \
  --volume /home/user/miracl-sso-consul/config.yaml:/etc/config.yaml \
  miracl/sso:latest \
  --configPath /etc/config.yaml

or specific ports sharing (8000 for the SSO and 8500 for Consul):

docker run \
  --publish 8000:8000 \
  --publish 8500:8500 \
  --volume /home/user/miracl-sso-consul/config.yaml:/etc/config.yaml \
  miracl/sso:latest \
  --configPath /etc/config.yaml