regify documentations

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).
Optional, get all assigned email addresses (for sync_mode = create+update).
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.
- In sync_mode = create+update, the below logic is applied.
Disconnect regify provider.

The create+update sync_mode supports various scenarios, where a and b are email addresses:

Case	Provider	LDAP	Action
1	a(m)	a	skip
2	-	a	Create or invite new user a
3	a(m)	-	Remove user a (only if sync_option = full)
4	a(m)	a b	Add address b to user a
5	a(m) b	a b	skip
6	a(m) b	b a	skip
7	a(m) b	a	Remove address b from user a
8	a(m) b	b	Switch main address of user to be b, remove address a

Case

Provider

LDAP

Action

a(m)

skip

Create or invite new user a

a(m)

Remove user a (only if sync_option = full)

a(m)

a b

Add address b to user a

a(m) b

a b

skip

a(m) b

b a

skip

a(m) b

Remove address b from user a

a(m) b

Switch main address of user to be b, remove address a

Note: (m) means, this is the main address in regify provider.

Account identification

In general, the tool uses the email 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 email addresses, all of them are assigned to the same regify account. In general, a regify account is able to handle up to 5 email 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)

ldap_fld_title

The optional LDAP field name for getting the title like “Mr” or “Ms”. Keep empty to ignore.

title

ldap_fld_lastname

The LDAP field name for getting the last name.

This is mandatory!

ldap_fld_firstname

The LDAP field name for getting the first name.

This is mandatory!

givenName

ldap_fld_email

The LDAP field name for getting the users email addresses. If the field contains multiple email 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).

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 email addresses.

This is mandatory!

mail

proxyAddresses

ldap_fld_address1

The optional LDAP field name for getting address information.

streetAddress

ldap_fld_address2

The optional LDAP field name for getting more address information.

postOfficeBox

ldap_fld_zip

The optional LDAP field name for getting the ZIP of the users city.

postalCode

ldap_fld_city

The optional LDAP field name for getting the name of the users city.

city

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”

ldap_fld_company

The optional LDAP field name for getting the users company name.

company

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

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).

ldap_fld_group

for future use, keep empty

user_flags

Defines the user-flags for the new user (only if sync_mode = create or sync_mode = create+update). Usual flags are:

N = suppress registration notification -mail
R = suppress recipience notification email
F = suppress reminder notification -mail
X = select extended portal-view
O = enable regibox for the user by default
H = do not store subject in provider

NRF

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

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

create = Create missing users directly and activate the account. This does not touch existing regify accounts.

create+update = Like create, but also update existing regify accounts with any changed email addresses. See Operation detail for the applied logic and scenarios.

invite = Like create, but send missing users an invitation (default). The accounts gets activated only, if the user accepts the invitation by clicking the link in his invitation email.

If you change to create+update mode after the system ran in other modes for a while: Note that email addresses, which are not in LDAP but were later added by users or admins in the provider, might get removed. Ensure that all the email addresses your users need are in LDAP!

In invite mode, the language for the invitations and the invited user is determined by the (sub)provider default language (web administration → manage sub-provider).

create+update

sync_option

full or missing = Full sync

nodelete = Do not delete user accounts on provider

Please read Safety instructions chapter for more information on this!

full

delete_only

If this parameter is not empty, only email addresses and accounts belonging to the listed domains may be deleted from your regify provider. The deletion of email addresses or accounts that do not match this list is prevented.

Please separate multiple domains with spaces.

This is useful if users in your regify provider also use email addresses outside your company (e.g. private addresses or addresses of external individuals such as lawyers, tax advisors, etc.). If these are not listed in your LDAP directory, they would normally be deleted if sync_option is set to full or is undefined. It is therefore advisable to restrict the deletion process to the domains of your company or organization only.

Please note that this is not affecting the creation of regify accounts or the adding of email addresses from LDAP to existing accounts. It is only used for deletions!

regify.com regify.de

lib_path

Optional information about the location of the LDAP libraries needed by the tool (Wldap32.dll). Leave empty to use the system default.

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!

[statistic] section

Here, the app stores two values: The date and time of the last successful LDAP query and the number of hits in the last successful LDAP query.

If you need to override the safety stop after receiving less than 70% of the last query, just set the last_ldap_count to 0 to let the tool ignore this value on the next run.

¹	This parameter is supported in the following sync_mode: C=create or create+update mode, I=invite mode. Example: If you try to set a value marked with C only, but using sync_mode = invite, the value will be ignored.

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. 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.

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 full list from LDAP, and the sync_option is full or missing, all users in the regify provider, who are not in the LDAP search result, will get deleted with no fallback option! Please also check delete_only option to restrict reletions to specified domains.

To avoid any accidential data loss, please respect the following usage rules:

Make sure to run every new or changed configuration in 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.

Beside the max_delete parameter, there are two built-in safety mechanisms:

If the LDAP query returns no results, synchronization is stopped and no accounts are deleted.
If the LDAP query returns fewer than 70% of the results from the last successful search, synchronization is stopped and no accounts are deleted.

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 email 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.

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.

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 email 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.
(&(o=acme)(objectclass=Country)(!(\|(c=spain)(c=us))))	Returns entries that are of type Country from the organization Acme, that are not countries spain or us.

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 email 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.

(&(o=acme)(objectclass=Country)(!(|(c=spain)(c=us))))

Returns entries that are of type Country from the organization Acme, that are not countries spain or us.

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 email 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).

V1.5 Sept 2026

New config value create+update for sync_mode parameter (allows updating email addresses).

Config parameter filter_mail was renamed to be delete_only. Its functionality is now more easy to understand. It also got some more meaning if sync_mode = create+update.

Tool denies syncronization, if sync_option = full and previous successfull LDAP query had > 10 hits and current LDAP query returned less than 70% of previous query.

The documentation was updated and enhanced. Also lining out the different sync situations in chapter Operation detail.