Documentation

Intended Audience: System architects, developers and system administrators

  1. System architecture
    1. Æ-DIR provider
    2. Æ-DIR consumer
  2. Roles and Access Rights
    1. Æ Admin
    2. Æ Auditor
    3. Zone Admin
    4. Zone Auditor
    5. Setup Admin
    6. Æ User
    7. Æ client service
    8. Æ server service
    9. Æ host
    10. Æ Replica
    11. Æ Provider
    12. Æ Login Proxy
  3. Directory Information Tree (DIT)
    1. Zone ae
    2. Zone people
    3. Zone pub
  4. Entity Relationship
  5. Schema
    1. Structural Object Classes
    2. Auxiliary Object Classes
  6. OpenLDAP configuration (slapd.conf)
    1. slapd replica roles
    2. Backends
    3. Overlays
    4. Access control

System architecture

Æ-DIR overall system architecture

Æ-DIR provider

For maintaining entries the Æ-DIR provider are used.

The following roles may access Æ-DIR provider:

Note: It is recommended to restrict network access to IP networks used by the roles above.

Æ-DIR provider components

The following system components are running on each Æ-DIR provider system:

slapd provider
OpenLDAP's slapd acting as roles Æ Replica and Æ Provider (see also provider configuration)
web2ldap
web2ldap is a web-based LDAPv3 client to access and maintain LDAP servers. It is used as Æ-DIR's main admin user interface. Check out the documentation to find out about fine-tuning, customizing etc.
aedirpwd_web
aedirpwd_web is a small web application for password self-service (see user guide for instructions how to use it).
aedirpwd_cron
aedirpwd_cron is a small Python script running as CRON job which performs the following tasks:
  • remove expired password reset attributes
  • send welcome e-mails to new users especially with password reset instructions

Æ-DIR consumer

All integrated hosts and services query the Æ-DIR consumers for accessing user and group entries and checking user passwords. Write access to consumers is deliberately disallowed. All write operations must be sent to the Æ-DIR provider systems.

The following roles may access Æ-DIR provider:

Note: It is recommended to restrict network access to IP networks used by the roles above.

There is currently only one component running on on each Æ-DIR consumer system:

slapd consumer
OpenLDAP's slapd acting as role Æ Replica (see also consumer configuration)

Roles

This chapter gives a high-level overview over the different roles and their access rights in Æ-DIR. See chapter access control for technical details.

Æ Admin

Æ admins (role assigned by membership in group ae-admins) directly manage all Æ-DIR systems and therefore have full write access (including manage privilege) to all LDAP entries. Furthermore this role has full read access to the audit database.

Typically the Æ admins are not expected to know the systems using Æ-DIR or the users in detail. Therefore Æ admins are adviced not to perform daily maintenance tasks except those directly related to Æ-DIR systems.

Typical tasks:

Exceptional tasks (requires careful consideration):

Æ Auditor

Æ auditors (role assigned by membership in group ae-auditors) have full read access to all LDAP entries including the audit database. Even when added to another user group members of group ae-auditors will not gain any write access.

Typical tasks:

Zone Admin

Zone admins have full write access (but no manage privilege) to all entries within a zone. Typically they perform the daily data maintenance tasks.

The role is assigned to a user account by adding it to a user group with name *-zone-admins which is referenced by attribute aeZoneAdmins in the aeZone entry.

Typical tasks:

People Admin

Zone admins in the special zone people are People Admins and can write organizational entries (aePerson, aeDept and aeLocation) and maintain organizational management relationships.

Zone Auditor

Zone auditors have full read access to all entries within a zone. Typically zone auditors need to read entries to reference them from another zone where they act as zone admin.

The role is assigned to a user account by adding it to a user group with name *-zone-admins or *-zone-auditors which is referenced by attribute aeZoneAuditors in the aeZone entry.

Typical tasks:

Setup Admin

Setup admins can maintain (add/modify/delete) member hosts/services of a service group typically while setting up a hosts/services instances. They can read but not write the service group (aeSrvGroup) entry. The role is assigned by adding a user to a user group referenced in attribute aeSetupGroups in the service group (aeSrvGroup).

Typical tasks:

Æ User

Normal Æ users can read their own person and user entries including own group membership and all user entries which are in at least one common user group. Users can set their own password but cannot read it.

Æ client service

Æ client services

Æ server service

Æ server services

Æ host

Æ host

Æ Replica

The system role Æ replicas can read all entries including userPassword except some sensitive attributes only usable by role Æ provider.

The role is assigned to service accounts (aeService) of all provider and replica slapd instances by adding them to user group ae-replicas.

Æ Provider

Additionally to the rights assigned to role Æ replica the role Æ provider has read access to:

The role is assigned to service accounts (aeService) of all provider slapd instances by adding them to user group ae-providers.

Æ Login Proxy

The system role Æ login proxy can read all attributes in user, group, service group and service group member entries needed for determining user role relationship.

The role is typically assigned solely to central service accounts (aeService) in zone ae by adding them to user group ae-login-proxies.

Directory Information Tree (DIT)

ou=ae-dir

The following diagram illustrates the directory information tree (DIT) structure of Æ-DIR in naming context ou=ae-dir where all Æ-DIR entities are stored as separate LDAP entries. The nodes contain the relative distinguished name (RDN) and the structural object class used for that entry. The tree structure is also formally specified (within web2ldap's configuration) with DIT structure rules and name forms.

Graph of Æ-DIR tree structure

cn=ae,ou=ae-dir

Zone ae is used for administration of Æ-DIR itself. Therefore some special restrictions apply.

Sub-tree structure of zone ae
RDN Description Structural object class
cn=ae-admins Group members can manage all Æ-DIR entries (see also role Æ Admin) aeGroup
cn=ae-auditors Group members can read all Æ-DIR entries (see also role Æ Auditor) aeGroup
cn=ae-all-zone-admins Æ-DIR user group entry updated by a CRON job to contain all active zone admins (see also role Zone Admin) aeGroup
cn=ae-all-zone-auditors This Æ-DIR user group entry is updated by a CRON job to contain all active zone auditors (see also role Zone Auditor) aeGroup
cn=ae-dir-provider-hosts Server group for all AE-DIR provider hosts aeSrvGroup
cn=ae-dir-consumer-hosts Server group for all AE-DIR consumer hosts aeSrvGroup
cn=ae-login-proxies Members are central login (proxy) components which are allowed to see all users/groups and must determine login user/target relation themselves (see also role Æ Login Proxy) aeGroup
cn=ae-replicas Members of this group are AE-DIR replicas including providers and consumers (see also role Æ Replica) aeGroup
cn=ae-providers Members of this group are AE-DIR provider replicas (see also role Æ Provider) aeGroup
cn=ae-sudo-sys-admins allows su - root for AE-DIR system admins (group ae-sys-admins) aeSudoRule
cn=ae-sys-admins Members are system admins for AE-DIR servers aeGroup
cn=ae-tag-init Tag for all entries created during initial load aeTag
cn=ae-uid-badwords UID blacklist containing bad words namedObject
cn=ae-uid-blacklist This entry contains a blacklist for 'uid' values namedObject
cn=ppolicy-base-users Password policy for primary personal user accounts (aeUser) in zone base namedPolicy
cn=ppolicy-default Unusable default password policy namedPolicy
cn=ppolicy-otptokens Password policy for OTP enrollment namedPolicy
cn=ppolicy-sasl-external Password policy for services which must use SASL/EXTERNAL (mainly disallows using simple bind with password) namedPolicy
cn=ppolicy-systems Password policy for hosts and system/service accounts (aeHost and aeService) namedPolicy
cn=ppolicy-users Password policy for personal user accounts (aeUser) namedPolicy
uid=ae-dir-otpenroll Service account for two-factor enrollment application (based on OATH-LDAP) aeService
uid=ae-dir-otpverify Service account for OATH-LDAP validator demon aeService
uid=ae-dir-pwd Service account for password self-service application and CRON job aeService

cn=people,ou=ae-dir

Zone people is used for storing organizational entries. These can be maintained manually or could be synced with a HR system or similar if appropriate. Make sure to avoid hen-and-egg issues when syncing entries. Manual maintenance is done by role People Admin.

cn=pub,ou=ae-dir

Zone pub contains entries which are globally readable by all authenticated clients and maintained by role Æ Admin:

RDN Description Structural object class
cn=sudo-defaults sets sudoers defaults sudoRole
cn=pub-tag-no-welcome-yet tag used with aeUser entries indicating that welcome e-mail was not sent to user yet aeTag
cn=dua-profile client configuration profile (see RFC 4876) DUAConfigProfile

Entity Relationship

The following diagram illustrates how the different entities in Æ-DIR are referenced from each other. This entity relationship is evaluated by the OpenLDAP ACLs to determine access rights of bound entity.

complete entity relationship diagram

The following smaller diagram shows only references for assigning Æ-DIR roles.

entity roles relationship diagram

Setting cross-zone references allow zone admins to delegate tasks to zone admins of other zones:

  1. Strictest level for preservation of full control:
    Users, user groups, service groups and services / hosts all in one zone. This gives the responsible zone admins full control over all authentication and authorization but also places the burden of having to maintain all these entries on them.
    This model should be used for hosts/services with high security requirements with access probably only for rather few administrators.
  2. Preservation of permissions control, user maintenance delegation to foreign zone:
    A zone admin can add users located in foreign zones to user groups in their zone. The rights to assign permissions to users is preserved but user maintenance (e.g. helping with password reset) is delegated to foreign zone admins.
    This model is reasonable for most hosts/services.
    The cross-zone reference link from aeGroup to aeUser/ aeService.
  3. Full foreign zone delegation of user and permission group maintenance:
    Delegating permission assignment (granted by group membership) can be achieved by referencing user groups in another zone from a server group. Note that different permissions are assigned by different link attributes and application-specific permissions for groups within services.
    This model is reasonable for most hosts/services.
    The cross-zone reference link from aeSrvGroup to aeGroup.

Schema

Attribute Types

The following diagram shows the attribute type hierarchy:

Graph of AE-DIR's attribute type

Structural Object Classes

For each entity in Æ-DIR there is a distinct structural object class (see also RFC 4512 section 2.4.2). All Æ-DIR object classes are derived from multiple abstract and structural object classes defined in various other standards.

The following diagram shows the object class hierarchy:

Graph of AE-DIR's structural object classes

The structural object classes are also referenced in the accompanying…

NAME RDN DESC SUP AUX
aeAuthcToken cn Authentication token device aeDevice
aeContact cn Mail contact
  • mailboxRelatedObject
  • inetLocalMailRecipient
aeDept departmentNumber department / organization unit labeledURIObject
aeGroup cn user group -/-
aeHost host host information and for host authentication aeDevice
aeLocation cn location labeledURIObject
aeMailGroup cn user group
  • mailboxRelatedObject
aeNwDevice cn Network device information aeDevice
  • ipHost
  • ieee802Device
  • bootableDevice
aeObject -/- abstract meta class -/-
aePerson uniqueIdentifier personal information msPerson
aePolicy cn Policy information
  • pwdPolicy
  • oathHOTPParams
  • oathTOTPParams
aeRoot ou root entry of Æ-DIR tree aePosixIdRanges
aeService uid service user account
aeSrvGroup cn host/service group -/-
aeSudoRule cn sudoers entry -/-
aeTag cn tag name-description mapping namedObject -/-
aeUser uid personal user account
aeZone cn zone (delegation container) aePosixIdRanges

aeObject

aeObject is an abstract object class, which only contains some common meta data attributes, to be available in all entries as described in the following list:

description
Must / should contain short description of the purpose / reason / usage of an entry. Especially this attribute is very often displayed as pop-up title in web2ldap.
aeStatus
The current status of an entry:
Value Meaning Usage
-1 requested Especially useful for adding an entry without making it directly usable, e.g. in case a confirmation is needed.
0 active In this state an entry is visible depending on the normal ACLs.
1 deactivated In this state an entry is still visible for zone admins/auditors but is not usable on systems/services. The entry can be set to active by zone admins if no other constraint disallows it.
2 archived In this state an entry is invisible even for zone admins/auditors and some attributes might already been stripped off due to privacy regulations. Which attributes are stripped is to be defined as local policy.
aeExpiryStatus
If set this triggers auto-expiration of entries and specifies the value to which aeStatus is set when aeNotAfter is in the past.
aeTicketId
This attribute is used to record the bug/issue tracker ID of the last change applied to an entry.
Validity period
Two attributes define the time period in which an entry can be used:
aeNotBefore
The entry must not be actively used before this timestamp.
aeNotAfter
The entry must not be actively used after this timestamp.
The validity period affects which aeStatus values are valid at current time:
Validity period aeStatus
aeNotBefore <= [current time] <= aeNotAfter requested (-1)
active (0)
deactivated (1)
archived (2)
[current time] > aeNotAfter (expired) deactivated (1)
archived (2)
[current time] < aeNotBefore requested (-1)
aeTag
This attribute contains names (attribute cn) of aeTag entries useful for marking various entries across zones or other boundaries. This eases searching for entries which are used together to provide a certain service.

aeRoot

The object class aeRoot is solely used for locating an Æ-DIR tree within another tree of other entries. Especially it also serves as start point to Æ-DIR's specific DIT structure rules and name forms.

description
set to "Æ-DIR - Authorized Entities Directory"
ou
usually set to ae-dir resulting in naming context / search root ou=ae-dir
meta attributes
see aeObject

aePolicy

The object class aePolicy is used for policy / security parameter entries. The real effective policy parameters are supposed to be attributes of AUXILIARY object classes added to the entry.

cn
common name of policy
description
Must contain short description of the purpose / meaning / scope of the policy
meta attributes
see aeObject

aeDept

The object class aeDept is used for entries for departments or units within an organization.

departmentNumber
Unique identifier / short name of department / organizational unit
ou
Descriptive name of department / organizational unit
organizationalUnit attributes
see RFC 4519: organizationalUnit
meta attributes
see aeObject

aeLocation

The object class aeLocation is used for entries representing geographic locations (offices, data centers) and can be referenced from aePerson or aeHost entries.

cn
Short name of location
locality attributes
see RFC 4519: locality
meta attributes
see aeObject

aeTag

The structural object class aeTag is used to create tagging entries mapping an arbitrary name (RFN attribute cn) to a meaningful usage definition in attribute description.

description
Must contain short description of the purpose / meaning of a tag.
cn
Name of the tag.
meta attributes
see aeObject

aeZone

Entries of object class aeZone are simply used as container for delegated administration. Besides the meta attributes and the zone name in attribute cn for forming the RDN there are no other attributes therein.

cn
Name of the zone. For the sake of clarity the value in cn must also be used as prefix of attribute cn in these subordinate entries:
aeDept
Associated department referenced by DN of aeDept entry. If set, this constraints the set of persons, for which aeUser entries can be added within this zone to matching department members.
meta attributes
see aeObject
aeZoneAdmins
Distinguished names of all aeGroup entries which's members act with role zone admin for the zone.
Constraint enforces that the group exists, is active and has name (attribute cn) of the form *-zone-admins.
aePasswordAdmins
Distinguished names of all aeGroup entries which's members are allowed to change password of aeUser entries and thus circumventing the password reset process.
Constraint enforces that the values are a subset of aeZoneAdmins.
aeZoneAuditors
Distinguished names of all aeGroup entries which's members act with role zone admin for the zone.
Constraint enforces that the group exists, is active and has name (attribute cn) of the form *-zone-admins or *-zone-auditors.

aePerson

Person entries are added using object class aePerson. Note that such an entry is not a user account and thus cannot authenticate to a the directory. Typically aePerson are maintained by human resource (HR) or sales departments (for customers), optionally synchronized from HR database or a customer relationship management (CRM) database or similar.

uniqueIdentifier
Unique primary key possibly used for synchronisation. This attribute is readable to various roles.
employeeNumber
Another unique primary key possibly used for synchronisation but subject to stricter access control due to privacy regulations for HR databases.
inetOrgPerson attributes
A limited subset of the widely used attributes defined in RFC 2798.
meta attributes
see aeObject

aeUser

Accounts for persons are created by using object class aeUser. For compability reasons with existing software aeUser is derived from the superior object classes account and inetOrgPerson. This object class must not be used when creating system/service/tool accounts. For these use aeService instead.

uid
unique username / user-ID of the personal account
aePerson
DN of the associated aePerson entry
aePerson attributes
The following name attributes values are copied from the accompanying aePerson name attributes:
  • sn
  • givenName
  • cn
  • mail
aeRemoteHost
remote host (client IP or FQDN) used during login
meta attributes
see aeObject

aeGroup

User groups are created using object class aeGroup. This hybrid group object class is derived from two structural group object classes:

groupOfEntries
replacement for groupOfNames which permits empty groups (see draft-findlay-ldap-groupofentries)
posixGroup
multiple attributes required for POSIX groups used for Unixoid operating systems (see RFC 2307)

The following attributes are used in aeGroup entries:

cn
unique group name
gidNumber
unique numerical POSIX GID for the group
member
Distinguished names of all member entries
memberUID
uid values of all member entries
aeDept
Associated department referenced by DN of aeDept entry. If set, this constraints the set of persons whose aeUser entries can be added to the group.
meta attributes
see aeObject

aeSrvGroup

In general a service group contains service instances which are together providing a service and are thus considered subject to unified administrative rules. So for each service providing a user login a service group entry has to be added with object class aeSrvGroup. Likely a clustered service consists of multiple hosts or other services which are called the members of the service group.

Service group entries have the following attributes:

cn
unique service group name
aeLoginGroups
Distinguished names of all aeGroup entries which's members have the right to login to the members of the service group
aeLogStoreGroups
Distinguished names of all aeGroup entries which's members have the right to access the centrally stored logs of the members of the service group
aeLogStorePeriod
aeProxyFor
Distinguished names of all aeSrvGroup for which this service group acts as proxy (must be within same zone)
aeSetupGroups
Distinguished names of all aeGroup entries which's members have the right to setup the members of the service group
aeVisibleGroups
Distinguished names of all aeGroup entries visible with their member accounts on all members of the service group
aeDisplayNameGroups
Distinguished names of all aeGroup entries define for which member accounts person attributes are visible for all service group members
aeVisibleSudoers
Distinguished names of all aeSudoRule entries visible on all members of the service group
meta attributes
see aeObject

aeSudoRule

sudoers rules are stored in entries of object class aeSudoRule. The attributes are compatible to those defined for sudo-ldap plus the meta information of aeObject and some constraints.

cn
unique rule name
sudo-ldap attributes
See sudo-ldap documentation: Notes:
  • The attribute sudoUser is constrained to only contain the name of a group (cn of an aeGroup entry) prefixed with a single percent character.
  • You must set attribute sudoHost to ALL because restricting sudoers rules to hosts is better achieved by restricting visibility in the service group (attribute aeVisibleSudoers in aeSrvGroup entry).
meta attributes
see aeObject

aeService

Object class aeService is used for creating accounts for services (sometimes called tool / machine / system account or similar). The service must authenticate by using bind-DN/password or TLS client cert. aeService entries may have a password (attribute userPassword) to authenticate to Æ-DIR. X.509 client certificate(s) may be associated by adding AUX object class pkiUser and setting the attribute seeAlso to the client certs subject-DN.

Two possible usage types (roles):

uid
unique username / user-ID of the system account
cn
unique service name
aeSrvGroup
distinguished names of aeSrvGroup entries this service is also member of
aeHost
distinguished name of aeHost entry for the system this service is running on
aeRemoteHost
remote host (client IP or FQDN) used during login
meta attributes
see aeObject

aeHost

Object class aeHost for host systems with login service for the operating system on this host.

host
unique canonical hostname (FQDN)
aeSrvGroup
distinguished names of aeSrvGroup entries this host is also member of
aeRemoteHost
remote host (client IP or FQDN) used during login
meta attributes
see aeObject

aeAuthcToken

Object class aeAuthcToken is used to add entries for personal authentication (OTP) token devices (e.g. yubikey).

cn
Device name
serialNumber
unique serial number (most times aeHwSerialNumber with prefix)
aeHwSerialNumber
vendor-specific serial number (not necessarily unique)
aeStockId
inventory number used for warehousing
meta attributes
see aeObject

aeNwDevice

Object class aeNwDevice is used to add entries subordinate to aeHost entries for network devices available on that particular host system.

cn
OS-assigned device name of network device
aeFqdn
fully qualified domain name (FQDN) of IP address(es) assigned to this device
aeNwDevice
DN reference to another aeNwDevice entry, e.g. to be used for bridge/virtual interfaces without macAddress attribute (constrained to DNs beneath same superior aeHost)
ipHostNumber
the IP address(es) of the network interface which must match the DNS lookup of values in attribute aeFqdn
macAddress
the hardware MAC address of the network interface
bootFile
which PXE file to load via TFTP
bootParameter
OS-specific boot parameters
meta attributes
see aeObject

Auxiliary Object Classes

Various auxiliary object classes are used to provide supplemental attributes. The DIT content rules defined for structural object classes restrict which auxiliary object classes can be added to an entry (see also table of structural object classes).

posixAccount

The auxiliary object class posixAccount contains multiple attributes required for POSIX login to Unixoid operating systems (see RFC 2307).

The following posixAccount attributes are always added to aeUser and aeService entries:

inetLocalMailRecipient

The auxiliary object class inetLocalMailRecipient contains multiple attributes used for SMTP e-mail routing (see draft-lachman-laser-ldap-mail-routing).

The following inetLocalMailRecipient attributes are optionally added to aeUser and aeService entries to turn these entries into a mailbox account:

pkiUser

The auxiliary object class pkiUser is used ... (see RFC 4523).

The following pkiUser attribute is optionally added to aeUser, aeService or aeHost entries:

ldapPublicKey

The auxiliary object class ldapPublicKey is used to store SSH public keys in (see openssh-ldap-publickey).

The following ldapPublicKey attribute is optionally added to aeUser and aeService entries:

OpenLDAP configuration (slapd.conf)

slapd replica roles

slapd provider

slapd consumer

Database backends

Different backends are used on all slapd instances listed in the following table.

Suffix No. Description Backend
cn=config 0 used in read-only mode for retrieving configuration (e.g. for monitoring) slapd-config(5)
cn=accesslog-ae-dir 1 Real database storage backend used for storing audit log entries of all write operations. The schema is formally specified in the Internet draft draft-chu-ldap-logschema. slapd-mdb(5)
ou=ae-dir 2 Real database storage backend used for Æ-DIR itself (see details) slapd-mdb(5)
cn=monitor used for retrieving performance monitor data slapd-monitor(5)

Overlays

Various overlays are configured on all replicas:

slapo-memberof
(see also slapo-memberof(5))
slapo-accesslog
used to log all write operations to the separate naming context cn=accesslog-ae-dir (see also slapo-accesslog(5))
slapo-rwm
(see also slapo-rwm(5))
slapo-syncprov
(see also slapo-syncprov(5))
slapo-lastbind
(see also slapo-lastbind(5))
slapo-ppolicy
(see also slapo-ppolicy(5))
slapo-noopsrch
(see also slapo-noopsrch(5))
slapo-deref
(see also slapo-deref(5))
slapd-sock
When using two-factor authentication bind requests are externally processed. The bind requests are passed to the external bind listeners by configuring slapd-sock(5) as overlay.

Several constraints are enforced by overlays configured on the slap provider to ensure data consistency and some more security policies:

slapo-unique
Uniqueness constraints slapo-unique(5)
slapo-constraint
Attribute value constraints slapo-constraint(5)
slapo-refint
Referential integrity slapo-refint(5)

Access control

Security policies are enforced by different types of OpenLDAP ACLs:

group
Access rights are granted based on simple group membership.
regex
Access rights are granted based on DIT with distinguished names matching certain regex patterns.
sets
Access rights are granted based on (indirect) entity relationship by following the references from entries to other entries.

If you want to understand the ACLs in detail you should consult various on-line documentation: