Skip to main content

LDAP integration

To enable Imply Hybrid (formerly Imply Cloud) Auth for your organization, contact your Imply account representative.

You can use LDAP-based identity federation with Imply SSO for user authentication and role assignment. By default, Imply LDAP maps username, email, first name, and last name from attributes.

Adding an LDAP provider​

To configure LDAP, follow these steps:

  1. Log in to the Imply user management console.
  2. Click User Federation from the left menu.
  3. Click the Add Provider menu and choose ldap from the list. The LDAP configuration settings appear as follows: LDAP config
  4. Configure the settings based on your requirements. The following sections provide more information about the settings.

Console Display Name​

Name used when this provider is referenced in the Admin Console.

Priority​

The priority of this provider when looking up users or adding a user.

Import users​

By default, Imply Hybrid Auth imports users from LDAP into the local Imply Hybrid Auth user database. This copy of the user is synchronized either on demand or through a periodic background task.

The single exception to this is the synchronization of passwords. Passwords are never imported. Their validation is always delegated to the LDAP server. The benefit of this approach is that all Imply Hybrid Auth features will work since any extra per-user data that is needed can be stored locally. The downside of this approach is that each time that a specific user is queried for the first time, a corresponding Imply Hybrid Auth database insert is performed.

The import may also have to be synchronized with your LDAP server. However, import synchronization is not necessary in the case that the LDAP mappers are configured to always read particular attributes from the LDAP server rather than from the database.

Alternatively, you can choose not to import users into the Imply Hybrid Auth user database. In this case, the common user model that the Imply Hybrid Auth service uses is backed only by the LDAP server. This means that if LDAP doesn't support a piece of data that an Imply Hybrid Auth feature needs, that feature will not work. The benefit to this approach is it avoids the overhead of importing and synchronizing a copy of the LDAP user into the Imply Hybrid Auth user database.

This storage mode is controlled by the Import Users switch. Set to On to import users.

If user import is disabled, you cannot save user profile attributes into the Imply Hybrid Auth database. Also, you cannot save metadata except for user profile metadata that are mapped to the LDAP. The single exception to this are user profile metadata, which are mapped to the LDAP. This includes role mappings, group mappings, and other metadata based on the configuration of your LDAP mappers.

When an attempt is made to change some of the non-LDAP mapped user data, an update of the user will not be possible. For example you will not be able to disable the LDAP mapped user unless the enabled flag of the user is mapped to some LDAP attribute (which is usually not the case).

Edit mode​

Users and admins can modify user information through the User Account Service and the Admin Console respectively. Your LDAP update privileges depend on your setup. The Edit Mode configuration option defines the edit policy you have with your LDAP store.

  • READONLY: Username, email, first name, last name, and other mapped attributes will be unchangeable. Imply Hybrid Auth will show an error anytime anybody tries to update these fields. Also, password updates will not be supported.
  • WRITABLE: Username, email, first name, last name, and other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
  • UNSYNCED: Any changes to username, email, first name, last name, and passwords will be stored in Imply Hybrid Auth local storage. It is up to you to figure out how to synchronize back to LDAP. This allows Imply Hybrid Auth deployments to support updates of user metadata on a read-only LDAP server. This option only applies when you are importing users from LDAP into the local Imply Hybrid Auth user database.

When the LDAP provider is created, the set of initial LDAP mappers is created. The mappers are configured on a "best-effort" basis based on the chosen combination of the Vendor, Edit Mode, and Import Users switches. For example, in case of UNSYNCED edit mode, the mappers are previously configured in a way that a particular user attribute is preferably read from the database instead of from the LDAP.



However, when you later change the edit mode, the mappers configuration will not be changed as it is not easily possible to detect if they were manually changed in the meantime. This means that it is recommended NOT to update the `Edit Mode` switch, but rather always decide on `Edit Mode` when creating the LDAP provider. This applies for `Import Users` switch as well.

Sync Registrations​

Does your LDAP support adding new users? To add new users created by the Imply Hybrid Auth in the Admin Console or the registration page to the LDAP, toggle the Sync Registrations switch.

Vendor​

Choose the LDAP vendor from the list of available vendors. Choosing a vendor populates the LDAP settings that follow with default values. Fill out the settings as appropriate for your LDAP system. Notice that you can test the connection to the LDAP system and authentication.

Other options​

For information about other configuration settings, hover over the tooltips for each setting in the Admin Console.

Synchronizing LDAP users to Imply Hybrid Auth​

After you create the LDAP configuration, you can synchronize users manually using the Synchronize changed users or Synchronize all users buttons.

If you have Import Users option enabled, the LDAP provider automatically synchronizes (imports) LDAP users into the Imply Hybrid Auth local database. As users log in, the LDAP provider imports the LDAP user into the Imply Hybrid Auth database and then authenticate against the LDAP password. This is the only time users will be imported.

If you go to the Users left menu item in the Admin Console and click the View all users button, note that only those LDAP users who have been authenticated at least once appear. Viewing all users does not trigger an import of the entire LDAP user database.

If you want to sync all LDAP users into the Imply Hybrid Auth database, you may configure and enable the Sync Settings on the LDAP provider configuration page.

Two types of synchronization exist, full sync and changed users sync, as described below.

Performing periodic full sync

Choose this option to synchronize all LDAP users into the Imply Hybrid Auth database. Those LDAP users which already exist in Imply Hybrid Auth and were changed in LDAP directly are updated in the Imply Hybrid Auth database. For example, the user Mary Kelly is changed in LDAP to Mary Smith.

Performing periodic changed users sync

When syncing occurs, only those users that were created or updated after the last sync will be updated and/or imported.

The best way to handle syncing is to click the Synchronize all users button when you first create the LDAP provider, then set up a periodic sync of changed users.

Setting up LDAP mappers​

After you create the LDAP configuration, the Mappers tab appears for the LDAP provider.

LDAP mappers are listeners, which are triggered by the LDAP Provider at various points and provide another extension point to LDAP integration. Mappers are triggered when users log in via LDAP and their data must be imported, during registration initiated by Imply Hybrid Auth, or when a user is queried from the Admin Console.

When you create an LDAP Federation provider, Imply Hybrid Auth automatically provides a set of built-in mappers for this provider. You are free to change this set and create a new mapper or update/delete existing ones.

User Attribute Mapper

User attribute mappers allow you to specify which LDAP attribute is mapped to which attribute of Imply Hybrid Auth user. So, for example, you can configure that LDAP attribute mail to the attribute email in the Imply Hybrid Auth database. For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one Imply Hybrid Auth attribute)

FullName Mapper

FullName mappers allow you to specify that the full name of the user, which is saved in some LDAP attribute (usually cn ) will be mapped to firstName and lastname attributes in the Imply Hybrid Auth database. Having cn to contain the full name of the user is common for LDAP deployments.

When registering new users in Imply Hybrid Auth and Sync Registrations is ON for the LDAP provider, the fullName mapper allows the possibility of fallback to the username. This fallback is especially useful in case of the Microsoft Active Directory (MSAD). The common setup for the MSAD is to configure cn LDAP attribute as fullName and at the same time, the cn is usually used as RDN LDAP Attribute, the configuration of the LDAP provider. With this setup, the fallback to the username will be used.

For example, when you create Imply Hybrid Auth user john123 and leave firstName and lastName empty, the fullName mapper saves john123 as the value of the cn in LDAP. When you later enter John Doe for firstName and lastName, the fullName mapper updates LDAP cn to the value John Doe, because a fallback to the username will not be needed anymore.

Hardcoded Attribute Mapper

This mapper adds a hard coded attribute value to each Imply user linked with LDAP. This mapper can also force the values for the enabled or emailVerified user properties.

Role Mapper

This allows you to configure role mappings from LDAP into Imply Hybrid Auth role mappings. One Role mapper can be used to map LDAP roles (usually groups from a particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of a specified client. It's not a problem to configure more Role mappers for the same LDAP provider. So for example you can specify that role mappings from groups under ou=main,dc=example,dc=org will be mapped to realm role mappings and role mappings from groups under ou=finance,dc=example,dc=org will be mapped to client role mappings of client finance.

Hardcoded Role Mapper

This mapper will grant a specified Imply Hybrid Auth role to each Imply Hybrid Auth user from the LDAP provider.

Group Mapper

This allows you to map LDAP groups from a particular branch of an LDAP tree into groups in Imply Hybrid Auth. It will also propagate user-group mappings from LDAP into user-group mappings in Imply Hybrid Auth.

MSAD User Account Mapper

This mapper is specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state into the Imply Hybrid Auth account state (account enabled, password is expired, and so on). It is using the userAccountControl and pwdLastSet LDAP attributes, which are both specific to MSAD and are not LDAP standard. For example if pwdLastSet is 0, the Imply Hybrid Auth user is required to update their password and there will be an UPDATE_PASSWORD required action added to the user. If userAccountControl is 514 (disabled account) the Imply Hybrid Auth user is disabled as well.