LDAP Sync Tool Manual
Description
The regify LDAP sync tool allows you to synchronize your local LDAP repositories against a given regify provider (sub provider). This is done by doing an LDAP search followed by synchronizing this search against your regify provider.
Operation detail
This is the operation in detail:
-
Connect to the LDAP server
-
Get a list of all users that have to be synchronized (execute LDAP search)
-
Disconnect LDAP server
-
Connect to the regify provider
-
Get a list of all registered users in regify provider (execute provider search)
-
Compare the two lists
-
If a user only exists in LDAP → Create new user in regify provider
-
If a user only exists in provider → Delete the user in regify provider-url (optional)
-
If a user exists in both systems → Do nothing
-
-
Disconnect regify provider
Account identification
In general, the tool uses the e-mail address to identify users. Thus, neither name nor userid are updated as long as the users regify account exists. Therefore, if someone got renamed in LDAP (eg by marriage), please remove him from the regify provider and the account will be re-created during the next run.
If an LDAP account owns multiple e-mail addresses, all of them are assigned to the same regify account. In general, a regify account is able to handle up to 5 e-mail addresses per user.
Installation instructions
To install the regify LDAP sync tool, simply copy the whole content of the provided ZIP file to your dedicated destination directory. After copied, you can directly run the tool using the command line or as an automated task (Windows Task Scheduler).
Usage
The regify LDAP sync tool is configured using a given configuration file. This file is an INI style file containing all relevant data. You can find an empty template config_template.ini in your installation folder.
Configuration Options
The file only has one user configurable group [configuration]. If there are other groups, they are used internally by the regify LDAP sync tool and should not be edited or deleted.
These are the available [configuration] options inside of this file:
Field Name | Description | Example | Mode [1] | ||
---|---|---|---|---|---|
provider |
This is the URL of the regify provider to synchronize with. |
https://portal.regify.com |
|||
username |
The user for regify provider SDK login. Please make sure that the needed provider SDK SUPER-USER permissions are set for this regify account. |
user@provider.com |
- |
||
password |
The password of the user. |
- |
- |
||
ldap_server |
The IP address or FQDN of the LDAP server to use for synchronization. |
192.168.123.123 |
- |
||
ldap_port |
The port of the LDAP server listening. |
389 |
- |
||
ldap_username |
The user to login to the LDAP system. This is an optional value and the tool only needs read permissions. |
- |
|||
ldap_password |
The password for the login to the LDAP system. This is an optional value. |
- |
|||
ldap_base |
Points to the distinguished name of the entry from which to start the search. |
ou=Users,dc=example,dc=com |
- |
||
ldap_filter |
The search filter. Simple filters take the form of strings: attribute name=attribute value. For more complex filters, see addendum examples. |
objectClass=inetOrgPerson |
- |
||
ldap_mode |
The LDAP mode to access the LDAP server.
|
1 |
- |
||
ldap_fld_title |
The optional LDAP field name for getting the title like “Mr” or “Ms”. Keep empty to ignore. |
title |
CI |
||
ldap_fld_lastname |
The LDAP field name for getting the last name.
|
sn |
CI |
||
ldap_fld_firstname |
The LDAP field name for getting the first name.
|
givenName |
CI |
||
ldap_fld_email |
The LDAP field name for getting the users e-mail addresses. If the field contains multiple e-mail addresses, it will add as much as the regify provider allows (default is 5). The entries are created in the order the LDAP query returned them (top to bottom). If there are e-mail addresses you like to exclude, please have a look at the filter_mail parameter. This field is processing addresses in the following format:
It ignores everything else by skipping entries like X400 names or invalid e-mail addresses.
|
proxyAddresses |
CI |
||
ldap_fld_address1 |
The optional LDAP field name for getting address information. |
streetAddress |
C |
||
ldap_fld_address2 |
The optional LDAP field name for getting more address information. |
postOfficeBox |
C |
||
ldap_fld_zip |
The optional LDAP field name for getting the ZIP of the users city. |
postalCode |
C |
||
ldap_fld_city |
The optional LDAP field name for getting the name of the users city. |
city |
C |
||
ldap_fld_ioc |
The users country as 3 letter IOC code (reference: https://en.wikipedia.org/wiki/List_of_IOC_country_codes). GER=Germany, LUX=Luxembourg, FRA=France, GBR=GreatBritain |
“GER” |
C |
||
ldap_fld_company |
The optional LDAP field name for getting the users company name. |
company |
CI |
||
ldap_fld_mobile |
The optional LDAP field name for getting the users mobile phone number. Please ensure format +49 1234 56789 incl. Country code. |
mobile |
CI |
||
ldap_fld_salesid |
The optional LDAP field name for getting some value to be stored in the salesId field (no specific usage, mainly invormational character). |
C |
|||
ldap_fld_group |
for future use, keep empty |
C |
|||
user_flags |
Defines the user-flags for the new user (only if sync_mode = create). Usual flags are: „N“ = suppress registration notification e-mail |
NRF |
C |
||
user_prof_until |
The date until that the user is getting regimail professional (if the current date is in the past, he is having regimail private). Leave empty to get providers default. The date must be in the following format: YYYY-MM-DD |
2038-01-01 |
C |
||
filter_mail |
Optional list of domains to filter e-mail addresses gathered from ldap_fld_mail. If empty, all e-mail addresses are taken. If you set a list of domains, only e-mail addresses of this domain will be used (whitelist). Please divide multiple domains using blank. |
regify.com regify.de |
CI |
||
report_folder |
Defines the folder to write all syncronization reports into. The tool will create a new file for every run. Usually, every successful user creation or deletion triggers one line. Errors might trigger multiple lines of information. The log is closed by some statistical information. |
c:\ldap_reports\ |
- |
||
sync_mode |
Missing or “create” = Create users directly “invite” = Send users an invitation. In invitation mode, the language for the invitations and the invited user is determined by the (sub)provider default language (web administration → manage sub-provider). |
invite |
- |
||
sync_option |
missing or “full” = Full sync Please read “Safety instructions” chapter for more information on this! |
full |
- |
||
lib_path |
Optional information about the location of the LDAP libraries needed by the tool. |
c:\program files\ldap_sync |
- |
||
max_delete |
This number defines how many deletions the tool is doing per run. If you set to 0, it means “unlimited”. This is only having any effect if sync_option is “full”. Please read “Safety instructions” chapter for more information on this! |
2 |
- |
Using fixed values
If you like to use a fixed value instead of a value from an LDAP attribute, you can force the regify LDAP sync tool to use the config as value by covering it in double quotes (ASCII 32). You can define such an ldap_fld_* field like this:
ldap_fld_company = "Bikini Bottom Inc."
ldap_fld_ioc = "LUX"
This will force the tool to use Bikini Bottom Inc. (without the quotes) and LUX as value and it does not try to find an LDAP field with that name. This is useful in cases where all users should get the same value and, maybe, there is no adequate LDAP attribute available (like for IOC country code).
Problems with special characters and umlauts
If you like to add such characters to the configuration file, you need to ensure that your text editor is adding the correct encoding headers (unicode, utf8 etc) as a BOM (Byte Order Mark) on top of the configuration file. For editors like PSPad (
), Notepad2 (UTF8 Signature) or Notepad++ (UTF-8-BOM), this is an option.Command line Options
If everything is working as expected, the most basic call is the name of the executable followed by the -i switch and the file name of the configuration file. If no parameter is given, the tool outputs some version information and basic usage hints.
These are the available command line options:
Switch | Description |
---|---|
-i |
Define the configuration file to use. This is a mandatory parameter. |
-s |
Runs the simulation mode. In this case, all the calls to the regify provider are not really executed. Instead, all such actions are printed on the console window only. This allows you to test your settings and functionality. Do not mix with -f. If this switch is set, no report file is generated (report_folder). |
-f |
Runs Filter-Test only. In this mode, the tool simply prints all LDAP search results to the console window. Use this switch to check and tweak your LDAP filter configuration. Do not mix with -s. If this switch is set, no report file is generated (report_folder). |
-v |
Starts verbose debug mode, especially to detect connectivity or API issues with regify support. This only works together with the -o switch. Please do not use this permanently, as the logfiles become huge quickly. |
-o |
Set the file (and path) for debug output. It only writes something in here if -v is used. |
Example calls
Simple standard call:
regify_ldap.exe -i config.ini
Standard call with debug logging:
regify_ldap.exe -v -o ”c:\temp\ldap.log” -i config.ini
Run an LDAP filter test only:
regify_ldap.exe -f -i config.ini
Run a save simulation:
regify_ldap.exe -s -i config.ini
Safety instructions
If the tool does not get a valid list from LDAP, and the sync_mode is “full”, all users in the regify provider, who are not in the LDAP search result, will get deleted with no fallback option! |
To avoid any accidential data loss, please respect the following usage rules:
-
Make sure to run every configuration with simulation mode first (-s switch). Never run without testing!
-
If the simulation is used, please examine the results carefully!
-
To enhance security, the tool only does a limited number of deletions per run (max_delete configuration value, by default this is 2). This avoids huge data loss if LDAP search does not return all users.
-
Do not set max_delete configuration value to 0 (unlimited deletions) unless you really want the tool to be able to delete a huge number of accounts in one run.
-
Due to the max_delete configuration value, it is important to check the system immediately if users start to complain about missing accounts.
Windows SysLog
On Windows, the regify LDAP sync tool logs successful entries and deletions and several error states to the Windows SysLog (Windows-Protocols/Applications).
The used EventID’s are:
-
0 - Success
-
1 - User related problem
-
2 - LDAP related problem
-
3 - regify Provider related problem
-
99 - Generic critical problem (like wrong config)
The description contains additional information. If you get any EventID’s > 1, we suggest to check the generated logs directly. EventID 1 is not a critical issue in all cases. It might be, that the user simply already has a regify account somewhere else or the e-mail address is invalid etc. You need to check the description for more details.
Addendum
LDAP Search Filters
The LDAP search filter grammar is specified in RFC 2254 and 2251. The grammar uses ABNF notation.
filter = " ( " filtercomp " ) "
filtercomp = and / or /not /item
and = "&" filterlist
filterlist = 1*filter
or = "|" filterlist
filterlist = 1*filter
not = "!" filterlist
filterlist = 1*filter
item = simple/present/substring/extensible
simple = attr filtertype value
attr = name | name;binary
filtertype = equal/approx/greater/less
value = data valid for the attribute's syntax
equal = "="
approx = "~="
greater = ">="
less = "<="
present = attr "=*"
attr = name | name;binary
substing = attr "=" [initial] any [final]
attr = name | name;binary
initial = value
any = "*" *(value "*")
final = value
extensible = attr [":dn"] [":" matchingrule] ":="value
/[":dn] ":" matchingrule ":=" value
/matchingrule = name | OID
For additional options for the attr option, see Section 4.1.5 of RFC 2251.
For additional information on the value option, see Section 4.1.6 of RFC 2251.
eDirectory does not support LDAP approximate (~=) matching or extensible matching rules. |
You cannot use the dn attribute in an LDAP search filter. Filters using either distinguishedName= or dn= in the filter syntax will not function correctly with LDAP. |
LDAP Filter Operators
Operator | Description |
---|---|
= |
Used for presence and equality matching. To test if an attribute exists in the directory, use (attributename=*). All entries that have the specified attribute will be returned. To test for equality, use (attributename=value). All entries that have attributename=value are returned. For example, (cn=Kim Smith) would return entries with Kim Smith as the common name attribute. (cn=*) would return all entries that contained a cn attribute. The = operator can also be used with wildcards to find a substring, (cn=*ary) would return mary, hillary, and gary. |
>= |
Used to return attributes that are greater than or equal to the specified value. For this to work, the syntax type of the attribute must have defined a mechanism to make this comparison. For example, (cn>=Kim Smith) would return all entries from Kim Smith to Z |
⇐ |
Used to return attributes that are less than or equal to the specified value. For this to work, the syntax type of the attribute must have defined a mechanism to make this comparison. For example, (cn⇐Kim Smith) would return all entries from A to Kim Smith. |
~= |
Used for approximate matching. The algorithm used for approximate matching varies with different LDAP implementations. |
The following boolean operators can be combined with the standard operators to form more complex filters. Note that boolean operator syntax is used different in search filters than in the C and Java programming languages, but the concepts are the same.
LDAP Filter Boolean Operators
Boolean Operators | Description |
---|---|
& |
And. For example, (&(cn=Kim Smith) (telephonenumber=555-5555)) would return entries with common name of Kim Smith and a telephone number of 555-5555. |
| |
Or. For example, (|(cn=Kim Smith)(cn=Kimberly Smith)) would return entries with common name Kim Smith or Kimberly Smith. |
! |
Not. For example, (!(cn=Kim Smith)) would return entries with any cn other than Kim Smith. Note that the ! operator is unary. |
LDAP Filter Examples:
Filter | Description |
---|---|
(cn = Kim Smith) |
Returns entries with a common name of Kim Smith. |
(&(cn=Kim Smith)(telephonenumber=555*)(emailaddress=*acme.com)) |
Returns entries with a common name of Kim Smith, a telephone number that starts with 555, and an e-mail address that ends in acme.com |
(!(cn = Chris Jones)) |
Returns entries that do not have a common name of Chris Jones. |
(&(objectClass=inetOrgPerson) (| (sn=Smith) (cn=Chris S*))) |
Returns entries that are of type inetOrgPerson with a surname of Smith or a common name beginning with Chris S. |
Document History
V1.0 Jan 2015
Initial version.
V1.1 Nov 2016
Added LDAP fields for title, company, address1, address2, zip, city, mobile, salesid, ioc and prof_until.
Added fixed value option (“value” in double quotes).
Enhanced logging functionality.
Added retry for LDAP connection.
Added a lot of fixes regarding ActiveDirectory/LDAP mapping (allow e-mail addresses starting with “smtp:”, filter X400 style addresses etc).
Added enhanced logging functionality.
V1.2 Jan 2017
Added filter_mail parameter.
Added SysLog logging for several events (Windows only).
V1.3 Nov 2017
Internal LDAP library switched to use builtin Windows LDAP library (on Windows).
Now using paged LDAP search with page size of 50 entries per page.
V1.4 Aug 2022
New config parameter “ldap_mode”, to allow switching between simple search and paged search mode (Lotus Notes Domino compatibility).