1. Architecture
  2. Models
  3. Secure Enrollment
    1. Objectives
    2. Process
  4. Bulk Enrollment
    1. Operational and security considerations
    2. Prerequisites
    3. Process
    4. Using oath-ldap-tool


OATH-LDAP system architecture based on OpenLDAP
The OpenLDAP server implementation (see also slapd(8)
slapd backend also useable as overlay which sends some LDAP requests to an external demon via Unix domain socket (see also slapd-sock(5))
OTP validator
The component validating the OTP values which runs on a slapd provider. It is the only component which has access to clear-text user password and OATH shared secret and updates the HOTP counter. Does not need any IP network access.
bind proxy
This component runs on a slapd consumers, which are by design read-only, and relays LDAP simple bind requests to one of several slapd providers.
web browser
Normal web browser used by the OTP admin to access the enrollment web app.
enrollment web app
A simple web application for resetting OATH token device entries to start enrollment
enrollment client
A hardened device where you plug in the OATH hardware token (e.g. Yubikey) to be initialized. Especially users shall not enter their normal password at this device.
LDAP client
Any LDAP client software which checks user's password and OTP by sending a LDAP simple bind request.


OATH-LDAP entity relationships

Secure Enrollment



OATH-LDAP enrollment process - component view

Bulk Enrollment Process

In some situations it may be required to ship pre-keyed token devices, e.g. during an initial rollout.

Operational and security considerations



Steps done with oath-ldap-tool either sequentially on one system or as a pipeline with three systems:

Using oath-ldap-tool

The relevant sub-commands can be invoked with argument -c or --continue for continuous operation interactively running until you hit Ctrl+C key combination.

For all commands below replace "..." with the following command-line arguments:

    --continue --ca-certs /path/to/trusted-cacerts.pem --ldap-url ldaps:/// --admin-dn 

Example for Æ-DIR with search base ou=ae-dir:

    --continue \
    --ca-certs /path/to/trusted-cacerts.pem \
    --ldap-url ldaps://ae-dir-p1.example.com/cn=otp,ou=ae-dir \
    --admin-dn uid=xkcd,ou=ae-dir


Sub-command ykreset is used to remove the pre-configured slots on brand-new Yubikey devices.

oath-ldap-tool ykreset -f -c -o ""


Sub-command ykadd is used to add OATH token entries based on a LDIF template file. Without argument -o or --owner it will interactively ask for an owner ID.

oath-ldap-tool ykadd ... --ldif-template /path/to/aedir-hotp-yubikey-template.ldif

See also: Examples for aedir-hotp-yubikey-template.ldif


Sub-command ykinit is used to generate a shared secret, send it to OATH-LDAP server and store it into the Yubikey. Furthermore the Yubikey device is proteced with a randomly generated access code which is displayed in the output. The access code is stored in the token entry encrypted with the same key like the shared secret.

oath-ldap-tool ykinit ...


Sub-command ykinit is used to test whether generating correct OTP values correctly works and if these values are valid. Furthermore contact information of owner is displayed which can be used for shipping the device to the right owner.

oath-ldap-tool ykcheck ...