Table of Contents:

Installation overview

This page takes you through installation of the two essential components for running MIRACL Trust® SSO SAML. These are the IdP server itself (Debian, Ubuntu or Docker) and Redis for user session storage (which can be run locally or remotely).

Other non-essential components are Consul or etcd for remote loading of config (this is mandatory if using Docker); and Graphite ( or another Statsd-compatible component which can optionally be used to display stats on usage metrics. A useful Docker image for Graphite can be found at

The following diagram gives an architectural overview of a typical MIRACL Trust® SSO setup:


Debian installation

If you are running Redis locally, first:

sudo apt-get update && sudo apt-get install redis-server

For ubuntu/debian you can install via the following commands when logged in as root:

wget -qO - | apt-key add --

Create a new file:


Now add the following to miracl.list:

deb all main (Note that, since it comes with i386 additional architecture, Ubuntu 14.04 should use deb [arch=amd64] all main)

Save and close the file, then continue with the commands:
sudo apt-get update
sudo apt-get install miracl-srv-idp

RPM installation

First, the EPEL repositories need to be enabled, so:

sudo yum install epel-release

Redis is a dependency, so first:

sudo yum install redis

You can now install via the following:

Create a new repo file: /etc/yum.repos.d/miracl-rpm.repo

Then add the following:

name= Latest Release for RHEL/Centos 7Server

Save and close the file.

During initial install of any package from this repo, you will be asked to accept the key.

sudo yum update

Finally, install with:

sudo yum install miracl-srv-idp

Docker Installation

When using Docker you can only load your configuration file remotely from consul or etcd. This is done by using remote config provider variables with your docker run command to pull the miraclpublic/miracl-srv-idp:latest image. The following example is for consul:

docker run \
--detach=true \
--net="host" \
--tty=true \
--name=<your_dockersso_image> \
--env="SRV_IDP_REMOTECONFIGENDPOINT=http://<yourconsulip>:<yourconsulport>" \
--env="SRV_IDP_REMOTECONFIGPATH=/config/srv-idp" \
miraclpublic/miracl-srv-idp:latest > <yourdockerdirectory>/

Substitute <your_dockersso_image> with the name you wish to give the container.

SRV_IDP_REMOTECONFIGPROVIDER can be either consul or etcd.
SRV_IDP_REMOTECONFIGPATH is the path where the config.json file will be stored on your consul/etcd server.
SRV_IDP_REMOTECONFIGENDPOINT is the url:port of your consul / etcd instance

When you start your Docker container the config file will then be loaded remotely from consul / etcd.

A working demonstration of a Docker setup, including LDAP, Graphite and Redis can be found at

Add Client ID and Secret to Config

To begin using MIRACL Trust® SSO, you must first log into the MIRACL Trust® authentication portal at, click on the 'Apps' link in the dashboard and create a new SSO with SAML app. Note that, normally, the entered Redirect URL must be the publicly available url which will be serving your installation of the SSO IdP server, and it must use the /login endpoint. For local testing, setting it as e.g. will enable local testing of your setup:



Clicking on 'Show keys' will display the Client ID and Secret values which you will need to enter in the config.json file. These then need to be added to the 'zfa' section of the /etc/srv-idp/config.json file:

  "zfa": {
    "client_id": "",
    "client_secret": "",
    "backend": ""

Generate certificates

Your config file must also contain your private key and public certificate. While you may have your own chosen method, these can be generated by openssl with a command such as:

openssl req -x509 -nodes -newkey rsa:2048 -keyout idp.key -out idp.crt -days 1000 -subj /C=UK/ST=London/L=London/O=Development/ \
&& echo -e "\nCONFIG PRIVATE KEY:\n" \
&& echo $(cat idp.key | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo $(cat idp.crt | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo ""

This script will generate a key and certificate within your current directory (pwd) and display them in the terminal in a format ready to be pasted straight into the config file (they will appear in the correct order with the private key appearing first):

"idp": {
    "private_key": "",
    "public_certificate": "",

Starting/Restarting the service

The service can be run with sudo service srv-idp start

After any changes are made to the config file the service needs to be restarted:

sudo service srv-idp restart


The program can be uninstalled with sudo apt-get --purge remove miracl-srv-idp

Further Configuration

Once installed, further configuration is needed to fully set up your IdP server with a key and certificate, and to set up individual Service Providers for users to log into.

The Quick Start section of this documentation takes you through a quick installation and setup with two common Service Providers (AWS and Dropbox)

The Configuration and Service Provider Setup sections take you through IdP and SP configuration in more detail.