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. 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. This can have 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.

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
    issuer: box.net
    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 also 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 will 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:

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

The above example would convert '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:

Attribute Notes
Assertion XML block containing the Assertion
AttributeStatement XML block containing the AttributeStatement
AuthnRequestID ID of the Authentication Request. An example of this being used can be seen in the assertion for Zabbix
Certificate IDP Public Certificate
Destination Assertion Consumer Service (ACS) Endpoint Location
ID Random ID. An example of this being used can be seen in the assertion for Zabbix
MetadataEntityID IDP Metadata EntityID
NameID XML block containing the NameID. An example of this being used can be seen in the assertion for Zabbix
RecipientIP Recipient IP address
Recipient Assertion Consumer Service (ACS) Endpoint. An example of this being used can be seen in the assertion for Zabbix
ReferenceURI Reference URI (Random ID)
RemoteAddress Remote address. An example of this being used can be seen in the assertion for Zabbix
SessionCreateTime Session creation time in RFC3339 format. An example of this being used can be seen in the assertion for Zabbix
SessionExpireTime Session expiration time in RFC3339 format
SessionID Session ID
SessionIndex Session Index. An example of this being used can be seen in the assertion for Zabbix
SessionUserEmail Session user email. Examples of this being used can be seen with:
- The primary_email attribute in Box
- The eduPersonPrincipalName attribute in Datadog
- The mail attribute in Open Telekom Cloud
- The IDPEmail attribute in Samanage
SessionUserName Session user name (currently is the same as the user email)
ServiceProviderUserID Session user email transformed with “user_id_transform” rules
SignatureBlock XML block containing the Signature. An example of this being used can be seen in the assertion for Zabbix
SPEntityID Service Provider EntityID. An example of this being used can be seen in the assertion for Zabbix
TimeExpire Expiration time in RFC3339 format. An example of this being used can be seen in the assertion for Zabbix
TimeNow Current time in RFC3339 format. An example of this being used can be seen in the assertion for Zabbix
StatusCodeTL Top-level status code
StatusCodeSL Second-level status code
StatusMessage Status message
Attributes Retrieved LDAP attributes