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_MyUserSynchronizationStrategy")
public class MyUserSynchronizationStrategy extends AbstractLdapUserDetailsSynchronizationStrategy<User> {
@Override
protected Class<User> getUserClass() {
return User.class;
}
@Override
protected void mapUserDetailsAttributes(User userDetails, DirContextOperations ctx) {
userDetails.setFirstName(ctx.getStringAttribute("givenName"));
userDetails.setLastName(ctx.getStringAttribute("sn"));
}
}
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.