LDAP Authentication
Configuration |
Basic LDAP connection properties |
Configuration of user and group lookup |
Since version 3.2, it is possible to configure the Server to use an LDAP server for users authentication. This way, credentials of users registered in LDAP may be used for authentication to any CloverDX Server interface (API or web console).
However, the authorization (access levels to sandboxes content and privileges for operations) is still handled by the CloverDX security module. Each user, even when logged-in using LDAP authentication, must have their own "user" record (with related groups) in the CloverDX security module. So there must be a user with the same username and domain set to "LDAP". Since version 5.4 user accounts can be created automatically on first time login and users can also be assigned to a default group.
The automatic account creation on first time login is controlled by the security.ldap.user_autocreate
property, which defaults to false
.
Since users have no access to the server console by default or any other permissions, you need to also automatically assign them to a group.
This can be achieved by either using LDAP for user synchronization or by setting the security.ldap.default_user_group
property.
The expected value of the property is the code of the group you want new users to be assigned to.
If the property is not set or no user group with the given code is found, the login operation will fail and an error message is logged.
To configure LDAP authentication, use the Setup GUI.
Use LDAP for user authentication only
If this Authentication Policy is selected, CloverDX Server uses LDAP directory to verify only the user's password:
The user specifies the LDAP credentials in the login form to the Server web console.
CloverDX Server looks up the user's record and checks whether it has the "LDAP" domain set. If there is no existing user account and
security.ldap.user_autocreate
is set totrue
, the login process continues, otherwise it fails.The Server attempts to connect to the LDAP server using the user's credentials.
If it succeeds and the user has existing account, the login succeeds. If there is no existing user account, then a user account is created and assigned to the group specified using the
security.ldap.default_user_group
property.
Use LDAP for user authentication and user synchronization
In this mode, CloverDX Server verifies user's credentials and synchronizes additional information (group, name and email) with those stored in LDAP.
In case the Server is configured for user authentication and group synchronization, the procedure is as follows:
The user specifies the LDAP credentials in the login form to the Server web console.
CloverDX Server looks up the user's record and checks whether it has the "LDAP" domain set.
CloverDX Server connects to the LDAP server and checks whether the user exists (it uses specified search to lookup in LDAP).
If the user exists in LDAP, CloverDX Server performs authentication.
If the authentication is successful, CloverDX Server searches LDAP for user's groups.
CloverDX user is assigned to the CloverDX groups according to his current assignation to the LDAP groups.
If no matching groups are found, user is assigned to the group defined in the
security.ldap.default_user_group
property.User is logged-in.
Note | |
---|---|
Switching domains:
|
Configuration
By default CloverDX Server allows only its own internal mechanism for authentication.
To enable authentication with LDAP, set the configuration property security.authentication.allowed_domains
properly.
The value of the property is a list of user domains that are used for authentication, e.g.:
security.authentication.allowed_domains = clover,LDAP
When set as in the example above, users from both domain may login.
(clover
is an identifier of CloverDX internal authentication
and may be changed by the security.default_domain
property, but only for white-labeling purposes.)
It's recommended to allow both mechanisms together, until the LDAP is properly configured.
So the admin user can still login to web GUI although the LDAP connection isn't properly configured.
You can use Setup to configure LDAP authentication. See LDAP in Chapter 15, Setup.
Basic LDAP connection properties
# Implementation of context factory. security.ldap.ctx_factory=com.sun.jndi.ldap.LdapCtxFactory # URL of LDAP server. security.ldap.url=ldap://hostname:port # User DN pattern that will be used to create LDAP user DN from login name. security.ldap.user_dn_pattern=uid=$${username},dc=company,dc=com
Depending on the LDAP server configuration,
the property security.ldap.user_dn_pattern
can be pattern for user's actual distinguished name in the LDAP directory,
or just the login name - in such a case just set the property to $${username}
.
Configuration of user and group lookup
In order to be able to synchronize the Clover groups with those defined in LDAP directory,
the security.ldap.user_dn_pattern
has to be left unspecified.
There are additional properties required so that the server is able to search the LDAP directory.
# User DN of a user that has sufficient privileges to search LDAP for users and groups. security.ldap.userDN=cn=Manager,dc=company,dc=com # The password for user mentioned above. security.ldap.password=
There are optional settings affecting how the LDAP directory is searched.
# Timeout for queries searching the directory. security.ldap.timeout=5000 # Maximal number of records that the query can return. security.ldap.records_limit=2000 # How LDAP referrals are processed, possible values are: 'follow', 'ignore' and 'throw'. # The default depends on the context provider. security.ldap.referral=
Specified values work for this specific LDAP tree:
dc=company,dc=com
ou=groups
cn=admins (objectClass=groupOfNames,member=(uid=smith,dc=company,dc=com),member=(uid=jones,dc=company,dc=com))
cn=developers (objectClass=groupOfNames,member=(uid=smith,dc=company,dc=com))
cn=consultants (objectClass=groupOfNames,member=(uid=jones,dc=company,dc=com))
ou=people
uid=smith (fn=John,sn=Smith,mail=smith@company.com)
uid=jones (fn=Bob,sn=Jones,mail=jones@company.com)
Following properties are necessary for lookup for the LDAP user by his username. (step [4] in the login process above)
# Base specifies the node of LDAP tree where the search starts. security.ldap.user_search.base=dc=company,dc=eu # Filter expression for searching the user by his username. # Note, that this search query must return just one record. # Placeholder ${username} will be replaced by username specified by the logging user. security.ldap.user_search.filter=(uid=$${username}) # Scope specifies type of search in "base". There are three possible values: SUBTREE | ONELEVEL | OBJECT # http://download.oracle.com/javase/8/docs/api/javax/naming/directory/SearchControls.html security.ldap.user_search.scope=SUBTREE
Following properties are names of attributes from the search defined above. They are used for getting basic info about the LDAP user in case the user record has to be created/updated by CloverDX security module: (step [6] in the login process above)
security.ldap.user_search.attribute.firstname=fn security.ldap.user_search.attribute.lastname=sn security.ldap.user_search.attribute.email=mail # This property is related to the following step "searching for groups". # Groups may be obtained from specified user's attribute, or found by filter (see next paragraph). # Leave this property empty if the user doesn't have such attribute. security.ldap.user_search.attribute.groups=memberOf
In the following step, CloverDX tries to find groups which the user is assigned to. (step [4] in the login process above). There are two ways how to get list of groups which the user is assigned to. The user-groups relation is specified on the "user" side. The user record has some attribute with list of groups. It's "memberOf" attribute usually. Or the relation is specified on the "group" side. The group record has an attribute with list of assigned users. It's "member" attribute usually.
In case the relation is specified on users side, please specify the property:
security.ldap.user_search.attribute.groups=memberOf
Leave it empty otherwise.
In case the relation is specified on the groups side, set properties for searching:
security.ldap.groups_search.base=dc=company,dc=com # Placeholder ${userDN} will be replaced by user DN found by the search above. # If the filter is empty, searching will be skipped. security.ldap.groups_search.filter=(&(objectClass=groupOfNames)(member=$${userDN})) security.ldap.groups_search.scope=SUBTREE
Otherwise, please leave property security.ldap.groups_search.filter empty, so the search will be skipped.
Clover user record will be assigned to the clover groups according to the LDAP groups found by the search (or the attribute). (Groups synchronization is performed during each login)
# Value of the following attribute will be used for lookup for the CloverDX group by its code. # So the user will be assigned to the CloverDX group with the same "code". security.ldap.groups_search.attribute.group_code=cn
Active Directory
CloverDX Server uses User Principal Name (UPN) username@domainname
for user authentication with Active Directory.
So if the domain name is the same for all CloverDX Server users,
you can set security.ldap.user_dn_pattern
to contain the name of the domain and then log in just using the user name,
e.g. john.doe
:
security.ldap.user_dn_pattern=$${username}@mydomain
If you need to use multiple domain names, use security.ldap.user_dn_pattern=$${username}
instead
and then enter the full UPN as the User name on the login page,
e.g. john.doe@mydomain
.