Documentation and help portal

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.

  • 0 = Simple query mode (slower, Lotus Notes Domino)

  • 1 = Paged query mode (faster, Exchange, OpenLDAP)

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.

This is mandatory!

sn

CI

ldap_fld_firstname

The LDAP field name for getting the first name.

This is mandatory!

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:

  • name@domain.com

  • smtp:name@domain.com

It ignores everything else by skipping entries like X400 names or invalid e-mail addresses.

This is mandatory!

mail

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
„R“ = suppress recipience notification e-mail
„F“ = suppress reminder notification e-mail
„X“ = select extended portal-view
„O“ = enable regibox for the user by default
„H“ = do not store subject in provider [2]

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
“nodelete” = Do not delete users on provider

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

-

1

Supported sync_mode: C=create, I=invite
If you try to set a value marked with C only, but using sync_mode = invite, the value will be ignored.

2

Only having effect with regify provider V4.0.10 or newer

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 (settings  add Ident Bytes for UTF-8), 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).