Help Center

Menu

SAML identity provider

Overview

Workplace is able to support users whose accounts are managed in Active Directory Federated Services (AD FS) with security assertion markup language (SAML)-based single sign-on.

After completing this configuration process, user accounts in AD FS are automatically created in Workplace when the user logs in to Workplace for the first time. Any user fields updated in AD FS are automatically updated in their corresponding fields in Workplace the next time the user subsequently logs in to Workplace.

AD FS with SAML is not configured by default in Workplace.

Use the instructions provided on this page to implement AD FS with SAML within your Workplace instance.

Prerequisites

To set up AD FS with SAML for your Workplace instance, you require a Workplace user whose account type is system administrator in Workplace. These people are known as Workplace system administrators.

Read more about morphing an existing Workplace user into a Workplace system administrator in Changing Account Types of the Squiz Matrix documentation. An existing Workplace system administrator can morph an existing Workplace user to a Workplace system administrator account type.

A Squiz staff member with server-level access to your Workplace instance itself. These people are known as Workplace server administrators.

Active Directory Federation Services (AD FS) configured within your organisation by an AD FS administrator.

A simpleSAMLphp service installed as part of your Workplace instance. This should normally be part of your Workplace instance.

Last, ensure the general prerequisites have been met before continuing.

Configure Workplace’s SimpleSAMLphp service

Configuring Workplace’s SimpleSAMLphp service requires work conducted by Workplace server administrators, AD FS administrators and Workplace system administrators.

Configure the SimpleSAMLphp certificate files for Workplace

SimpleSAMLphp is a native PHP application that provides Workplace with SAML-based authentication and single sign-on capabilities.

Contact your Squiz Workplace server administrator to configure the SimpleSAMLphp certificate files for your Workplace instance.

Obtain the FederationMetadata.xml data/file from your AD FS server

As an AD FS administrator, obtain the FederationMetadata.xml data/file for your AD FS instance. You can do this using Microsoft’s Federation Metadata Explorer page.

Ensure that your FederationMetadata.xml data/file includes the following claims, as the minimum requirement:

  • username

  • first name

  • last name

  • email address

Configure your Workplace instance with the FederationMetadata.xml file

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the Asset Map section on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Authentication asset and expand its tree.

  3. Right-click the SAML-authentication asset and choose Details (and Acquire Locks on the right if necessary).

  4. Scroll down the page and under the Parse Metadata XML section (towards the middle of the page), copy the contents of the FederationMetadata.xml data/file above and paste this into the XML metadata text box.

  5. Click Commit, which converts this XML data to its PHP equivalent for Workplace’s SimpleSAMLphp service.

Complete the SimpleSAMLphp configuration for Workplace

Contact your Squiz Workplace server administrator to complete the SimpleSAMLphp configuration process for your Workplace instance. This entails updating the saml20-idp-remote.php and authsources.php files associated with your Workplace instance.

Configure Workplace with the authorisation source defined in SimpleSAMLphp

As a Workplace system administrator, configure the authorisation source you defined in Workplace’s SimpleSAMLphp service above.

  1. Ensure you are logged in to Workplace as a Workplace system administrator and have accessed admin mode.

  2. In the Asset Map section on the left, locate the Squiz Workplace Mk III > Squiz Workplace - Site > Authentication asset and expand its tree.

  3. Right-click the SAML-authentication asset and choose Details (and Acquire Locks on the right if necessary).

  4. Scroll down the page and under the General Settings section (near the top), choose the Authentication Source you configured above (e.g. sso-sp), and click Commit to save your changes.

  5. Scroll further down to the Asset Creation Settings section (towards the middle of the page) and for the Matrix User to Create field, choose Simple Edit User.

  6. In the Metadata Schemas to Apply fields, specify the following assets using Change and by clicking More to add another asset field:

    • located within the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Metadata asset:

      • Content Personalisation

      • (Client) Custom user setttings

      • (Client) Staff Profile CSV Settings

    • located within the Squiz Workplace Mk III > Squiz Workplace - Platform (Authorised Access Only) > Metadata schemas asset:

      • User settings

      • Authentication settings

  7. In the next Populate User Attributes section, for the Attributes To Populate on Creation, specify the following values for these attributes (using the Add Attribute drop down to add the appropriate attribute).

    • Email

    • First Name

    • Last Name

    • You can keep the default values for these attributes unchanged.

    • If, however, you want to customise these values, do so by specifying the value %globals_session_saml_attributes_FIELDNAME_0%, where FIELDNAME is the name of the LDAP field (with any non-valid field characters typically converted to underscores).

    • You can also create a 'test' page and specify the keyword replacement value %globals_session_saml_attributes%, to see a list of possible values.

That’s it! Your Workplace instance should now be configured with AD and SAML.

When new users sign in, verify that their accounts are added within the Squiz Workplace Mk III > Squiz Workplace - Site > Site Configuration > Squiz Workplace Users > SAML Users asset.