SSO SAML Overview

With MIRACL Trust® SSO SAML (Single Sign-On), companies can give their users the convenience of one login to multiple apps and websites, a la Google (gmail, drive, youtube, 'Login with Google'). It makes use of the SAML protocol.

The SAML protocol enables organisations to use a 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 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 authorization rules can be set up in the IdP using email filters and/or LDAP.

In order to implement MIRACL Trust® SSO with any one Service Provider it is necessary to:

  1. As the Identity Provider make the necessary configurations in your config.json file
  2. Login to the admin console of the Service Provider to configure the IdP metadata including the public certificate
  3. Download the provided SP metadata and add to your config.json file

Once installed, the IdP service works by referencing a single config.json configuration file, either locally or remotely. This file contains all the necessary IdP settings, and a section for each Service Provider.

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

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

  • 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

Quick Start will take you through the process of setting up the connection to the ZFA authentication backend, installing the IdP server and quickly running a test setup with one Service Provider. This will enable you to make sure you are confident with having your basic settings correct, before progressing to more detailed configuration of the product.

Configuration then takes you through the different sections of the config file in detail.

Service Provider setup then gives instructions on how to set up Service Providers to work with the IdP, both in the config file and in the SP admin area. Before the specific SP instructions, there is a Generic Setup Instructions page which gives an overview of the information that is generally required by SPs and will give 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. The setup instructions for SPs supported out of the box are found in the Service Provider list.

Endpoints Reference gives an explanation of all the available IdP endpoints (Note that it is strongly advisable to ensure that the base url "/", "/status", "/splist" 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.authorize/, https://api.mpin.io/oidc/certs and https://api.mpin.io/oidc/token)

Top