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.
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
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
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
/etc/miracl-sso/config.yaml to list the config files that are to be
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
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/miraclenables local testing of your setup.
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.
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
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.