Generic Setup Instructions

In SAML terminology, MIRACL Trust SSO is acting as an Identity Provider (IdP) and the third-party applications being logged into 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).

Configuring SSO to work with Service Providers

Adding an SP to your list involves two steps, which will mean that your IdP and the SP are now talking to each other and users who are registered with your service will be able to access the SP as long as they have a corresponding account with the third party (with, e.g., matching email).

These steps are:

1. Setting up the Service Provider

You will need to login to your account with the SP and follow their specific instructions for enabling SSO/SAML (please see specific instructions for SPs supported 'out of the box' in the left-hand menu).

This will include uploading the public certificate for your SSO server. An SP will normally ask for this as an xml file which also contains information on the urls/endpoints of the configured IdP service. The IdP metadata xml file is accessible at the /metadata endpoint on your server. Some providers may ask for the certificate in a different format. The file format can be converted using openssl. Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file will need to be edited to an appropriate date (it defaults to 48hrs from the current date).

If an SP asks for the Sign in URL or the SSO endpoint. This is simply the /sso endpoint on your server. This may also be referred to as the IdP POST Binding url.

You may also be asked for the IDP Issuer or the SSO Server Entity ID. This is the SSO server url which points to the xml metadata, which is just the /metadata endpoint.

If a service provider asks for a binding method for Single Sign-On and Logout, it should be set as http-redirect.

Some service providers, such as Salesforce, may require some further setup steps, such as creating a self-signed certificate to deploy your domain (which can be done within their admin interface). They will also provide their own metadata certificate which will then need to be pasted into your config file.

Some SPs may ask for a fingerprint of your certificate. With your IdP certificate, this can be generated in the terminal with an openssl command such as: openssl x509 -in idp.crt -sha1 -noout -fingerprint

2. Activating the SP profile in the configuration file

In your config.json file, you will need to activate a profile for that specific SP. This is primarily managed in two sections:

  1. The profile section. Some SPs will require SAML assertions and attributes to be sent in a specific format. For SPs supported 'out of the box', this extra config has already been done.

  2. The sp section. Here it is necessary to add the SP issuer url, logout url and metadata. All of which can be retrieved from the SP using their admin system.

Note that the config.json file only accepts values in a single line . An xml metadata file which has been downloaded from a Service Provider can be output in the terminal in single line format - and with " characters escaped - with a command such as echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n" This can then be copied and pasted into the config file.

Please see the individual SP sections in the left-hand menu for specific instructions for the SPs supported 'out of the box'. Please also see the 'Configuration' menu section for a more detailed breakdown of the config file.