SAML account manager

Overview

The SAML account manager allows you to integrate SAML 2.0 federated access through a nominated identity provider.

When a user visits the SAML account manager asset, the system will redirect the user to the SAML authentication system. After successfully authenticating their account, the user will be redirected back to Matrix and logged into the system using their linked local user account if one has already been created.

If no account has been linked to the current user, Matrix will either identify an associated account within Matrix to link to (that is, one the user is also logged in with) or create a new local user account within the system to link.

After the SAML user has been successfully authenticated and linked, their user profile data will be retrieved through the service provider’s profile API.

This data is stored within the session and is available using the following keyword replacements:

%globals_session_saml_attributes%

The entire attributes data as a JSON array.

%globals_session_saml_attributes_x%

Specified value from the attributes JSON array.

For example, if the JSON data is as follows:

{  "first_name":"John",  "last_name":"Doe",  "email":"jd@example.com"}

We can use the following keyword to extract the first_name value of John by using: %globals_session_saml_attributes_first_name%

If a JSON key has non-alphanumeric characters in it (applies to all characters except for _, -, and .), they will need to get replaced with underscores when using the SAML keyword to print the value.

For example, if the JSON attribute has the following format:

{  "http://www.site.com/name":"John"}

The keyword to extract that value would be: %globals_session_saml_attributes_http___www.site.com_name%

No caching settings should be used on a SAML account manager asset, including Matrix caching, HTTP cacheable headers, or any external proxy caching.

Additional dependant assets

SAML account manager dependant assets

When you create a SAML account manager within your system, several assets are automatically created beneath it, as highlighted in the previous figure.

You can use these assets to define the contents and layout of the SAML account manager.

Create user

This bodycopy is used to define the layout to display to a SAML user when no associated user account is found within Matrix. This will allow the user to create and link to a new user account within the system.

Create link

This bodycopy is used to define the layout to display to a SAML user when an associated user account is found within Matrix. This will allow the user to link these user accounts, enabling federated access to the system.

Logged in

This bodycopy is used to define the layout to display to a logged-in SAML user with a linked Matrix account.

Authentication failed

This bodycopy is used to define the layout to display to a user when authentication fails on the SAML account manager.

Details screen

The Details screen allows you to configure the settings of the SAML account manager. The settings available on this screen are similar to those of the Account manager asset.

This page will only cover the fields that specifically relate to the functionality of the SAML account manager.

General settings

The general settings section of the Details screen displays the status of SAML on your system and allows you to configure its general settings.

The general settings section is shown in the figure.

The general settings section of the Details screen

The fields available in this section are as follows:

SimpleSAMLphp status

Displays the status of SAML on your system. If SimpleSAMLphp has been correctly integrated and installed on the Matrix system, this field will read Installed. If SAML is not found configured on your system, this field will read Not installed.

This setting is not visible in Matrix 5.5.0.0 and above as SimpleSAMLphp is automatically installed.
Authentication source

Select the authentication source type of the SAML identity provider. The options available here will depend upon the SimpleSAMLphp configuration on your system.

SAML user ID location

The location to source a unique user ID on the SAML authentication response. This setting can either be set as the NameID element of the SAML user or from a nominated attribute element. Selecting the attribute element setting in this field will display the Attribute element name field, where the attribute can be specified.

Allow linking to existing users

This option allows you to link an existing Matrix user accounts with their authenticated SAML identities. This means that if a user is logged into the system and their account is SAML authenticated, the SAML account manager will prompt the user to link their accounts if they have not already been. This allows for federated access to the system, automatically signing the user into their account as part of the SAML authentication process. By default, this option is enabled.

Automatic creation

This option allows for the automatic creation of linked local users when a user is not logged into Matrix. By default, this option is a manual process, with users being allowed to create a new user account during SAML authentication. Enabling this field will automate this creation, skipping this procedure.

Disallow password login

This option allows you to randomize Matrix users' passwords when they are linked to a SAML account. This will prevent them from logging into the system using the standard username and password; they can only sign in through the SAML bridge.

Authentication request

The authentication request section of the Details screen allows you to configure the request sent to the SAML identity provider from Matrix.

The authentication request section is shown in the figure.

The authentication request section of the Details screen

The fields available in this section are as follows:

NameID policy

The format of the NameID attribute on the SAML authentication request. This option can be either persistent, transient, or left empty.

Protocol binding

The format of the ProtocolBinding attribute on the SAML authentication request. This option can be either persistent, transient, or left empty.

AuthnContextClassRef

The value of the AuthnContextClassRef attribute on the SAML authentication request.

Use extensions

Enables to use of query extensions on the SAML authentication request. If this field is enabled, an Additional extensions field will be displayed, allowing you to configure extensions on the SAML authentication request. Consult your identity provider’s integration guide for more information on the settings in this section.

SAML 2.0 service URLs

The SAML 2.0 service URLs section of the Details screen displays the service URLs of the SimpleSAMLphp configuration on your system. These URLs are displayed for use when configuring the settings of your SAML identity provider. The SAML 2.0 service URLs section is shown in the figure below.

The SAML 2.0 service URLs section of the Details screen

The fields available in this section are as follows:

Assertion consumer service URL

The URL of the SAML assertion consumer service on your system.

Single logout service URL

The URL of the SAML single logout service on your system.

Service provider metadata download URL

The download URL of the service provider metadata file for use on the SAML identity provider.

Consult your identity provider’s integration guide for more information on the use of the SAML 2.0 service URLs.

Parse metadata XML

The parse metadata XML section of the Details screen allows you to convert your identity provider’s SAML 2.0 metadata XML for use on your SimpleSAMLphp metadata configuration. The parse metadata XML section is shown in the figure.

The parse metadata XML section of the *Details* screen

In the XML metadata field enter the SAML 2.0 metadata XML of your identity provider and click Save.

This XML will be converted for SimpleSAMLphp for use within the saml20-idp-remote.php file on your SimpleSAMLphp installation within Matrix.

Asset creation settings

The asset creation settings section of the Details screen allows you to configure the user asset types that will be created during the SAML authentication process when no linked Matrix user is found.

Matrix user to create

Select the user account types to create for new Matrix users during the SAML authentication process. The account types available are:

  • User

  • Backend user

  • Content editor

  • System administrator

    Read the Permissions documentation for more information on the available user types.

    Metadata schemas to apply

    This field allows you to select a metadata schema that will automatically be applied to the created user assets. Users can input the metadata of the nominated schema when creating their accounts.

Populate user attributes

The populate user attributes section of the Details screen allows you to define the user attributes of your SAML authorized users using the profile data returned from the identity provider.

The following user attributes can be set:

  • First name

  • Last name

  • Sign-in date

  • Sign-in IP

  • Disallow password sign-in

  • Email

  • Restrictions

  • History passwords

  • Username

  • Password

  • Locale

To set an attribute, select it in the Add attribute field and click Save; the Attributes to populate on creation field will be displayed in the populate user attributes section. In the Value field of the attribute being set, enter the source string from which to retrieve the specified attribute data.

To delete an attribute that has been set, select the corresponding Delete check-box and click Save. The attribute will be removed from the populate user attributes section.

Sync user attributes

The sync user attributes section of the Details screen allows you to configure a set of user attributes of your SAML authorized users, populated from the profile data returned from the identity provider, that will sync each time a user logs into the system.

The following user attributes can be set:

  • First name

  • Last name

  • Sign-in date

  • Sign-in IP

  • Disallow password sign-in

  • Email

  • Restrictions

  • History passwords

  • Username

  • Password

  • Locale

To set an attribute, select it in the Add attribute field and click Save; the Attributes to sync on sign-in field will be displayed in the sync user attributes section.

In the Value field of the attribute being set, enter the source string from which to retrieve the specified attribute data.

To delete an attribute that has been set, select the corresponding Delete check-box and click Save. The attribute will be removed from the sync user attributes section.

Return location

The return location section of the Details screen allows you to set the location for users to redirect to after the SAML authentication process. The return location section is shown in the figure.

The return location section of the *Details* screen

The fields available in this section are as follows:

URL

The URL of the web page to return users to, for example, http://www.example.com. This option is useful when wanting to return users to a page outside of your Matrix system.

This URL requires the web protocol to be included (for example, HTTP://).

OR

Asset

An asset within the system to which to return users.

OR

Query string parameter

The name of a query string parameter whose value will specify the URL to return users to, for example, if this value is URL and the inbound query string includes ?URL=http://example.com, users will be returned to http://example.com.

Letting the return location URL be dynamic using a query string can result in attackers using this to redirect users to malicious sites.

Use custom redirect implementation on the "Signed-in bodycopy" instead to control what domains can be used for the dynamic redirect URL.

Redirect after sign-in

If enabled, the user will get redirected to the specified location as soon as they sign in.

Redirect after user created

If enabled, the user will get redirected to the specified location as soon as their linked Matrix user account has been created.

This setting will not work when Redirect after sign-in is enabled.
Redirect after link created

If enabled, the user will get redirected as soon as their existing Matrix user account is linked with their external, signed-in account.

Redirect delay

The number of seconds to delay the redirect. By default, this field is set to 0 (zero), meaning that the redirect will not be delayed. When a value is set in this field, JavaScript code will be used to execute the delayed redirect.

Advanced settings

Secure only cookie

Specify whether to enable the cookie_secure flag for the sq_saml_preserved_session_data cookie sent by the SAML account manager. Enabling this will cause browsers to not share the session cookie between HTTP and HTTPS.

HTTP only cookie

Specify whether to enable the cookie_http_only flag for the sq_saml_preserved_session_data cookie sent by the SAML account manager. An HTTP-only cookie will only be used when transmitting HTTP or HTTPS requests. Additionally, a web browser will not allow client-side scripts (such as JavaScript) to access to the cookie. This can help mitigate the effects of cross-site scripting attacks.

Logging a user out

To log out of a SAML session, the standard method of logging out of Matrix (http://example.com/page?sq_action=logout) will often result in a redirection back to the SAML IDP if the sign-in design template is set to redirect the user to the SAML account manager.

However, as the SAML IDP session is still valid, the user will automatically log in again by SAML IDP. This generally results in the user being logged back into Matrix. To ensure the user properly ends the SAML session, the user must be directed to: http://example.com/path/to/SAML-account-manager?logout

This will log the user out of Matrix and initiate a logout message back to the IDP.

Trigger method

This method will more reliably ensure users who log out of admin using the Logout button will also end their SAML session with the IDP.

  1. Create a trigger called SAML logout.

  2. Set the event to After user logs out.

  3. Set an action of redirect to URL, with the URL set to: http://example.com/path/to/SAML-account-manager?logout

Keyword replacements

The following keyword replacements can be used in implementations using the [SAML account manager] and OAuth account manager.

SAML Account Manager

Keyword replacement Information shown

%globals_session_saml_attributes%

The entire attributes data as a JSON array.

%globals_session_saml_attributes_<attrtibute_name>%

Specific value from the attributes JSON array. For example, %globals_session_saml_attributes_first_name%

Oauth account manager

Keyword replacement Information shown

%globals_session_oauth_profile%

The entire profile data as a JSON array.

%globals_session_oauth_profile_<profile_name>%

Specific value from the profile JSON array. For example, %globals_session_oauth_profile_first_name%

Examples

For example, if the JSON data returned for a SAML account manager is as follows:

{"first_name":"John", "last_name":"Doe", "email":"jd@example.com"}

We can use the following keyword to extract the first_name value of John by using: %globals_session_saml_attributes_first_name%

If a JSON key has non-alphanumeric characters in it (applies to all characters except for _, -, and .), they will need to get replaced with underscores when using the SAML keyword to print the value. For example, if the JSON attribute has the following format:

{"http://www.site.com/name":"John"}

The keyword to extract that value would be: %globals_session_saml_attributes_http___www.site.com_name%.

The same concept applies to the keywords for the OAuth account manager, just replace saml_attributes with oauth_profile in the keyword.

© 2015- Squiz Pty Ltd