LDAP Synchronization

Squore can be plugged-in with one or more company directory services, allowing to synchronize the existing groups and users accounts in Squore with the content of these directory services. Only the LDAP protocol is supported.

Synchronization is configured in <SQUORE_HOME>/server/standalone/configuration/standalone.xml file, in urn:com:vector:squore subsystem.

Here is an example of what a synchronization configuration that uses more than one provider looks like:

<subsystem xmlns="urn:com:vector:squore:1.0" >
	<security>
		<authentication>
			...
		</authentication>
		<synchronization period="5" missing-user-action="keep" missing-group-action="keep">
			<sync-module name="myFirstLdapSync" provider="ldapSync-1"/>
			<sync-module name="mySecondLdapSync" provider="ldapSync-2"/>
		</synchronization>
		<providers>
			<provider name="ldapSync-1" type="ldap">
				<property name="url" value="ldaps://hostname:port/"/>
				<property name="principal" value="cn=admin,dc=domain,dc=com"/>
				<property name="password" value="password"/>
				<property name="usersCtxDN" value="ou=people,dc=example,dc=com"/>
				<property name="usersFilter" value="(objectClass=person)"/>
				<property name="userLoginAttribute" value="login"/>
				<property name="userIdentifierAttribute" value="useridentifier"/>
				<property name="userIdentifierAttributeIsDN" value="false"/>
				<property name="userDisplayNameAttribute" value="displayName"/>
				<property name="userMailAttribute" value="mail"/>
				<property name="userDepartmentAttribute" value="department"/>
				<property name="groupsToSync" value="true"/>
				<property name="groupsCtxDN" value="ou=groups,dc=example,dc=com"/>
				<property name="groupsFilter" value="(objectClass=group)"/>
				<property name="groupIdentifierAttribute" value="groupIdentifier"/>
				<property name="groupIdentifierAttributeIsDN" value="false"/>
				<property name="groupNameAttribute" value="name"/>
				<property name="groupMembersAttribute" value="member"/>
				<property name="groupMemberReferencedAttribute" value="useridentifier"/>
				<property name="groupMemberReferencedAttributeIsDN" value="false"/>
			</provider>
			<provider name="ldapSync-2" type="ldap">
                ...
			</provider>
		</providers>
	</security>
</subsystem>

When using more than one synchronization module, you must make sure that the modules resulting set of users and groups are independent, i.e. do not share any common users nor groups.

Synchronization module

The synchronization module is defined inside the synchronyzation element with a sync-module sub-element.

Accepted attributes for the synchronyzation element are the following:

period (optional), to define the time interval between each synchronization, in minutes.
missing-user-action (optional), to configure what to do during synchronization when a user has been removed from service directory. The following values are accepted:
- disableOrDelete (default), to disable the user if he has already logged in and delete otherwise.
- keepOrDelete, to keep the user if he has already logged in and delete otherwise.
- delete, to delete the user.
- disable, to disable the user.
- keep, to keep the user.
missing-group-action (optional), to configure what to do during synchronization when a group has been removed from service directory. The following values are accepted:
- delete (default), to delete the group.
- keep, to keep the group.

Accepted attributes for the sync-module sub-element are the following:

name (mandatory), to define the unique identifier for the synchronization module.
type (optional), to define the provider type (mandatory if no provider attribute is defined). Accepted value is the following:
- ldap
provider (optional), to define the provider name where the properties will be found.
enabled (optional, default: true), to enable or disable the synchronization module.

Providers

Providers are defined inside the providers element with provider sub-elements. Accepted attributes are the following:

name (mandatory), to define the unique identifier for the provider.
type (mandatory), to define the provider type. Accepted value is the following:
- ldap, to define LDAP protocol properties.

Each provider element accepts an unlimited number of property sub-elements used to define the necessary properties for the module as pairs of key/value. Accepted attributes are:

name (mandatory), to define the name of the property.
value (mandatory), to define the value of the property.

Properties can also be defined inside the sync-module element, but a good practice is to defined them in providers. If the same property is defined in both the referenced provider and in the sync-module then the latter take precedence over the former.

LDAP properties

LDAP properties will be used to define how and what to access in your company directory service. They are to be defined in providers of type ldap.

The mandatory properties are the following:

url, the URL of the Directory Server, default port is usually 636.
principal, the DN used to bind against the Directory Server for the user and groups queries. It should have read or search permissions on the usersCtxDN and groupsCtxDN values.
password, the password for the bind DN.
usersCtxDN, the fixed DN of the context to start the user search from.
usersFilter, the search query sent by Squore to the LDAP server when fetching users. For more information about LDAP query syntax, see https://ldap.com/ldap-filters. Note that the & characters must be written as an entity (&) in the settings file.
userLoginAttribute, the attribute field to use when loading the user login. Should be unique.
userIdentifierAttribute, the attribute that will be used to synchronize ldap users. Should be unique. Might leave empty if it is the DN.
userIdentifierAttributeIsDN, true if the userIdentifierAttribute is the DN, false otherwise.
groupsToSync, true if groups should be fetched, false otherwise.
groupsCtxDN, the fixed DN of the context to start the group search from.
groupsFilter, the search query sent by Squore to the LDAP server when fetching groups. For more information about LDAP query syntax, see https://ldap.com/ldap-filters. Note that the & characters must be written as an entity (&) in the settings file.
groupIdentifierAttribute, the attribute that will be used to synchronize ldap groups. Should be unique. Might leave empty if it is the DN.
groupIdentifierAttributeIsDN, true if the groupIdentifierAttribute is the DN, false otherwise.
groupNameAttribute, the attribute field to use when loading the group name. Should unique.
groupMembersAttribute, the attribute field to use when loading the group members.
groupMemberReferencedAttribute, the attribute field referenced by groupMembersAttribute values. Might leave empty if it is the DN.
groupMemberReferencedAttributeIsDN, true if the groupMemberReferencedAttribute is the DN, false otherwise.

If you do not want to synchronize the groups from your Directory Server, simply do not add the group related properties to your configuration.

Additional properties can be defined in order to map user information:

userDisplayNameAttribute, the attribute that will be used to specify Squore user display name.
userMailAttribute, the attribute that will be used to specify Squore user mail.
userDepartmentAttribute, the attribute that will be used to specify Squore user department.

Note that for Active Directory, OU, DC and other keywords are all uppercase.

Most directory servers are not configured to be case-sensitive so users authentication and synchronization won’t be. If your server is configured to be case-sensitive, users authentication and synchronization will be too.

It is highly recommended to use LDAPS instead of LDAP: ldaps://<hostname>:<port>/.

The java instance used by WildFly shall be able to check the certificate of the LDAP server.
If the LDAP certificate has not been signed by an "official" CA (self-signed certificate, or the company issued its own root CA), please refer to Import a certificate section.