MIRACL SSO Server

With MIRACL Trust SSO (Single Sign-On), companies can give their users the convenience of one log in to multiple apps and websites, a la Google (gmail, drive, youtube, ‘Login with Google’). It makes use of the SAML protocol, which enables the use of an individual user’s logged in session (as carried out by the MIRACL Trust authentication server) to log that same user into other applications.

In SAML terminology, MIRACL Trust SSO is acting as an Identity Provider (IdP) and the other applications (e.g. Dropbox, or Office365) are acting as Service Providers (SPs). When accessing SPs via SSO, the authentication process can either be SP-initiated (in which case the SP may provide a login button which redirects to the IdP for authentication) or IdP-initiated (in which case the user may login using an IdP-provided link which activates the MIRACL Trust pin pad and then redirects to the Service Provider’s logged-in page).

Setting up SSO access to a third party/SP is done by configuring your IdP server and SPs to securely talk to each other. Additional rules to control who is authorized to attempt to login can be set up using email filters, API requests and/or LDAP (i.e. screen users before they even get to the authentication process).

# Configuration of the MIRACL Trust SSO IdP Server

The configuration of the IdP server is managed using config files stored in the /etc/miracl-sso/ directory. The functions served by these files can be split into separate files and then loaded by the main config.yaml file which lists the files to be loaded as ‘includes’. The config.yaml file could include all of the configuration itself in one large file, but it is recommended to split and name the files into a logical structure which enables a more modular management of functionality and Service Providers. Note that MIRACL Trust supports config files in both YAML and JSON format. Throughout the documentation, however, we are using YAML.

You can find a recommended setup for these files already in the /etc/miracl-sso/ directory (note that the example layout and naming of the config files is only for guidance, and you can choose a different structure and naming system):

├── config.yaml
├── core.yaml
├── integrations/
└── service_providers/

This documentation is based on the file structure in /etc/miracl-sso/ folder as every subsequent section describes the configuration files connected with it. In order to run the MIRACL Trust SSO server, it looks for config.yaml file and assembles its configuration from what is listed in it.

The following table lists the most important of these example config files and explains their function. All files are listed and described in their relevant section.

File Function Notes
config.yaml Lists all config files to be included
core.yaml Enter basic SSO IdP server details: server address and port; Client ID and Client Secret from the admin portal, and the private key and public certificate for your IdP server. The config contained in this file is essential for the running of the service
integrations/ldap.yaml Enables use of your own remote LDAP server to control lists of users authorized to attempt login. In each Service Provider’s config file it is compulsory that you choose either LDAP, API or a simple regex of email domains as a means of controlling authorized users. Detailed information could be found in the authorization section This config is not essential for the running of the service
integrations/api.yaml Enables use of API request to control which users are authorized to attempt login. In each Service Provider’s config file it is compulsory that you choose either API, LDAP or a simple regex of email domains as a means of controlling authorized users. All authorized options are explained in the authorization section This config is not essential for the running of the service
integrations/pages_template.yaml For IdP-initiated login, end users must be provided with web pages to interact with your SSO installation. For testing, the default config schema auto-includes some very basic html to display the listed service providers, a logout page, error messages and choose authentication settings if needed. You can override this html directly in the configuration file. Remote pages can also be loaded using the parameters found in /etc/miracl-sso/integrations/pages_url.yaml. Guidance on this can be found in Managing web pages No config changes are needed for testing, but you must have secure web pages configured for a production environment
service_providers/*.yaml The individual files for the Service Providers you wish to allow your users to access (e.g. service_providers/dropbox.yaml) At least one SP must be configured

Advanced IdP server configuration files can also be used to alter log level, change the session management (use REDIS server for example) and specify system stats settings (i.e. reporting on session starts, logins, spikes in statuses, etc.). These are discussed in Advanced config.

# Configuration of the Service Providers

Once the installation and basic config of the IdP has been carried out, in order to implement MIRACL Trust SSO with any one Service Provider it is necessary to:

  1. Create a configuration file for the Service Provider (e.g. /etc/miracl-sso/service_providers/dropbox.yaml).
  2. Login to the admin console of the Service Provider to enter the key details (endpoints, public certificate etc.) of your MIRACL Trust SSO IdP server (you may need to enquire with the Service Provider as to where SSO/SAML settings are found in their admin console).
  3. Download the provided SP metadata from the SP admin console and add it to the relevant config file for your SP.
  4. Restart the IdP service.

The running IdP server then has several endpoints available to interact with and serve its functionality:

  • The /services endpoint leads to a web page which lists all Service Providers the user has access to once authenticated using MIRACL Trust.

  • The /logout endpoint can be used to terminate the current user IdP session and present links to logout from the visited Service Providers.

# How to Use This Documentation

The quick start guide takes you through installing the IdP server, connecting to the authentication platform backend and setting up a single service provider (using Dropbox or AWS as an example). The setup instructions for SPs supported out of the box are found in the Service Provider list.

To learn how to set up any Service Provider that is not included in the list, the Generic Setup Instructions page gives an overview of the information that is generally required by SPs and gives you the information you need to set up an SP which is not supported ‘out of the box’. Typically you need to provide each SP with the IdP public certificate and some further details on IdP endpoints.

Endpoints Reference gives an explanation of all the available IdP endpoints (Note that it is strongly advisable to ensure that the base url "/", "/status" and "/metadata" endpoints are not publicly exposed. It is also important that your network settings allow connection to the https://api.mpin.io/.well-known/openid-configuration endpoint, as this is where the program attempts to get the platform configuration. It also needs outgoing access to https://api.mpin.io/authorize, https://api.mpin.io/oidc/certs and https://api.mpin.io/oidc/token).