Configure identity management

Identity management defines the various means by which users authenticate and receive their authorization to access Semarchy xDM features and applications.

Configure identity management

Identity management configuration includes:

Identity providers available to authenticate;
(Optional) Role lookup that applies to all authenticated users;
Branding for the login page.

Identity management is a platform-level administrative task performed in the Configuration module.

To access the identity management editor, from the navigation drawer of the Configuration module, select Identity Management.
The Identity Management editor opens.

The Identity Management editor is saved as a whole. Therefore, any changes made in this editor are considered changes in identity management.

Configure identity providers

In the Identity Management editor, the Identity Providers tab displays two lists of IDPs:

The single sign-on (SSO) IDPs. These IDPs do not require the users to enter their credentials in a login form handled in Semarchy xDM. Users are redirected to the external IDP login experience.
The login form IDPs. These IDPs require the user to enter their login and password in a login form handled by Semarchy xDM.

In each list, identity providers can be enabled or disabled, deleted, and ordered. The order of the enabled IDPs defines the login experience:

Single sign-on IDPs appear as buttons on the login page in their list order, each redirecting to the SSO provider login experience. If only one SSO IDP and no Login form IDP is enabled, then the user is directly redirected to the enabled SSO IDP without seeing the Semarchy login page.
If at least one login form IDP is enabled, then the login form appears on the login page. If multiple login form IDPs are enabled, the login information entered by the user in the form is sent to each IDP in the list order until one IDP authenticates the user successfully.

When configuring identity management, carefully review and test the enabled IDPs. Make sure to also test the various authentication flows and conditions.

Semarchy xDM allows specifying which IDPs should be enabled on a given node in a high-availability cluster. The list of IDPs can be defined by setting the xdm.idm.availableidps property in the startup configuration. For a full description of this property, see Identity management.

Add an IDP

To add an identity provider:

In the Identity Management editor, select the Identity Providers tab.
Click the Add Provider floating action button in the lower-right corner of the screen.
In the New identity provider dialog, select a provider type, give a name to the new IDP, and then click Create.
The new Identity Provider editor opens.
In this editor, enter the configuration properties for your IDP type. The properties required depend on the type of IDP:
Test the identity provider.

Configure roles

When a user authenticates with an external IDP, the IDP returns a list of roles assigned to the user in the IDP. These roles represent how users are organized in the IDP. They may represent teams, departments, user groups, and sometimes actual roles. They may not be fit for Semarchy xDM as they are.

To adapt the roles, you can configure for each IDP:

Default roles, which are granted upon login to all users authenticated using the IDP.
Role mappings, to transform IDP roles into Semarchy roles.

To configure an identity provider’s roles:

In the Identity Management editor, select the Identity Providers tab.
Click the identity provider you want to configure, and then select the Roles tab.

(Optional) Select one or more default roles. Note that you can only select roles already defined on the platform.

The default roles provide the baseline privileges to all users authenticated with the IDP. For example, to allow all users from your Google domain to access the Semarchy platform, select the semarchyConnect default role for that IDP.

Configure the role mappings:
1. In the Role Mapping table, click the Add Role Mapping button to add a new role mapping.
  A new line appears in the Role Mapping table.
2. In the Provider Role cell, enter the role or group returned by the IDP.
3. In the Mapped Role cell, select one or more platform roles you want to assign to the user having the provider role in the IDP.
  
  You can select the Use regular expressions checkbox to convert provider role patterns into mapped roles using regular expressions.
To retain the roles or groups returned by the IDP after role mapping, enable the Keep provider roles toggle. If this toggle remains off, only the default and mapped roles will be retained for the user after role mapping.
Test the IDP.

Role mapping with regular expressions

In the Role Mappings table, you can select the Use regular expressions option if you want to detect a pattern in the provider role and convert it to a mapped role using regular expressions.

The following role mapping example illustrates how to use this capability.

Role mapping with regular expressions

Users in the IDP are categorized into either the SUPP_US, SUPP_EMEA, or another group. This group should be translated into the semarchyConnect and Support roles, along with the respective US, EMEA, or other regional roles.

Provider role Mapped role Description

Provider role	Mapped role	Description
`SUPP_.*`	`semarchyConnect, Support`	If an IDP role starts with `SUPP_`, then the `Support` and `semarchyConnect` roles are mapped.
`SUPP_(.*)`	`$1`	If an IDP role starts with `SUPP_`, then the rest of the role string is captured and returned as a mapped role (e.g., `SUPP_EMEA` would be mapped to `EMEA`).

SUPP_.*

semarchyConnect, Support

If an IDP role starts with SUPP_, then the Support and semarchyConnect roles are mapped.

SUPP_(.*)

$1

If an IDP role starts with SUPP_, then the rest of the role string is captured and returned as a mapped role (e.g., SUPP_EMEA would be mapped to EMEA).

Role names and labels

The roles are referenced in the configuration by their role name (e.g., BusinessUser or DataSteward). The configuration user interface displays roles found in the Semarchy xDM roles with their corresponding label (e.g., Business User, Data Steward).

When you select a default role or configure a role mapping without regular expressions, this Semarchy xDM role appears with its role label (e.g., Business User). A role used in the configuration with no corresponding Semarchy xDM roles appears with the role name (e.g., BusinessUser) as defined in the configuration, since it was not found in the list of Semarchy xDM roles.
When using regular expressions, the mapped role value is a comma-separated list of role names (e.g., BusinessUser).

Configure profile synchronization

Profile synchronization brings information from the IDP into the user profile and defines the properties available to the user in their profile.

To configure an identity provider’s roles:

In the Identity Management editor, select the Profile tab.
The tab lists all the properties of the user profile.

Define how each property is managed:

Synchronize defines how the property should be synchronized from the IDP. Possible values are:
- Each Login: synchronizes the property from the IDP at each user login. The property cannot be modified by the user.
- First Login: synchronizes the property from the IDP the first time the user logs in. The property may be modified by the user afterward depending on the user access configuration.
- Never: does not synchronize the property from the IDP. The property may have a default value, and be modified by the user afterward depending on the user access configuration.

Synchronize From defines the value that should be synchronized from the IDP. The syntax and value in this field depend on the IDP type. For example, for OpenID Connect, the value is a claim. For LDAP, it is an attribute of the user object.

For some properties, the Synchronize From field is automatically seeded with a default value, which uses the standard (or most common) property mapping for the type of IDP. You can click the

Reset Default Value button on each field to reset its value to the default at any time.

For more details on how to configure each IDP, see the following resources:

Default Value defines the default value of the profile property. If the IDP does not provide a valid value for a synchronized property, this default value is applied. For properties that are never synchronized, the default value is set directly in the user profile.

The table below lists the required profile properties that must be configured for proper IDP operation. If no value is synchronized from the IDP and no default value is configured, fallback values are applied.

Required property Fallback value

language

Inferred from the browser locale at login (defaults to en_US if no header is present or if consumed before login).

timezone

Inferred from the browser locale at login or the server timezone if consumed before login.

dateFormat

Inferred from the language settings.

datetimeFormat

Inferred from the language settings.

decimalSeparator

Inferred from the browser locale at login (defaults to en_US if no header is present or if consumed before login).

thousandSeparator

Inferred from the language settings.

densityMode

Standard spacing.

User Access defines how the property appears in the user profile. Possible values are:
- Hidden: hides the property from the user profile. The user cannot edit it.
- Read: displays the property in the user profile as a read-only field.
- Read/Write: displays the property in the user profile as an editable field. Note that if a property is set to synchronize at each login, it cannot use that user access configuration.

Test the IDP to review the property values for a test user.

Configure the login button

SSO identity providers appear on the login page with a button to redirect to the SSO login experience. The Button tab allows you to configure the appearance of this button, including the Button Label, Button Color, and Button Image (from the image library).

Test the IDP

It is recommended to test the IDP at each stage of its configuration:

After configuring the connection and authentication in the Configuration tab.
After configuring the role mappings in the Roles tab.
After configuring the profile synchronization in the Profile tab.

The date and outcome of the most recent connection test appear both in the identity provider list and within each IDP’s Configuration tab. Additionally, the color of the

Test icon indicates whether the IDP has not been tested (gray), was successfully tested (green), or unsuccessfully tested (red) since the last modification.

To test an identity provider:

In the Identity Management editor toolbar, click the Test button.
The Identity Provider Test side sheet opens.
Click the Start Test button on the side sheet.
In a new incognito browser window, open the Log In link that appears in the side sheet.

Starting the test in a new incognito window guarantees that your test session does not reuse the connection with which you configure identity management.
Log in to Semarchy xDM in this incognito window, using the identity provider that you want to test.
In the Identity Provider Test side sheet, review the result and the log of the test.

The IDP test mode tracks all incoming logins on the IDP for 180 seconds and is automatically disabled. You can disable the test mode by clicking the Stop Test button. Leaving the IDP editor automatically disables the test mode.

Configure role lookup

Role lookup automatically adds roles to users connecting with any of the identity providers (including the internal IDP). These roles are retrieved from a table containing a list of records, each record containing a user name and a role name assigned to this user, as shown in the example below:

Role lookup table example: CUSTOM_ROLES
USER	GRANTED_ROLE
john.doe	semarchyConnect
john.doe	dataSteward
jane.smith	semarchyConnect
jane.smith	dataAdmin
jane.smith	semarchyAdmin

To configure role lookup:

In the Identity Management editor, select the Roles Lookup tab.
Select the Enable roles lookup from a database switch.
In the Role Lookup Datasource section, configure the connectivity to the database containing the roles lookup table:
- Database Type: Selected the technology of the database.
- URL: enter the JDBC URL to connect the database.
- Username: enter the user name to authenticate to the database. This user should have read access to the roles lookup table.
- Password: this user’s password.
- You may optionally provide advanced datasource configuration in the Advanced Datasource Configuration section.
Enter the name of the Role lookup table (e.g., CUSTOM_ROLES). Note that you also use a view defined in the database the same way you would use a table.
Enter the name of the Username column and Role name column (e.g., USER and GRANTED_ROLE).
Click the Test button to test the configuration. The test returns the top 10 records of the lookup table. Review these results.
Save your configuration.

Configure the login page

The layout of the login page depends on the identity provider configuration enabled for a given node.

You can also enable different sets of identity providers for specific Semarchy xDM nodes. For more information, see Identity management.

Within the Identity Management editor’s Login Page tab, you can configure two components of this page:

The login page logo, which appears in the header of the login page.
Under Login Page Logo, click the Select an image icon to choose a logo from the image library.
The login page message, which is displayed at the bottom of the login page, before the login button. If there is no login form, the message appears after all the SSO buttons.
In the Login Page Message field, enter your custom text. This message supports Markdown syntax.

Configure identity management using the REST API

Endpoints are available on the Semarchy xDM REST API to consult and define the configuration of identity management. For more information, see the REST API documentation.