Quick Start

# Introduction

This quick start guide takes you through all the steps necessary to get your SSO server installed, connected to the authentication portal backend and set up with a single service provider. This enables you to then run your SSO server and make a test log in to the configured SP, thus ensuring that you have a good grasp of how to configure the system before going on to add any other service providers, whether they are ones supported ‘out of the box’ by MIRACL Trust SSO, or ones you wish to add from scratch. The list of Service Providers supported out of the box can be found here.

# Installation

MIRACL Trust SSO service requires properly setup configuration either in yaml or/and json format. If you need the sample configuration described here or the SSO container, request MIRACL for it. After the configuration is ready, the installation is just a matter of running the MIRACL SSO docker image the way you prefer considering the configuration is saved at /home/user/miracl-sso-test/config.yaml:

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

More about it could be read in the installation guide.

# Restarting the Service

Every change of the configuration should be followed by a restart of the SSO container (named sso) in order to take effect:

docker restart sso

# Uninstall

The SSO service could be uninstalled by just stopping and removing its docker container:

docker stop sso
docker rm sso

# Core Configuration

Let’s consider that the configuration of your SSO server is driven by files located in the /etc/miracl-sso/ directory (please see the overview for an intro to how these files work):

/etc/miracl-sso/
├── config.yaml
├── core.yaml
└── service_providers
    ├── aws.yaml
    └── dropbox.yaml

Edit /etc/miracl-sso/config.yaml to list the config files that are to be included:

includes:
  - core.yaml

# example service providers
  - service_providers/aws.yaml
  - service_providers/bamboo.yaml

Note that settings in files lower down the list of includes overrides settings in those higher in the list. For example if you include a file which specifies a server port number, this overrides a server port number set in a file higher in the list of includes.

# Remote Configuration With Consul

If you wish to load your configuration files remotely, you can add the url of your config as an include, as per the following consul example:

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

Read more about configuring Consul here.

# Obtain the Client ID and Client Secret

To begin using MIRACL Trust SSO, you must first log into the MIRACL Trust authentication portal at https://trust.miracl.cloud to create a new app:

  1. Click on the ‘Applications’ link in your project and create a new OIDC app. Note that, normally, the entered Redirect URL must be the publicly available url which is serving your installation of the SSO IdP server, and it must use the login endpoint (/auth/oidc/miracl by default - see here for more details). Setting it as e.g. http://127.0.0.1:8000/auth/oidc/miracl enables local testing of your setup.

  2. Note that your Client Secret is only issued to you once so it must be grabbed when first displayed. The Client ID can then be grabbed from the app settings screen. Both of these values are needed, for entering in your configuration below.

Now edit /etc/miracl-sso/core.yaml:

server:
  address: ":8000"
  public_address: "http://127.0.0.1:8000"
authentication:
  oidc:
    miracl:
      client_id: <YOUR_CLIENT_ID>
      client_secret: <YOUR_CLIENT_SECRET>
idp:
  private_key: <YOUR_PRIVATE_KEY>
  public_certificate: <YOUR_PUBLIC_CERTIFICATE>

Leaving the server section enables local testing with http://127.0.0.1:8000

Note that public_address should not end with a "/" i.e. http://yoursso.net is correct but http://yoursso.net/ results in an error.

In the authentication section enter the Client ID and Client Secret for your application generated in the MIRACL Trust Portal.

# Generate Certificates

In the idp section you need to add your private key and public certificate for your SSO IdP server. These can be generated and output in the terminal in single line format 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/CN=example.com \
&& echo -e "\nCONFIG PRIVATE KEY:\n" \
&& echo $(cat idp.key | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo -e "\nCONFIG PUBLIC CERTIFICATE:\n" \
&& echo $(cat idp.crt | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo ""

This script generates 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 appear in the correct order with the private key appearing first).

Remember that you need to restart the IdP server in order the changes to take effect.

# Service Provider Setup

Now that you have done the basic configuration, you are ready to integrate your first service provider. You can go to the Service Provider Setup section to see how you can integrate your first SP or see the existing documentation for services that have already been configured and tested with MIRACL SSO Server.