Configure Identity Management

Identity Management defines that is 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:

To access the identity management editor:

Identity Management is a platform-level administrative tasks performed in Semarchy Configuration.
  1. In Configuration, select Identity Management in the navigation drawer.

The Identity Management editor opens.

The Identity Management editor is saved as a whole, so any change performed in this editor is considered a change in identity management.

Configure Identity Providers

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

  • The Single sign-on 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 that the user enter their login and password in a login form handled by Semarchy xDM.

Each list supports enabling/disabling, deleting as well as ordering identity providers. The order of the enabled IDPs define 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. In 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 IDPs 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.

Add an IDP

To add an identity provider:

  1. In the Identity Management editor, select the Identity Providers tab.

  2. Click on the Add Provider floating action button in the lower-right corner of the screen.

  3. In the New identity provider dialog, select a Provider Type, Name the new IDP, and then click CREATE.
    The new identity provider editor opens.

  4. In this editor, enter the Configuration Properties for your IDP Type. The properties required depend on the type of the IDP:

  5. Test the Identity Provider.

Configure the Roles

When a user authenticates with an external IDP, this 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 is.

To make the roles fit for usage, you can configure for each IDP:

  • Default Roles, 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:

  1. In the Identity Management editor, select the Identity Providers tab.

  2. Click the identity provider you want to configure, and then select the Roles tab.

  3. Optionally select one or more Default Roles. Note that you can only select roles already defined in 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.
  4. Configure the role mappings:

    1. In the Role Mappings table, click the Add Role Mapping button to add a new role mapping. A new line appears in the Role Mappings table.

    2. Enter in the Provider role cell the role/group returned by the IDP.

    3. Select in the Mapped Role cell one or more platform roles you want to assign to the user having the provider role in the IDP.

      You can optionally select the Use regular expressions checkbox to convert provider role patterns into mapped roles using regular expressions.
  5. Select the Keep provider roles switch to keep the role/groups returned by the IDP after the role mapping. If you unselect this switch, only the default roles and mapped roles remain for the user after the role mapping.

  6. Test the Identity Provider.

Role Mapping with Regular Expressions

In the Role Mappings table, select the Use regular expressions 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 belong to one of the SUPP_US, SUPP_EMEA, …​ groups. The group should convert into the semarchyConnect and Support roles, plus the US, EMEA, …​ role.

Provider Role

Mapped Role



semarchyConnect, Support

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



If an IDP role starts with SUPP_, then the rest of the role string is captured and returned as a mapped role. For example: 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, Steward). 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 his profile.

To configure an identity provider’s roles:

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

  2. Define how each property is managed:

    • Synchronize defines how the property should be synchronized from the IDP:

      • 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. Refer to each IDP for the configuration details:

    • Default Value defines the default value of the profile property. For the synchronized property, the default value is used if the IDP does not return a valid value. For a property that is never synchronized, the default value is seeded in the user profile.

    • User Access defines how the property appears in the user profile:

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

  3. Test the Identity Provider 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 result of the latest connection test appear in the Identity Providers list and each IDP’s Configuration tab. The color of the Test button icon Test button also reflects whether the IDP was untested (grey), successfully (green), or unsuccessfully (red) tested since it was last changed.

To test an identity provider:

  1. In the Identity Management editor toolbar, select the Test button icon Test button.
    The Identity Provider Test sidesheet opens.

  2. Click the Start Text button in the sidesheet.

  3. Open in a new incognito browser window the Log In link that appears in the sidesheet. Log in to Semarchy xDM in this incognito window, using the identity provider that you want to test.

  4. In the Identity Provider Test sidesheet, review the result and the log of the test.

Make sure to start the test in a new incognito window. This guarantees that your test session does not reuse the connection with which you configure identity management.
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 Cancel Test button. Leaving the IDP editor automatically disables the test mode.

Configure Roles 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:

Table 1. Role lookup table example: CUSTOM_ROLES













To configure roles lookup:

  1. In the Identity Management editor, select the Roles Lookup tab.

  2. Select the Enable roles lookup from a database switch.

  3. 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 use should have read access to the roles lookup table.

    • Password: This user password.

    • You may optionally provide advanced datasource configuration in the Advanced Datasource Configuration section.

  4. Enter the name of the Role lookup table. For example, CUSTOM_ROLES. Note that you also use a view defined in the database the same way you would use a table.

  5. Enter the name of the Username column and Role name column. For example, USER and GRANTED_ROLE.

  6. Click the TEST button to test the configuration. The test returns the top 10 records of the lookup table. Review these results.

  7. Save your configuration.

Configure the Login Page

The layout of the login page depends on the enabled identity providers configuration.

You can configure in the Identity Management editor’s Login Page tab two components of this page:

  • The Login Page Logo: This logo appears in the header of the login page. Select this logo from the image library.

  • The Login Page Message: This message appears at the bottom of the login page, before the login button. If the login page has no login form, the message appears after all the SSO buttons. This message supports the 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 details, refer to the REST API documentation.