ldap-notify - LDAP Password/Login Expiration Notification Tool

Usage: ldap-notify [OPTION]... -c config_file.conf

ldap-notify searches users in an LDAP directory whose login or password expires in a certain number of days. These users are notified with a customizable email. The time intervals for the notifications and the email templates can be freely defined. By using a custom LDAP attribute the last notification is stored in the directory such that users are only notified once per rule. Moreover, this mechanism allows running the tool (e.g. via cron) on multiple machine with a certain time delta in order to implement high availabiliy.

-h, --help show this help

-c, --conf config-file mandatory parameter: the config file name

-k ignore SSL/TLS certificates

--dry do not send emails or modify anything in ldap

--test test-address send all mails to the given address

--restrict DN;CN;... restrict notifications to these semicolon separated user DNs or CNs

--time timestamp simulate current UTC time (format: 20141031162633Z)

-v, --verbose enable verbose logging

-d, --debug enable debug logging

--print-conf print the used configuration to console and exit

The behaviour of ldap-notify is defined via a config-file. The parameters above will override the options in the configuration file.

The configuration file given by the mandatory -c or --conf parameter uses the common INI file format. This means that it consists of sections with key/values pairs in the following format:

[section_name]
attribute=value
second_attribute = multi
    line
    value
    
# comment

The multi-line value is useful for long lists like in the restrict_to_users value.

The default configuration is the following (call ldap-notify with the --print-conf parameter to print it):

[common]
server = ldap:https://localhost
bind_dn =
bind_password =
bind_password_base64 =
base_dn =
subtree_search = false 
starttls = false
ignore_cert = false
expiry_attribute = passwordExpirationTime
notify_attribute = pwmNotify
dry = false
restrict_to_users =
user_objectclass = person
object = password
objects =

[smtp]
server =
ssl = false
starttls = false
user =
password =
password_base64 =

[admin]
from_address = root@<HOSTNAME>
to_address = admin@<HOSTNAME>
from_text = $Object Expiry Notification
subject = $Object Expiry Notification Report
text_template = <LDAP_NOTIFY_DIR>/templates/admin.tmpl.txt

[test]
enabled = false
to_address = root@<HOSTNAME>

The configuration options have the following meaning:

The DN list of base_dn is separated by semi-colons, spaces or newlines. An empty base_dn implies substree_search = true and means to start the search at the dictionary root.

The DN or CN list of `restrict_to_users is separated by semi-colons, spaces or newlines. A non-trivial example with a multi-line value is the following:

restrict_to_user = cn=alice,ou=users,dc=localhost
	cn=bob,ou=users,dc=localhost
	root;admin;operations

The object and objects values are only used in templates in order to allow unified templates for e.g. password and login configuration.

The object string in the common section can be used in the templates such that they work for password and login notification emails.

An arbitrary number of rules can be defined in the configuration file. The rules are named according to their number of days before an expiration date when the rule applies. E.g. a 30 day rule is called "30".

The default values of a 30 day rule:

[30]
from_address = *ADMIN FROM ADRESS*
from_text = *ADMIN FROM TEXT*
subject = $Object will expire soon
text_template = <LDAP_NOTIFY_DIR>/templates/notify.tmpl.txt
html_template =

A quite minimal rules configuration with only one template (the default notify.tmpl.txt), but customized subject lines looks like this:

[30]
subject = $weeks_left weeks left

[7]
subject = $days_left days left

[1]
subject = Tomorrow

The rule options have the following meaning:

The subject of the notification emails will be interpolated with the same variables as in the email template itself (cf. below).

By default, HTML mail templates are disabled. Next to the default text template there is also an example notify.tmpl.html. By assigning a template to the html_template option, HTML mail templates will be enabled.

During test of the script it is highly suggested to use the --test, the --dry and --restrict options or the respective options in the configuration file.

These three options are orthogonal and can be combined depending on the test case at hand:

• --test test-address: all emails that are sent by ldap-notify are sent to the test address, not the actual addresses of the matching users. Moreover, no LDAP modifications are done.
• --dry: no emails are sent at all, not even to a test user. Moreover, no LDAP modifications are done.
• --restrict DNs;CNs;...: all users are processed as in normal operation, but emails are only sent to the admin (for the admin report) and the given users as DNs or CNs. Moreover, no LDAP modifications are done to users not in this list.

For debugging and testing it is useful to use verbose and debug output:

• -v: show log output on level ERROR, WARN, INFO. Normally, INFO log output is supressed.
• -d: show log output on level ERROR, WARN, INFO and DEBUG. Normally, INFO and DEBUG log output is supressed.

The debug parameter -d can be passed multiple times in order to increase the debug level even further.

Email templates, email subjects and email from strings for rules are interpolated with a number of variables.

In the case of user notification emails the following variables are interpolated:

The object and objects variables are defined by the very same options in the configuration. If objects is empty, a single s character is appended to the object value.

In the case of admin report emails the following variables are interpolated::

The object and objects variables are defined by the very same options in the configuration. If objects is empty, a single s character is appended to the object value.

The ..._length variables count the number of lines in the respective ..._users variables. These can be used to shows counters (e.g. of failed notifications) at the very top of the admin report.

The search algorithm in `ldap-notify looks for users of each rule which satisfy the following conditions:

• have an expiration timestamp within the number of days in the rule,
• do not match with other rules,
• are not disabled,
• have not received the same notification before.

In addition in case of any of the following conditions only the admin is notified via the admin report, no user notification is sent out:

• have an email address,
• have grace login available.

The algorithm stores the last sent notification and a timestamp in the notify_attribute (defined in the common config section). The value has the following format:

20140116111356Z:30

It tells the algorithm that this user was notified at the given timestamp with a 30 days rule.

Assume that three rules are defined: 30, 7, 1 and passwordExpirationTime is used as the expiry attribute. Then three independent LDAP searches are performed, each of them with a filter of the following shape:

(& (objectClass=person)
   (!(loginDisabled=true))
   (& (passwordExpirationTime>=20141112173529Z)
      (!(passwordExpirationTime>=20141116173529Z))
      (!(loginGraceRemaining=0))
   )
)

The timestamps used are:

• 1 days: passwordExpirationTime >= *NOW* and passwordExpirationTime < *24 HOURS FROM NOW*
• 7 days: passwordExpirationTime >= *24 HOURS FROM NOW* and passwordExpirationTime < *7 DAYS FROM NOW*
• 30 days: passwordExpirationTime >= *7* and passwordExpirationTime < *30 DAYS FROM NOW*.

To detect that the same notification was sent before, but to cope with old notify attribute values at the same time, the notify attribute is read, e.g. 20130116111356Z:30. This notify attribute timestamp is considered old if

• expirationTime - last_notify >= 30 days
• or the current applied rule (e.g. 7) is smaller than the last notified rule: 7 < 30.

If neither condition matches, the notifiy attribute is current and the user is skipped. If at least one condition matches, the user is notified and a new notify attribute is written.

Users are notified only once for each rule. This allows to launch ldap-notify on multiple servers, with a time delta to avoid overlap and race conditions. If the first server fails, the second launch on the second server will notice this and send the notifications on behalf of the first instance.

Moreover, ldap-notify will handle SMTP errors gracefully: if the SMTP connection fails, the notification attribute is not updated.

If the notification attribute cannot be parsed (i.e. its format is invalid), the notification attribute is deleted before processing the user.

ldap-notify is written in Python. The ldap-notify has no dependencies other than python-ldap. After cloning the Github repository with the source code, some more dependencies are needed for development which can be installed with pip:

virtualevn ../env
. ../env/bin/activate
pip install -r requirements.txt

After installation the dependencies, the unit tests can be run to verify that everything works as expected:

nosetests --rednose -v ldap_notify/tests

Everything should be green.

To launch the ldap-notify itself, do the following:

python -mldap_notify.main -c login.conf

Make sure that login.conf in the current directory is valid.

To update the man page from README.md, install md2manand run:

grep -v 'Build Status' README.md | md2man-roff > man5/ldap-notify.5
man -M . ldap-notify

Dr. Stefan Schimanski [email protected]

• https://github.com/sttts/ldap-notify
• https://build.opensuse.org/package/show/home:sttts/ldap-notify