Service Provider Setup

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 means that your IdP and the SP are now talking to each other and users who are registered with your service are able to access the SP as long as they have a corresponding account with the third party (with, e.g., matching email).

# 1. Setting Up the Service Provider

You need to log in to your account within the SP admin platform 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 includes uploading the public certificate for your SSO server. An SP normally asks 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 needs 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 also provides their own metadata certificate which then needs 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. Creating a Specific Config File for the SP

In your /etc/miracl-sso/service_providers/ subfolder, you need to create an individual config file for the SP with the following sections:

1. The profile section. This is required from some SPs only if there are specific SAML assertions and attributes that need to be sent in a specific format. For SPs supported ‘out of the box’ which need such one, this extra config has already been done.

2. The sp section which is required for every SP. It is necessary to add the SP name, authorize section, login and logout url and metadata. The last three of them can be retrieved from the SP using their admin system.

# 3. Using Custom Attributes

A simple example which illustrates the above points is Box (which can be found in /etc/miracl-sso/service_providers/box.yaml):

profile:
  attribute:
    box: >-
      <AttributeStatement>
        <Attribute Name="primary_email">
          <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
        </Attribute>
      </AttributeStatement>
sp:
  box:
    description: box
    name: Box
    login_url: https://example.account.box.com/login
    logout_url: https://example.app.box.com/logout
    relay_state: ""
    metadata: >-
      <!-- insert downloaded SP metatadata here -->

    sign_response: false
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      attribute: box

As you can see, Box expects the IdP to pass an attribute of primary_email which is picked up as the {{.SessionUserEmail}} attribute. On the very last line note that, in the profile subsection of the sp section, the box attribute is invoked.

At this point it is useful to note that there are two types of attributes that can be passed:

1. Attributes which are programmatically picked up from the IdP to pass on to the SP. In an attribute statement these are passed as variables within the AttributeValue tags. Examples being <AttributeValue>{{.NameID}}</AttributeValue> or <AttributeValue>{{.MetadataEntityID}}</AttributeValue>. A full table of available attributes is available below, including links to examples of them in use with preconfigured SPs.

2. Attributes which are extracted from an LDAP server before being passed on to the SP. In an attribute statement these are passed as {{AttrVal}} variables within the AttributeValue tags. An example being <AttributeValue>{{AttrVal "uid" 0 "" . Attributes}}</AttributeValue>. An explanation of how this is done can be found in the advanced section of LDAP and authorization.

It is possible to pass hardcoded values as attributes to SPs, if required, as per the following example from Open Telekom Cloud:

<Attribute FriendlyName="groups" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
  <AttributeValue>restricted</AttributeValue>
</Attribute>

It is also important to note that some Service Providers require that the user ID is sent in a particular format. For example, Bamboo does not accept a full email address - only the user name from the first part of the email. This can be dealt with by user_id_transform added to the sp section:

user_id_transform:
- search: ^([^@]+)@[^@]+$
  replace: $1

The above example converts ‘john.smith@example.com’ to just ‘john.smith’.

Looking at other Service Providers shows more examples of custom attributes. The following attributes are available to be passed as SAML attributes/assertions: