SAML Single Sign-On

DataMasque can be configured by an administrator to use SAML single sign-on (SSO), backed by your organisation's federated identity provider (IdP). DataMasque supports On-Premise Active Directory (AD) and Azure Active Directory (AAD) as its SAML identity providers. Additional configuration may be required for other identity providers.

• Overview
• Identity provider configuration
  1. Basic SAML configuration
  2. User attribute mapping
  3. SAML metadata XML
• On-Premise Active Directory with Federation Services
  1. Create Relying Party Trust
  2. Setting up the Claim Issuance Policy
  3. Exporting Federation Metadata
• DataMasque configuration
• User provisioning and management
  • Authorisation
  • User account creation
  • Updating user details
  • Revoking user access
• Troubleshooting
  • Invalid SAML single sign-on configuration
  • Missing identity provider certificate in metadata XML
  • SAML signature validation error
  • SAML response is missing required attributes

Overview

When configured to use SAML single sign-on, DataMasque will provide an option for users to Sign in with SSO on the sign-in page. Clicking this button will initiate the SAML single sign-on process:

1. The user is redirected to the identity provider for authentication.
2. The user authenticates against the identity provider¹.
3. The user is redirected back to DataMasque and signed-in.
4. The user is assigned the Mask Runner role by default. See User Management for more details.

¹If the user already has an authenticated browser session with the identity provider, this step will happen automatically; the user will be signed-in to DataMasque without needing to enter credentials.

Note: The DataMasque admin account is only accessible using local credentials. Single sign-on for this account is disabled to ensure that it will not become inaccessible in case of misconfiguration.

Note: DataMasque does not implement single sign-out. Signing out from DataMasque will not sign the user out from the SSO session with the identity provider.

Identity provider configuration

1. Basic SAML configuration

Create an application (Enterprise Application in AAD) entry for DataMasque in the identity provider. If you plan to deploy multiple instances of DataMasque, you will need one application per-instance. In order to easily identify each instance, it is recommended to include the instance hostname when naming your application.

Once created, configure the SAML single-sign on settings for your application using the following values - replacing <hostname> with the hostname of the DataMasque instance:

Identifier / Entity ID	https://<hostname>
Reply URL	https://<hostname>/api/saml/acs
Sign on URL	https://<hostname>/api/saml/login

Note: To authenticate using SAML SSO, users must access DataMasque in their web browser using the hostname provided to the IdP. If the user attempts single sign-on while accessing DataMasque using a secondary hostname or server IP address, the SSO request will be rejected.

2. User attribute mapping

NameID

DataMasque uses the SAML NameID field to identify the user each time they sign in using SAML SSO. It is required that the SAML NameID is mapped to a unique, persistent identifier for each user account and will remain unchanged for the entire lifespan of that account. The following options are recommended to configure the NameID in your IdP:

SAML attribute / claim	Required source attribute (AAD)	Required NameID format
NameID	user.objectid	Persistent

User attributes

Additional user attributes are used by DataMasque to complete the user account information within DataMasque. These must be configured using the following attribute mapping in your IdP:

SAML attribute / claim	Required source attribute (AAD)	DataMasque attribute mapping
name	user.userprincipalname	The user's username. Must be unique.
emailaddress	user.mail	The user's email address. Must be unique.
givenname	user.givenname	The user's first name.
surname	user.surname	The user's last name.

Note: Each of the specified attributes must use the following namespace:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims

3. Export IdP metadata XML

After completing the basic SAML configuration and user attribute mapping, export this configuration to a SAML metadata XML from your IdP. This file contains the necessary configuration that enables DataMasque to use the IdP for SAML single sign-on.

In Azure Active Directory, this metadata XML file download link can be found under the SAML Signing Certificate panel of the Single sign-on options for your enterprise application. The file download is labelled Federation Metadata XML. Download this file and save it for use during the DataMasque configuration process.

On-Premise Active Directory with Federation Services

Setting up SAML with on-premise Active Directory is done in three steps. First, create a Relying Party Trust to specify DataMasque's URLs. Next, assign a Claim Issuance Policy to the Relying Party Trust, this sets the mapping for data attributes between Active Directory and DataMasque. Finally, export the metadata XML and upload it to DataMasque. These instructions assume you have already set up Federation Services with Active Directory.

1. Create Relying Party Trust

Launch Server Manager and connect to the Active Directory Federation Services (ADFS) server you want to set up. Then, select Tools > AD FS Management.

Select Relying Party Trusts from the left sidebar menu, then click Add Relying Party Trust… from the Actions sidebar on the right. This will open the Add Relying Party Trust Wizard.

The options you will need to use as you go through the process are:

• Select Claims Aware, then click Start.
• Choose to Enter data about the relying party manually, then click Next.
• Enter a Display Name and, optionally, Notes. These will be displayed on the ADFS sign on page. Click Next.
• Click Next without entering certificate details.
• Check Enable support for SAML 2.0 SSO service, then enter the DataMasque reply URL (e.g. https://<hostname>/api/saml/acs). Click Next.
• The Relying party trust identifier is the root URL of your DataMasque install, without a trailing /. For example, if you access DataMasque at https://datamasque.example.com/ the trust identifier is https://datamasque.example.com. After adding this, click Next.
• At the Choose Access Control Policy step, you will need the select the appropriate policy for your use case. Once selected, click Next.
• On the Ready to Add Trust screen you can review the options you've entered. Then when ready to proceed, click Next.
• The relying party trust has been added. Check Configure claims issuance policy for this application to create a claims issuance policy ready to edit, then click Close.

Your relying party trust has been set up but will not map the required attributes for DataMasque. You'll do this in the next step, Setting up the Claim Issuance Policy.

2. Setting up the Claim Issuance Policy

A claim issuance policy defines the mapping between Active Directory attributes and SAML attributes. Follow these steps to set up a claim issuance policy on your relying party trust.

• While still in the AD FS manager, make sure Relying Party Trusts is selected in the left sidebar, then in the main view select the relying party trust you just created.
• Click Edit Claim Issuance Policy… in the right sidebar.
• In the window that opens, click Add Rule… to add a new rule.
• Select Send LDAP Attributes as Claims as the Claim rule template then click Next.
• Set a Claim rule name.
• Select Active Directory as the Attribute Store.
• The following table is a guide for setting up the claims. The Outgoing Claim Types must be set as laid out in the table, however the source attributes (LDAP Attributes) are suggestions only. For example, if your users log on with an email address, then User-Principal-Name could map to E-Mail Address.

LDAP Attribute (Suggested)	Outgoing Claim Type	DataMasque user attribute mapping
User-Principal-Name	Name ID	SSO ID Must be unique and persistent for the user.
User-Principal-Name	Name	Username. Must be unique.
E-Mail Address	E-Mail Address	Email address. Must be unique.
Given-Name	Given-Name	First name.
Surname	Surname	Last name.

• After setting the mappings, click OK, then OK in the next dialogue Edit Claim Issuance Policy for

The configuration in ADFS is now complete. You'll next need to export the federation metadata XML file, for import into DataMasque.

3. Exporting Federation Metadata

The FederationMetadata.xml file can be downloaded from your ADFS server over HTTPS. The address is https://<adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml. For example, on the ADFS server itself, this address would be https://localhost/FederationMetadata/2007-06/FederationMetadata.xml.

Once the metadata XML file has been retrieved, follow the DataMasque configuration instructions to upload it to DataMasque.

DataMasque configuration

Configuring DataMasque to use an identity provider (IdP) which has been configured as per identity provider configuration simply requires the installation of the IdP metadata XML file.

To install the IdP metadata XML in DataMasque, navigate to the application Settings page (only accessible when logged in as the admin user). On the Settings page, you will find the SAML Single Sign-On panel:

Upload the IdP metadata XML file and click SAVE to complete the configuration.

You may also optionally enable the Disable local logins switch, which disables the use of local DataMasque user accounts (except for the admin account).

Note: If the IdP metadata XML is updated or modified, all users who have authenticated using the previous configuration will be signed-out, however their API tokens will remain active. If you are migrating to a new IdP and wish to ensure that all access - including API - is revoked for users provisioned against the old IdP, it is recommended to also disable the user account in DataMasque.

User provisioning and management

Authorisation

When configured with SAML single sign-on, DataMasque relies on successful authentication of the user against the identity provider to determine whether a user is authorised to access DataMasque. To authorise user access to a DataMasque instance, users and/or groups should be assigned to the corresponding application entry on the identity provider.

User account creation

When a user successfully authenticates using SAML SSO for the first time, an SSO DataMasque user account is automatically created for them. The username and email of this account will be populated using the SAML attributes returned by the identity provider. For this reason it is important to ensure the correct attribute mapping when configuring the identity provider.

In the event that a user authenticates with SAML SSO, but an existing local DataMasque account is registered with that user's email address, this existing local account will be converted to an SSO account. When this happens, the user will no longer be able to sign in using their previous local credentials; all future sign-ins must be authenticated through SSO.

Updating user details

User accounts that are authenticated using SSO cannot be updated from DataMasque.

In the event that user account details such as email address are updated on the identity provider, these changes will not currently be synchronised to DataMasque.

Revoking user access

User access for SSO accounts can be revoked by disabling the user account using the Users management page. Disabling a user account will take effect immediately, causing all existing sessions to be logged out.

Additionally, it is recommended to remove the user from the application on the identity provider. This will cause the identity provider to deny the authentication request immediately when the user attempts to sign-in.

Warning: Removing the user from the DataMasque application entry on the identity provider will not terminate any existing sessions the user may have with DataMasque. To ensure that user access is revoked entirely and immediately, the user account must be disabled using the DataMasque Users management page.

Troubleshooting

Invalid SAML single sign-on configuration

When attempting to sign in with SSO, users may receive an error:

Invalid SAML single sign-on configuration. Ensure that a valid IdP metadata XML file has been installed.

This error may occur if an invalid IdP metadata XML file has been uploaded to the DataMasque application Settings.

Ensure that the correct metadata XML file has been provided to DataMasque, following the export IdP metadata XML and DataMasque configuration sections of this guide.

Missing identity provider certificate in metadata XML

When attempting to sign in with SSO, users may receive an error:

Single sign-on authentication failed: Missing identity provider certificate in metadata XML.

This error may occur when the IdP metadata XML file exported from your IdP does not contain a valid signing certificate.

Ensure that your IdP has been correctly provisioned with a SAML signing certificate, then re-export the metadata XML and upload this to DataMasque following the export IdP metadata XML and DataMasque configuration sections of this guide.

SAML signature validation error

When attempting to sign in with SSO, users may receive an error:

Single sign-on authentication failed: SAML signature validation error.

This error may occur in one of the following cases:

1. The SAML signing certificate in use by DataMasque does not match the certificate that is being used by the IdP.
2. The SAML signing certificate in use by the IdP may have expired.

Check the SAML signing certificate expiry date on your identity provider. If the certificate has expired, you will need to install a new SAML signing certificate on your IdP. When using AAD, ensure that the status of the newly created certificate is "Active". This may require activating the certificate by choosing "Make certificate active".

To ensure that DataMasque is using the correct signing certificate for your IdP, follow the export IdP metadata XML and DataMasque configuration sections of this guide.

SAML response is missing required attributes

When attempting to sign in with SSO, users may receive an error:

SAML response is missing required attributes. Ensure identity provider SAML attribute mapping is configured correctly.

This may occur when the SAML attribute mapping is incorrectly configured. Ensure that the IdP has been configured following the user attribute mapping section of this guide. Pay careful attention to the SAML attribute and namespace values.