LDAP Directory

CityScreen Deals publishes its employees and employee groups as an LDAP directory. Mail servers, VPN gateways and other systems read it to find e-mail addresses, to expand distribution lists and to check passwords, so that people use the same account everywhere.

An administrator creates the accounts that other systems connect with, called LDAP consumers. An integrator, or the person who runs the other system, configures that system with the address, the base DN and the credentials described here.

This function is licensed. If your organization’s license does not include it, contact CityScreen.

What the directory is

The directory is read-only: every write operation is refused with "The LDAP interface is read-only". It is served over LDAPS, which is TLS from the first byte, and StartTLS is refused. What a connection sees is decided by the roles of the account it is bound as.

The server speaks LDAP version 3 and accepts simple bind only. It answers bind, search, compare and the "Who am I?" extended operation (RFC 4532). Every other operation is refused.

Address

Setting Value

Server

ldap.<your organization’s domain>, port 636. CityScreen can confirm the address for your organization.

Protocol

LDAPS with TLS 1.2 or 1.3.

Base DN

One dc= component for each label of your organization’s domain, without the ldap. prefix. For an organization at office.example.com the base DN is dc=office,dc=example,dc=com.

Configure clients with the ldap. name, which the certificate is issued for. A connection by IP address does not work.

If the address of your organization has no domain name, for example because it is an IP address, the directory has no base DN and does not exist. The LDAP consumers page then shows "None: the address of this instance has no domain name, so the LDAP interface has no base DN."

The directory tree

The tree has three organizational units below the base DN.

Unit Entry class RDN Attributes

ou=people

inetOrgPerson

employeeNumber=<employee id>

uid is the username. cn and sn hold the full name, or the username when the name is empty. mail is the e-mail address.

ou=groups

groupOfNames

cn=<machine name>

description is the name of the group. member lists the DNs of the members. mail is the group’s e-mail address, when it has one.

ou=consumers

applicationProcess

cn=<consumer id>

description is the name of the consumer.

An attribute without a value is left out of the entry. mail and uid match ignoring case.

Only employee groups that have members are published. member lists only the employees who belong directly to the group. The RDN of a group is its machine name, which never changes, and its mail is the group e-mail.

A search with the empty DN as base and the base scope returns the root DSE, which names the base DN in namingContexts.

Who can connect

An LDAP consumer binds with the DN of its entry and its secret. An employee binds with the DN of their own entry and either the account password or an app password.

Who Bind DN Password

LDAP consumer

cn=<consumer id>,ou=consumers,<base DN>

The consumer secret, which starts with csd_ldc_.

Employee

employeeNumber=<employee id>,ou=people,<base DN>

The account password, or an app password, which starts with csd_app_.

Anonymous binds, and binds with an empty password, are refused.

The account password is refused for an employee who uses two-step verification, including an employee whose organization requires it, and for an employee whose password has expired. Those employees bind with an app password, which they create under Account > App passwords. See Access Tokens and App Passwords and Two-Step Verification. The Use in a mail client panel on the App passwords tab shows the Bind DN (user name) and the Base DN to employees who may view LDAP consumers.

A bind whose DN, secret or password the server rejects answers invalidCredentials (49) with "Invalid credentials", whatever the reason. A bind with another method than simple answers authMethodNotSupported (7), and a bind with LDAP version 2 answers protocolError (2).

When your organization does not have the function, every bind answers unwillingToPerform (53) with "The LDAP interface is not available under the license of this instance". Bind attempts are recorded in the sign-in log with the entry point "LDAP bind".

What a connection sees

A bound account sees the entries that its roles allow it to view. Employee entries need the permission to view employees, group entries need the permission to view employee groups, and consumer entries need the permission to view LDAP consumers. The scope of the permission applies: an account that may view only its own employee record sees only its own entry under ou=people.

An entry the account may not view does not exist for it. A search does not return the entry, a search with the entry as base answers "No such object", and the entry is left out of the member values of a group. A consumer that has no roles sees no employees, groups or consumers.

Operations and limits

Topic Behavior

Operations

Search with the base, one-level and subtree scopes, compare, and "Who am I?". Add, modify, modify DN, delete and Password Modify answer unwillingToPerform (53) with "The LDAP interface is read-only".

Filters

A filter is matched against every entry the account may view.

Size limit

At most 1000 entries per search, whatever size limit the client asks for. A search that reaches the limit answers sizeLimitExceeded (4) with the first 1000 entries.

Time limit

A search that runs too long answers timeLimitExceeded (3) with the entries found so far.

Entries read

A search that would have to read too many entries answers adminLimitExceeded (11) with "Too many entries to search" and returns no entries.

Controls

A control that is marked critical, including the paged results control, is refused with unavailableCriticalExtension (12). A control that is not critical is ignored.

Idle connections

The server closes a bound connection that stays idle.

Busy server

When the server is busy, it answers busy (51), and the client repeats the operation later.

When access ends

A change of roles applies at the next operation of a connection that is already bound.

A connection ends when its credential stops being valid:

  • A consumer connection ends when the consumer is deleted or its secret is regenerated.

  • An employee connection bound with the account password ends when the password changes or expires, when two-step verification applies to the employee, or when the account is deactivated.

  • An employee connection bound with an app password ends when the app password is revoked or the account is deactivated. A change of the account password does not end it.

  • Every connection ends when the organization is deactivated or the license for the function ends.

The operation that finds the credential invalid is answered with insufficientAccessRights (50) and "Authentication required", and the connection is unbound.

LDAP consumers

An LDAP consumer is an account for a system that reads the directory, such as a mail server. It has a name, a secret and roles, and it sees what its roles allow. Give it a role that can view employees and employee groups.

Consumers are managed in Employees > LDAP consumers. The tab is shown to employees whose role holds the permission LDAP consumers and whose organization has the function. The permission has the scope Any only, and it offers Create, View, Edit and Delete. See Roles & Permissions.

The page header shows the Base DN and the state of the interface:

State Meaning

Listening

The server accepts connections.

Not listening

The license includes the function, and the server is not accepting connections. Contact CityScreen.

Not available in the license

Your organization does not have the function.

The table lists each consumer with these columns:

Column Content

Name

The name of the consumer, with the beginning of its secret below it.

Bind DN

The DN the consumer binds with, with a Copy bind DN button.

Roles

The roles whose permissions the consumer acts with.

Last bind

The date and time of the last successful bind, or Never.

Creating a consumer

  1. Open Employees > LDAP consumers and click Create consumer.

  2. Enter a Name of up to 255 characters, for example "Postfix mail server".

  3. Choose the Roles.

  4. Click Create.

  5. The dialog "LDAP consumer created" shows the Bind DN and the Secret. Copy the secret with Copy secret and click Done.

Create a consumer only for a system your organization runs. Confirm who is asking before you give a secret to anyone, and before you regenerate one, because a consumer reads the employees and groups that its roles allow.

The warning in the dialog reads "Copy the secret now. It will not be shown again. Treat it like a password." After the dialog closes, the secret cannot be shown again.

Changing and removing a consumer

  • Edit changes the name and the roles. The secret stays the same.

  • Regenerate secret issues a new secret and shows it once. The old secret stops working at once, and every server that uses it must be configured with the new one.

  • Delete removes the consumer. Servers that bind with it lose access at once, and this cannot be undone.

A role cannot be deleted while it is assigned to a consumer.

Example: a mail server

The values in this example are office.example.com as the organization’s domain, 7 as the id of the consumer and jdoe as a username.

To check that a consumer can read the directory, search for an employee by username:

ldapsearch -x -H ldaps://ldap.office.example.com:636 \
  -D "cn=7,ou=consumers,dc=office,dc=example,dc=com" -w "$CONSUMER_SECRET" \
  -b "ou=people,dc=office,dc=example,dc=com" "(uid=jdoe)" uid cn mail

A mail server such as Postfix needs three lookups; the consumer runs all three searches, and the password check then binds as the employee:

  1. Mailbox lookup. The server looks for the employee whose address it is delivering to. The filter is (&(objectClass=person)(mail=<address>)) below ou=people, and the result attribute is mail.

  2. Distribution lists. The server looks for a group by its address with (&(objectClass=groupOfNames)(mail=<address>)) below ou=groups. It then expands the member values: each one is the DN of an employee, whose mail is read with a base-scope search. The consumer must be able to view the members, because a member it cannot view is left out of the list.

  3. Password check. When the server verifies a mailbox password, it finds the employee by (uid=<username>) below ou=people, and binds with the DN of the entry it found and the password the user typed.

For Postfix, the first two lookups are tables of the following form:

# mailboxes
server_host = ldaps://ldap.office.example.com:636
version = 3
bind = yes
bind_dn = cn=7,ou=consumers,dc=office,dc=example,dc=com
bind_pw = csd_ldc_...
search_base = ou=people,dc=office,dc=example,dc=com
query_filter = (&(objectClass=person)(mail=%s))
result_attribute = mail

# distribution lists
server_host = ldaps://ldap.office.example.com:636
version = 3
bind = yes
bind_dn = cn=7,ou=consumers,dc=office,dc=example,dc=com
bind_pw = csd_ldc_...
search_base = ou=groups,dc=office,dc=example,dc=com
query_filter = (&(objectClass=groupOfNames)(mail=%s))
special_result_attribute = member
result_attribute = mail

For saslauthd, the password check uses these settings:

ldap_servers: ldaps://ldap.office.example.com:636
ldap_bind_dn: cn=7,ou=consumers,dc=office,dc=example,dc=com
ldap_bind_pw: csd_ldc_...
ldap_search_base: ou=people,dc=office,dc=example,dc=com
ldap_filter: (uid=%u)
ldap_auth_method: bind
Connect with an ldaps:// address and leave StartTLS off: do not use -Z with ldapsearch or start_tls = yes in a mail server. Do not ask for paged results, because the server refuses a critical paging control.

Related pages