LDAP Integration
About
To set up LDAP/Active Directory integration, go to System > LDAP Integration in the YSoft SafeQ management interface. You can also access the same configuration page through the Welcome to YSoft SafeQ 6 widget on the main screen.
You can set up the replication process in three modes:
Basic
Advanced
Expert
Once the LDAP connection is configured (see below), save the settings and run the synchronization using the Sync now button.
Basic Mode
Status tab
The Status tab contains only information about the last synchronization with the LDAP server (date, duration and result) and the count of added/updated/deleted users, cost centers and roles. If there is an error, the error will display here.
Settings tab
The Connection section is used to set up these essential settings for LDAP integration:
LDAP server type (AD, NDS, OpenLDAP) – use AD for Active Directory
URL of LDAP server – use a URL starting with LDAPS to use an encrypted connection (or LDAP for a plain connection)
Mode of LDAP server certificate check – defines how the LDAP server certificate is validated (applies to LDAPS protocol only)
LDAP bind method – method used for authentication and data security on the LDAP level
Searched LDAP subtree
The Mode of LDAP server certificate check setting is very important for security and may require additional non-trivial configuration, supported options are:
Windows certificate store – The LDAP server certificate is verified using the certification authorities set in Windows (a certificate import might be required). The certificate also has to match the value of URL of LDAP server.
Java truststore (with hostname check) – The certificate is verified using authorities in a dedicated Java truststore where the certificate authority needs to be installed. The certificate also has to match the value of URL of LDAP server.
Java truststore (without hostname check) – The certificate is also verified using the Java truststore but the certificate does not have to match any URL. This can be secure only if all certificate authorities in the truststore are controlled by trusted individuals exclusively, other authorities have to be removed.
No certificate check (insecure) – Any certificate is accepted for a TLS connection, this option is not recommended in production as it is insecure.
Please see Configuring secured connection to the LDAP server for more information. Here is an example of how to import CA certificate for the Java truststore methods.
java\bin\keytool.exe -server -import -alias YourCompanyCA -file YourCertificate.cer -keystore conf\ssl-truststore
The correct setting of LDAP bind method needs to be selected so that YSoft SafeQ can authenticate to the LDAP server configured, supported options are:
Simple bind – This is universal password-based authentication method simply passing the username and password in plain. From a security perspective, this is acceptable if an LDAPS connection is used since the entire communication is protected on the TLS level. LDAP servers might refuse to accept an unsecured LDAP connection using simple bind (e.g. based on registry settings of an Active Directory server). Select this method if an anonymous connection is to be used.
LDAPv3 SASL DIGEST-MD5 – An advanced authentication mechanism added in LDAP version 3 is used which does not expose plain-text passwords. In addition, if an unsecured LDAP connection is used, the data transferred will be integrity-protected and also encrypted if the LDAP server supports it. However, using LDAPS is still recommended for better security. This method can also be used together with LDAPS, when only the initial authentication might be affected (LDAP servers might refuse to accept connections with a doubled data protection mechanism). Note there are limitations when using this method, e.g. the IP address in the URL of LDAP server setting is not supported.
Please see Configuring secured connection to the LDAP server for more information and the full list of limitations.
The On-demand mode section allows you to enable Load users on demand. This type of replication mode is sometimes referred to as semi-online. When enabled, users are created only during job reception or when logging into the terminal.
Full and differential replication update only the users already registered within YSoft SafeQ 6.
Replication of Roles and Cost centers is unaffected.
When a user's card is removed from the LDAP, it is not synchronized to the database with the configuration option removeCardsInDiffLdapReplication .
In the Service account section, the LDAP user credentials can be specified if needed:
Anonymous – Anonymous access is used, no credentials are needed.
Authorized – The username and password for LDAP access need to be specified. The selected account has to have at least read access to reach the users and their attributes
Please ask your domain administrator for LDAP credentials. Specific username (principal) format might be required based on LDAP bind method selected. For LDAPv3 SASL DIGEST-MD5 setting, use only the username string with no prefix or suffix. Simple bind setting supports more formats, e.g. user@domain or distinguished name.
The Scheduling section gives you the possibility to schedule the run of replication. All settings are revealed after you check the Enable regular synchronizations checkbox. The options are:
Start full replication – You can select the days and times for full replication by clicking checkboxes.
Start differential replication – You can specify the hours or time interval from the last replication to starting differential replication. This type of replication will be started every day.
You have to restart the YSoft SafeQ Management Service services to apply these changes.
Test settings tab
The Test tab enables you to test the connection to the LDAP server. Please note that the settings have to be saved before the test can start. If the settings are correct, the test will return the first five users, cost centers and roles matching the entered settings and filters.
There is a summary table at the top if more than one LDAP connection (domain) is set. You can see if the domain settings are correct (all icons are green) or if something is set up wrongly (red icons). If the test returned fewer than five results, the icon is orange. This does not necessarily mean that the setting is wrong (there could be only three objects of that type in the LDAP) but a warning is raised so the administrator can check if, for example, the filter settings are correct.
You can list the returned items for each domain by clicking the domain name in the summary table.A summary table is not displayed if only one domain is set.
YSoft SafeQ 6 uses the LDAP Control Extension for Simple Paged Results Manipulation (RFC-2696) for limiting the fetched results. If this extension is not supported by the LDAP provider, using the paging will result in an Operation not supported error. In this case, please do not use paging in responses or the Test feature to avoid this extension usage.
Log tab
On the last tab called Log, you can see the information that was logged by the running LDAP replicator. This is a good place for troubleshooting if there is an issue with the replication process.
Advanced Mode
The Advanced mode adds an Advanced settings tab, which can be used to configure additional settings.
In the Replicator section, these settings can be configured:
Number of objects in search request – The maximum number of objects requested on one response page during a search. Set to -1 for an unlimited response.
List of binary attributes – A list of attributes that contain binary (non-string) values. Attributes are separated by commas. No spaces are allowed.
Maximum number of reconnection attempts – The maximum number of reconnection attempts when a connection with the LDAP fails during critical operations.
Delete imported objects in case of an error – The parameter affects only Full replication (not Differential replication). YSoft SafeQ Management Service launches the procedure for the deletion of outdated objects at the end of every full LDAP replication. For example, when a user is deleted on the Active Directory side, this user is deleted on the YSoft SafeQ Management Service side at the end of LDAP replication by the procedure for the deletion of outdated objects.
If this parameter is set to "disable" and there is an error during the replication (a connection error, unexpected values...), the procedure for deletion of outdated objects is not launched – this way it prevents the deletion of valid objects. It is strongly recommended to leave it with the default value "disable".
If this parameter is set to "enable" and any error during replication occurs, the procedure for deletion of outdated objects is launched – this may result in even valid objects being deleted during replication and users will be unable to authenticate. "Enable" should only be selected in special cases (for example, as a temporary workaround for issues where the LDAP contains incorrect values).
Terminate replication if an error occurs – Enable this feature to terminate replication if any error occurs while synchronizing user roles or cost centers (these objects are synchronized before any user account).
Remove cards from the database during differential replication
The Users schema section allows you to specify your own attributes that contain important user data such as an attribute containing aliases, login, cards numbers and other data:
Import users – If disabled, only cost centers and groups are imported – not users.
Attribute containing username – Do not include domains in usernames – Determines how the domain will be separated from the login:
Option none – The domain will not be separated from the login and the string will be used as it is
Option at sign or backslash (@, \) – The domain will be separated by (@, \)
Option dot (.) – The domain will be separated by (.)
Login | Alias | ||
Do not include domain in username | none | at sign or backslash (@, \) | dot (.) |
--- | john.doe | john | |
martin@example | --- | martin | --- |
example.cz\bailey | --- | bailey | example |
jfreeman.example | --- | --- | jfreeman |
john.doe.example.com | --- | --- | john |
Do not include domain in username
Attributes containing aliases – Attributes containing user aliases. Use commas to separate multiple attributes.
Attribute containing user first name
Attribute containing user surname
Attribute containing user email
Check username uniqueness – It is restricted to have two or more users with an identical login within a single tenant. If both this option and the option Overwrite user if already exists in database from Filters tab in Expert mode are enabled, then the original user created in the YSoft SafeQ management interface is deleted and the user from the Active Directory is created. Otherwise, user data received from the remote LDAP server is merged with an existing user created in the YSoft SafeQ management interface.
Attribute containing user role (membership) – The attribute containing the user role (membership). This multi-valued attribute is a collection of the Distinguished Names of all groups the user is a direct member of.
Attributes containing cards/PINs – Attributes containing cards and PINs. Use commas to separate multiple attributes. Multiple values can be replicated from this attribute.
Card number conversions – Used for the conversion of card numbers replicated from Directory services (AD, NDS, OpenLDAP). You can use The Card Conversion Tool to find a suitable conversion rule automatically or create the conversion rule manually. For more information on how to create a conversion rule, see the Card Number Conversion article.
Card separator – If multiple card numbers are stored in a single-value attribute in the LDAP, the card numbers are separated by the defined separator.
Note: The separator must not contain the apostrophe character (ASCII code 039).
Note: If the LDAP replicator is used in On-demand (semi-online) mode, this feature is not supported – only one card number may be stored in each single-value attribute.
Delete all the user’s cards when a user’s account is deactivated – When a user's account is deactivated in the LDAP, all the user's cards will be deleted in the database.
Note: If this option is enabled, the user’s cards that were added via the YSoft SafeQ management interface or card self-assignment will also be deleted from the database. Because this operation cannot be undone, the recommended value is disabled.
Note: Do not enable this option if multiple LDAP accounts are merged into one YSoft SafeQ 6 user account (that is, if multiple LDAP accounts have the same employeeID attribute). Deleting or disabling one of the accounts on the LDAP server causes all cards from the merged user account to be deleted from the YSoft SafeQ database.
Attribute containing PIN code – The attribute containing the PIN, which can be converted if the PIN code conversion value is defined. Only a single value is replicated from this attribute.
PIN code conversion – Used for the conversion of PIN codes replicated from Directory services (AD, NDS, OpenLDAP) to the database. The default system configuration of YSoft SafeQ 6 requires that PIN codes in the database are stored in the following format: PIN + MD5 hash of the PIN itself (PIN in LDAP is 1234, database value is PIN81dc9bdb52d04dc20036dbd8313ed055 which requires "MD5;LeftAppend(PIN)" conversion rule). For more information on how to create a conversion rule, see the Card Number Conversion article. The conversion must reflect the setting of the conversionPin attribute in System configuration.
The Groups schema section allows to configure:
Attribute containing group name
Attribute containing group description
Attribute containing group role (membership)
Load primary group
The Cost center schema section contains settings:
Keep users in their current cost center
Attribute containing cost center name
The Home directory schema section allows you to set:
Keep current users' home folders
Attribute containing home directory
The port on which the LDAP listens to YSoft SafeQ Management Service can be configured by the Port for internal LDAP Replicator communication (ldap-replicator-service-port) expert property.
Expert Mode
Expert mode unlocks the following tabs and features.
Domains tab
It is possible to configure replication for more LDAP domains, see separate Domains documentation.
Connection tab
Timeout – The number of milliseconds after which the connection to the LDAP server times out if there was no response. If several reconnection attempts are configured in the Replicator tab, LDAP replication will retry the connection after a delay specified by the ldapReconnectionDelay System settings configuration property.
The On demand mode has two expert options available on the System > Configuration page:
Number of threads (property ldap-replicator-online-mode-threads) – The number of concurrently running threads. The number of threads should not exceed the number of LDAP connections. The database should have a sufficient number of open connections.
Maximum response time (property ldap-replicator-online-mode-timeout) – The maximum response time in seconds. Requests that take longer than the given time are prematurely canceled.
Expert settings tab
Expert mode adds the Expert settings tab, which contains a few more configuration sections.
The User unique mapping section allows you to configure options and conversion for user unique mapping, an option for extracting external ID and several options for the user's organizational unit mapping.
Options for unique mapping of users – Options for user unique mapping:
ID-GUID – for mapping a user to the GUID
ID-[attribute-name] – for mapping a user to an attribute
[name-of-numeric-attribute] – for ID equivalency mapping
Conversion for unique mapping of users – Turn on the conversion of user unique mapping Options for user unique mapping, e.g., for ”GUID” (=value ”ID-GUID”) is converted to ”objectGUID” (used for Active Directory). Usually, for the existing installations, the value Enable should be set for backward configuration compatibility.
For new installations, it is recommended that you use Disable and the specified item Options for user unique mapping properly, e.g., ” Options for user unique mapping = ID-objectGUID” for Active Directory. Typically, Disable is used for non-AD servers.
The External ID extraction section contains only Option for extracting external ID – An option for extracting ext-id from the attribute Options for user unique mapping. Matching parts are used for the output. An unmatching input is not processed. For example: regex (d+)-adm-(d+)|adm-(d+) for inputs 12345-adm-6789, 123-adm-456789, adm-123456789, 123456789 will have same output 12345678.
In the User's organizational unit mapping section, these settings can be configured:
Options for user cost center mapping
DN:[attribute-name] – Cost centers are searched by a query in the LDAP, the cost center is assigned according to LDAP setting (by DN prefix). [attribute-name] determines the user ext-id. Example: DN:GUID
NUMBER:[attribute-name] – Cost center creation during user replication. The number is stored in the user’s [attribute-name]. The name is created as ”OU-”[attribute-name], example: NUMBER:department
NAME:[attribute-name] – Cost center creation during user replication. The name is stored in the user’s [attribute-name]. The number is identical to the ID (initialized by sequence). Example: NAME:department
NN1:[attribute-name-with-number]:[attribute-name-with-name] Cost center creation during user replication. [attribute-name-with-number] contains the cost center number and [attribute-name-with-name] contains its name. Example: NN1: department:company
NN2:[attribute-name]:[groups-order]:[pattern] – Cost center creation during user replication. The user’s [attribute-name] must include content that matches reg-ex [pattern]. The value must contain at least two reg-ex groups: the first for the OU name, the second for the OU number. [groups-order] is string ”name,number”, or ”number,name” depending on the mapping order of regex-groups to the OU number and the OU name in [pattern]. Example: NN2: department:number,name:([^:]*):(.*)
Conversion of user cost center mapping - Turn on the conversion of the user’s cost center unit mapping (Options for user’s cost center mapping). For example, ”GUID” (=value ”DN:GUID”) is converted to ”objectGUID” (used for Active Directory). Usually for existing installations, set this value to Enable for backward configuration compatibility. For new installations, it is recommended that you use Disable and the specified item Options for user’s cost center mapping, for example, ”Options for user’s cost center mapping = DN:objectGUID” for Active Directory. Typically, Disable is used for non-AD servers.
Map cost center only when value exists – When enabled, the user’s cost center information is updated only if the cost center exists. If disabled, the user is saved without cost center information.
The User's groups mapping section contains these settings:
Attribute containing unique identifier for groups – The name of the LDAP attribute containing the unique identifier for groups.
Bind user to ancestor groups – The option that specifies to map the user not just to its superior roles but also to roles superior to these roles.
In the Filters section, you can specify additional filters for users, groups or cost center searching and some other filters according to your needs:
Additional filter for user searches – You can use this filter if the standard built-in filter includes unwanted objects in the search result. For example, a filter for users that have not been disabled (&(objectCategory=Person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
Additional filter for group searches – Use this filter if the standard built-in filter includes unwanted objects in the search result.
Additional filter for cost center searches – You can use this filter if the standard built-in filter includes unwanted objects in the search result. This setting is, in effect, only when Mapping -> Options for user’s cost center mapping is set to DN:keyword (for example, DN:GUID). With other options (like NAME, NUMBER,...), this option is not used.
Ignore distinguished name when searching for users – Domain name branches to ignore during searches of users. Separate multiple values with a pipe.
Ignore distinguished name when searching for groups – Domain name branches to ignore during searches of users. Separate multiple values with a pipe.
Ignore distinguished name when searching for cost centers – Domain name branches to ignore during searches of users. Separate multiple values with a pipe.
Overwrite user if already exists in database – Enable this option if you have created internal users prior to synchronization from the LDAP. If both this option and the option Check username uniqueness from Users schema tab in Advanced mode are enabled, then the original user created in the YSoft SafeQ management interface is deleted and the user from the Active Directory is created. Otherwise, user data received from the remote LDAP server is merged with the existing user created in the YSoft SafeQ management interface.
Merge automatically generated accounts in YSoft SafeQ 6 database – If multiple user accounts are automatically generated in the YSoft SafeQ database, they can be automatically merged once accounts are created in the LDAP with aliases that are the same as the generated accounts. This should be enabled only when using the anonymous print feature.
Running the Replication
Once you are finished with settings, you can save the LDAP replicator settings by clicking the Save changes button. Also, if you want to run the replication immediately, you can do so by clicking the Sync now button.
Replication is always run by the cluster node designated by the ldapReplicatorClusterNodeId configuration option. The configuration option can be set to the ID of the cluster node that should run the replication. The default value is '-1', which means the replication is run by the first cluster node (the node with the lowest ID among all nodes in the cluster, running or not). LDAP replication is not executed if the designated node is not operational.
LDAP password encryption
Integration with LDAP uses encryption configuration defined in <safeq_folder>/Management/conf/safeq.properties, meaning whenever the following configuration property is present, the encryption is enabled.
dataProtection.pathToKey = <path to key file>Note that <path to key file> should be absolute file path, eg. c:\encryption_secure_location\encryption.key
For information about creation and management of dataProtection attributes, as well as full list of supported configuration options, please refer to the Enhanced Password Protection.