Getting Started with LDAP

Let’s consider we will use LDAP authentication and maintain users in the application.

First, add the LDAP add-on to your project according to the installation section.

Configuring Main Properties

Now, add the main LDAP properties. We will use a test LDAP server - \ldap://ldap.forumsys.com:389/ that have some test users.

jmix.ldap.urls = ldap://ldap.forumsys.com:389/ 
jmix.ldap.base-dn = dc=example,dc=com
jmix.ldap.manager-dn = cn=read-only-admin,dc=example,dc=com
jmix.ldap.manager-password = password
jmix.ldap.user-search-filter = (uid={0})

jmix.ldap.default-roles contains a list of roles that will be assigned to every user authenticated in LDAP. It is needed since a user without any roles will not be able to log in to the application.

Set the jmix.ldap.default-roles property to ui-minimal.

jmix.ldap.default-roles=ui-minimal

You can find out more about the meaning of each property in the Properties section.

Configuring Synchronization

Now we need to describe the way we want users to be synchronized.

We will implement the default scenario when the add-on authenticates users from the application against LDAP. If a user is successfully authenticated in LDAP, but it does not have UserDetails in the application, it will be automatically synchronized, and UserDetails will be created in accordance with the corresponding LDAP entry.

Let’s declare a bean implementing the LdapUserDetailsSynchronizationStrategy interface. The add-on comes with a basic abstract implementation: AbstractLdapUserDetailsSynchronizationStrategy, so in a simple case the strategy can be declared by only specifying a concrete User class and implementing a simple mapping:

@Component("ldap_CustomUserSynchronizationStrategy")
public class CustomUserSynchronizationStrategy extends AbstractLdapUserDetailsSynchronizationStrategy<User> {

    private String getFirstName(String fullName) {
        return fullName.split(" ")[0];
    }

    @Override
    protected Class<User> getUserClass() {
        return User.class;
    }

    @Override
    protected void mapUserDetailsAttributes(User userDetails, DirContextOperations ctx) {
        userDetails.setFirstName(getFirstName(ctx.getStringAttribute("cn")));
        userDetails.setLastName(ctx.getStringAttribute("sn"));
        userDetails.setEmail(ctx.getStringAttribute("mail"));
    }
}

Note that AbstractLdapUserDetailsSynchronizationStrategy also persists role assignments that were obtained during the role mapping flow. After each synchronization execution, role assignments are rewritten with the new ones. It is done in order not to preserve the obsolete role assignments.

So, let’s set the jmix.ldap.synchronize-role-assignments to false in order to manage user roles manually in the application.

After the synchronization strategy is declared, users will be synchronized on every login. If you want to disable user synchronization on login, set the jmix.ldap.synchronize-user-on-login to false.

If you want to manage users fully in LDAP and not maintain them in the application, see the In memory user management section.