DataMasque Portal

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 has tested support for the following SAML identity providers:

  • On-Premise Active Directory (AD)
  • Azure Active Directory (AAD)
  • PingOne/PingIdentity SAML
  • Okta SAML

Additional configuration may be required for other identity providers.

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 provider1.
  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.

1If 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.

![Sign in with SSO](assets/images/sign-in-with-sso.png =*x400 "Sign in with SSO")

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

The following user attributes are required by DataMasque to complete the user account information within DataMasque. All these attributes must be configured.

The source attributes to use will depend on your identity provider and how you have set up each user's information within the identity provider. This table gives the usual source attributes to use for Azure Active Directory.

SAML attribute / claim Source attribute (AAD) DataMasque attribute mapping
name user.userprincipalname The user's username. Must be unique.
email user.mail The user's email address. Must be unique.

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.

Azure Active Directory Metadata XML

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.

PingOne/PingIdentity SAML Application

The XML metadata for a PingOne/PingIdentity SAML application can be downloaded from the Configuration section of the SAML application, by clicking the Download Metadata button in the Connection Details section.

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.

PingOne/PingIdentity SAML Configuration

To configure authentication using PingIdentity SAML, first create a new SAML Application in your PingIdentity console.

Once created, the configuration is split into four sections:

  • Configuration Settings
  • Attribute Mappings
  • Policies
  • Access

The options required for each configuration section are specified below.

Configuration Settings

Most configuration settings for the application can be left as the default, but you must specify:

  • ACS URLS: https://<hostname>/api/saml/acs/
  • Entity ID: https://<hostname>. Note there should be no trailing /.

From the Configuration tab you should also download the metadata XML by clicking the Download Metadata button.

Attribute Mappings

The SAML application adds the mapping from saml_subject to User ID automatically. The following additional mappings must also be added, and all should be marked as Required.

Attribute PingOne Mappings
email Email Address
name Username
nameId User ID

For each attribute, enter the attribute name as shown, and select the PingOne Mapping from the menu.

Policies

DataMasque does not require any specific policy configuration, so any changes in this section will be specific to your organisation.

Access

DataMasque does not require any specific access configuration, so any changes in this section will be specific to your organisation.

After configuring and enabling the SAML application in PingIdentity, and downloading the metadata XML, continue with the DataMasque configuration as described below.

Okta SAML Configuration

To configure authentication using Okta SAML, follow these steps:

1. Create a SAML Application in Okta

  1. Log in to your Okta account.
  2. Navigate to Applications and click on Create App Integration.
  3. Select SAML 2.0 as the sign-in method, then click Next.
  4. Enter "DataMasque" as the App name, then click Next.

2. Configure the SAML Settings

In the SAML Settings page, configure the following settings:

  • Single sign-on URL: https://<hostname>/api/saml/acs/
  • Audience URI (SP Entity ID): https://<hostname>. Note there should be no trailing /.

3. User Attribute Mapping

NameID Format

DataMasque uses the SAML NameID field to identify the user each time they sign in using SAML SSO. For the Name ID format option, select Persistent. Ensure that the SAML NameID is mapped to a unique, persistent identifier of each user.

Additionally, make sure the Response and Assertion Signature fields are both set to Signed.

Attribute Statements

For the Attribute Statements (Optional) section, configure the following attribute statements to ensure DataMasque can complete user account information:

SAML attribute / claim Source attribute (Okta) DataMasque attribute mapping
NameID user.userID The user's ID. Must be unique.
name Any attribute The user's username. Must be unique.
emailaddress user.email The user's email address. Must be unique.
givenname user.firstName The user's first name.
surname user.lastName The user's last name.

4. Save and Assign Users to the App

  1. Click Next after configuring the attribute statements.
  2. Select I’m an Okta customer adding an internal app and This is an internal app that we have created.
  3. Click Finish.
  4. Navigate to the application you created.
  5. Click on the Assignments tab.
  6. Assign users or groups to the application as required.

5. Export IdP metadata XML

After configuring the SAML application and assigning users, you need to export the metadata XML.

  1. Navigate to the application you created.
  2. Click on the Sign On tab.
  3. Scroll down and click View SAML setup instructions.
  4. Scroll down and copy the XML IdP metadata from the Optional section and save it as an XML file.

5. DataMasque configuration

Follow the DataMasque configuration instructions below to upload the Okta metadata XML 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:

![SAML Single Sign-On Settings](assets/images/settings-saml-sso.png =*x200 "SAML Single Sign-On Settings")

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.

If the user's email address is updated on the identity provider, DataMasque will detect and synchronise the change when the user next logs in to DataMasque. Note that there can be a delay between when the email address is updated and when the identity provider starts providing the updated email address on SSO logins.

Other properties of the user (such as their name) are not currently synchronised by DataMasque.

Revoking user access

Remove the user from the application on the identity provider. This will cause the identity provider to deny the authentication request when the user next attempts to sign-in.

Warning: Removing the user from the DataMasque application entry on the identity provider does not immediately terminate existing sessions the user may have with DataMasque.

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.