LDAP

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
ACI	Access Control Instruction	目录服务中的访问控制指令
ACL	Access Control List	访问控制列表
AD	Active Directory	微软活动目录
CA	Certificate Authority	证书颁发机构
CPU	Central Processing Unit	中央处理器
DB	Database	数据库
DNS	Domain Name System	域名系统
DS	Domain Services / Directory Server	AD DS 中指域服务；389 DS 等产品中指目录服务器
FS	File System	文件系统
GPO	Group Policy Object	组策略对象
HBAC	Host-Based Access Control	基于主机的访问控制
HR	Human Resources	人力资源
HRIS	Human Resources Information System	人力资源信息系统
IAM	Identity and Access Management	身份与访问管理
ID	Identifier	标识符
IdP	Identity Provider	身份提供方
IGA	Identity Governance and Administration	身份治理与管理
LDAP	Lightweight Directory Access Protocol	轻量级目录访问协议
LDIF	LDAP Data Interchange Format	LDAP 数据交换格式
MFA	Multi-Factor Authentication	多因素认证
OIDC	OpenID Connect	基于 OAuth 2.0 的身份认证协议
OSS	Open-Source Software	开源软件
OU	Organizational Unit	组织单元
PAM	Pluggable Authentication Modules	可插拔认证模块
SaaS	Software as a Service	软件即服务
SAML	Security Assertion Markup Language	安全断言标记语言，用于身份联合
SSO	Single Sign-On	单点登录
SSSD	System Security Services Daemon	Linux 系统安全服务守护进程
TLS	Transport Layer Security	传输层安全协议
URL	Uniform Resource Locator	统一资源定位符，通常指访问地址
UUID	Universally Unique Identifier	通用唯一标识符

Links#

https://www.openldap.org/doc/admin26/
https://www.port389.org/docs/389ds/
https://www.freeipa.org/page/Documentation
https://www.samba.org/samba/docs/current/man-html/samba.8.html
https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview
https://learn.microsoft.com/en-us/entra/identity/domain-services/
https://directory.apache.org/apacheds/
https://www.rfc-editor.org/rfc/rfc4511
https://www.rfc-editor.org/rfc/rfc4512

1. Important Points#

LDAP 是 directory access protocol，不是 SSO 协议。它主要解决“怎么查用户、组、属性，以及怎么验证用户名密码”。

LDAP is good at:
    user lookup
    group lookup
    password bind authentication
    directory attributes
    hierarchical organization data
    central account source for Linux / network devices / legacy apps

LDAP is not:
    SAML IdP
    OIDC provider
    OAuth2 authorization server
    browser SSO session manager
    complete HR lifecycle system

和 Keycloak 的关系:

Keycloak does not require LDAP:
    Keycloak can use local users
    Keycloak can broker upstream OIDC / SAML IdP
    Keycloak can connect LDAP / AD only when enterprise directory federation is needed

LDAP / AD with Keycloak:
    LDAP / AD stores users, groups, passwords
    Keycloak reads and authenticates against LDAP / AD
    Keycloak maps LDAP groups / attributes to claims
    Keycloak issues OIDC tokens or SAML assertions to apps

典型架构:

LDAP / Active Directory
    -> Keycloak User Federation
        -> OIDC / SAML
            -> internal apps / SaaS / APIs

2. Product Options#

Product	Best For	Not Best For
Microsoft AD DS	Windows domain, GPO, Kerberos, enterprise workforce directory	Linux-only lightweight LDAP
Microsoft Entra Domain Services	Azure managed domain join / LDAP / Kerberos for cloud workloads	Full AD replacement with domain admin control
FreeIPA	Linux fleet identity, Kerberos, SSSD, sudo/HBAC, certificate integration	Windows GPO-heavy environment
389 Directory Server	Enterprise LDAP server, replication, Red Hat ecosystem	AD-compatible domain controller
OpenLDAP	Lightweight generic LDAP directory, embedded/infrastructure use	Full workforce IAM without extra tooling
Samba AD DC	Open-source AD-compatible domain controller	Simple LDAP-only directory
ApacheDS	Java LDAP server, dev/test, embedded directory use	Large enterprise workforce directory
OpenDJ / ForgeRock DS	Commercial/enterprise directory platform	Simple self-managed OSS baseline
Oracle Unified Directory	Oracle enterprise stack	Small teams avoiding commercial lock-in

Simple grouping:

AD-compatible domain:
    Microsoft AD DS
    Samba AD DC
    Microsoft Entra Domain Services, managed but with limits

Linux identity platform:
    FreeIPA

Generic LDAP directory:
    OpenLDAP
    389 Directory Server
    ApacheDS
    OpenDJ / ForgeRock DS
    Oracle Unified Directory

3. Decision Guide#

choose Microsoft AD DS when#

you need:
    Windows domain join
    Group Policy
    Kerberos for Windows estate
    enterprise desktop/laptop management
    mature admin tooling
    many commercial apps expecting AD

notes:
    AD DS is not just LDAP
    AD DS includes LDAP, Kerberos, DNS, domain controller replication, GPO
    SAML/OIDC usually comes from AD FS, Entra ID, Okta, Keycloak, or similar IdP layer

choose FreeIPA when#

you need:
    Linux server identity
    Kerberos for Linux
    SSSD integration
    sudo rules
    HBAC rules
    host/service principals
    integrated CA/cert management

best fit:
    Linux-heavy platform team
    internal infrastructure identity
    Keycloak reads users/groups from FreeIPA LDAP

choose 389 Directory Server when#

you need:
    enterprise LDAP server
    replication
    good operational tooling
    Red Hat ecosystem alignment
    directory service without full AD domain semantics

choose OpenLDAP when#

you need:
    lightweight standards-based LDAP
    simple user/group directory
    broad compatibility
    low footprint
    maximum control

watch out:
    operations are more manual
    schema/ACL/replication need LDAP expertise
    not a complete IAM product by itself

choose cloud managed directory when#

you need:
    less domain controller maintenance
    cloud workload domain join
    managed backups and patching
    integration with cloud identity

watch out:
    not every managed directory is a full AD replacement
    admin control, schema extension, trust, and network limits vary

4. Core Concepts#

Concept	Meaning	Example
DIT	Directory Information Tree	whole LDAP tree
DN	Distinguished Name	`uid=alice,ou=people,dc=example,dc=com`
RDN	Relative Distinguished Name	`uid=alice`
Base DN	search root	`dc=example,dc=com`
Entry	one directory object	user, group, org unit
Attribute	field on entry	`mail`, `cn`, `uid`
ObjectClass	schema type	`inetOrgPerson`, `groupOfNames`
Bind	authentication step	user/password or service account
Search	query operation	find user by uid/mail
Filter	LDAP query filter	`(uid=alice)`
LDIF	text format for LDAP data	import/export entries
StartTLS	upgrade LDAP connection to TLS	port 389 with TLS negotiation
LDAPS	LDAP over TLS	port 636
ACL / ACI	access control	who can read/write which attributes

DN parts#

dc=example,dc=com 通常来自公司拥有的 DNS domain。

DNS domain:
    example.com

LDAP base DN:
    dc=example,dc=com

为什么是两个 dc:

dc:
    domain component

example.com:
    has two DNS labels:
        example
        com

LDAP DN:
    writes each DNS label as one dc component:
        dc=example,dc=com

真实公司通常用自己控制的域名:

LDAP entry 的 DN 是目录路径，OU 用于组织条目；认证成功不自动决定应用业务权限，授权规则需另行配置。

company domain:
    example.com      -> dc=example,dc=com
    corp.example.com -> dc=corp,dc=example,dc=com
    example.local    -> dc=example,dc=local

recommended:
    use a domain the company controls
    avoid random public-looking domains you do not own
    keep base DN stable; changing it later is painful

ou 是 Organizational Unit，用来把 entry 分区管理。它不是必须的，但生产目录通常会建。

ou=people:
    user entries live here

ou=groups:
    group entries live here

ou=service-accounts:
    service bind accounts live here

why use ou:
    easier search base
    easier ACL
    easier sync scope
    easier backup/export review
    avoid mixing users, groups, service accounts, admins

cn 是 Common Name，通常表示一个 entry 的可读名称。组对象经常用 cn=<group-name> 作为 RDN；用户对象可以用 uid=<login-name> 或 cn=<name>，企业里更常见用稳定的 uid。

dn:
    full path of one entry in LDAP tree

rdn:
    left-most part of DN
    examples:
        uid=alice
        cn=platform-admins

dc:
    domain component

ou:
    organizational unit / folder-like container

uid:
    stable login identifier for user

cn:
    common name, often display name or group name

和 SAML/OIDC 的关系:

LDAP:
    stores attributes:
        uid
        cn
        sn
        mail
        member

Keycloak / IdP:
    reads LDAP entries
    maps LDAP attributes and groups
    emits SAML attributes or OIDC claims

SAML example:
    mail -> email attribute
    cn -> displayName attribute
    group membership -> groups attribute

OIDC example:
    uid -> preferred_username
    mail -> email
    cn -> name
    LDAP group -> groups claim or app role

应用通常不应该直接依赖完整 DN 作为业务用户 ID，因为 DN 会受 OU 迁移影响。更推荐用稳定的 uid、entryUUID、AD objectGUID、或 IdP 里稳定的 sub。

Example tree:

dc=example,dc=com
    ou=people
        uid=alice
        uid=bob
    ou=groups
        cn=platform-admins
        cn=developers
    ou=service-accounts
        uid=svc-keycloak

Example user:

# This entry's full LDAP path. uid=alice is the user RDN; ou=people is the container; dc=example,dc=com is the base DN.
dn: uid=alice,ou=people,dc=example,dc=com

# Object class for a human user with common attributes such as cn, sn, mail.
objectClass: inetOrgPerson

# Object class for Unix/Linux account attributes such as uidNumber, gidNumber, homeDirectory.
objectClass: posixAccount

# Stable login name / user identifier. Often mapped to OIDC preferred_username.
uid: alice

# Common name / display name. Often mapped to OIDC name or SAML displayName.
cn: Alice Chen

# Surname / family name. inetOrgPerson requires sn.
sn: Chen

# Email address. Often mapped to OIDC email or SAML email attribute.
mail: alice@example.com

# Numeric Unix user ID for POSIX/Linux integration.
uidNumber: 10001

# Numeric primary Unix group ID for POSIX/Linux integration.
gidNumber: 10001

# Unix home directory for POSIX/Linux integration.
homeDirectory: /home/alice

Example group:

# This group entry's full LDAP path. cn=platform-admins is the group RDN under ou=groups.
dn: cn=platform-admins,ou=groups,dc=example,dc=com

# Object class for a group whose members are referenced by DN.
objectClass: groupOfNames

# Group common name / group identifier. Often mapped to SAML groups or OIDC groups claim.
cn: platform-admins

# Member points to the full DN of a user entry. This says alice belongs to platform-admins.
member: uid=alice,ou=people,dc=example,dc=com

5. Architecture#

LDAP only#

legacy app
    -> LDAP bind/search
        -> LDAP server

适合老系统、网络设备、Linux PAM/SSSD、内部工具。缺点是每个应用都要自己处理登录体验、session、MFA、权限映射。

LDAP behind SSO#

app
    -> OIDC / SAML
        -> Keycloak / Okta / Entra ID / AD FS
            -> LDAP / AD

适合现代应用。应用不直接碰密码，只验证 IdP 发来的 token/assertion。

LDAP and HR source#

HRIS
    -> identity sync / workflow
        -> LDAP / AD
            -> Keycloak / SSO
                -> apps

LDAP 通常不应该是唯一的入职/离职流程系统。HRIS / IGA / workflow 要决定账号生命周期，LDAP/AD 承载账号状态。

6. Schema And Data Modeling#

design principles:
    choose stable uid
    email can change, avoid using email as immutable id
    keep base DN simple
    separate people, groups, service accounts
    define group model early
    document required attributes
    avoid app-specific random attributes in common user object

Recommended baseline:

base DN:
    dc=example,dc=com

people:
    ou=people,dc=example,dc=com

groups:
    ou=groups,dc=example,dc=com

service accounts:
    ou=service-accounts,dc=example,dc=com

admin accounts:
    ou=admins,dc=example,dc=com

Group strategy:

application access:
    cn=app-order-admins,ou=groups,dc=example,dc=com
    cn=app-order-readers,ou=groups,dc=example,dc=com

team identity:
    cn=team-platform,ou=groups,dc=example,dc=com

do not:
    map every organization department directly to every app role
    put thousands of groups into every OIDC token

7. Security Best Practices#

network:
    do not expose LDAP to the Internet
    restrict LDAP to trusted subnets / apps
    use LDAPS or StartTLS
    monitor certificate expiry

bind accounts:
    create one service bind account per system
    read-only by default
    scope search base narrowly
    rotate bind password
    store bind password in secret manager

passwords:
    use strong password hashing supported by product
    define password policy
    lock or disable leaver accounts quickly
    do not allow anonymous bind in production

access control:
    normal apps can read only required attributes
    password hashes are never readable by apps
    write access is limited to identity automation
    admin operations require named accounts

Keycloak bind account example:

dn:
    uid=svc-keycloak,ou=service-accounts,dc=example,dc=com

permissions:
    read people under ou=people
    read groups under ou=groups
    no password hash read
    no write by default

8. Reliability#

production baseline:
    at least 2 replicas/domain controllers
    backups tested
    replication monitored
    restore tested in isolated environment
    time sync is correct
    DNS records are stable
    certificate rotation is planned

Failure modes:

Symptom	Likely Cause	Check
login slow	LDAP search slow / network latency	query filter, index, latency
login fails for all users	bind account password expired	service bind, audit log
some groups missing	wrong group search base / nested group behavior	group mapper, filter
Keycloak cannot sync	TLS trust or bind DN issue	Keycloak logs, ldapsearch
Linux login fails	SSSD cache / Kerberos / LDAP issue	`sssctl`, `/var/log/sssd/`
replica has old data	replication lag / conflict	replication status

9. Monitoring#

must watch:
    bind success/failure rate
    search latency
    LDAP connection count
    replication lag
    disk usage
    DB/cache size
    CPU / memory
    certificate expiry
    failed admin operations

Alert examples:

Alert	Signal	Start Threshold
LDAPDown	health check / port check fails	2-5 minutes
HighBindFailure	failed bind rate	baseline + sudden spike
SlowSearch	search p95 latency	> 500 ms for 10 minutes
ReplicationLag	replica behind primary	product-specific
DiskAlmostFull	data/log volume usage	> 85%
CertExpiring	server cert expiry	< 30 days

Dashboard:

traffic:
    bind/search/modify rate
    success/failure by operation

latency:
    bind latency
    search latency
    replication delay

resource:
    CPU / memory
    disk usage
    file descriptors
    connection count

security:
    failed binds
    admin changes
    locked accounts

10. Hands-on#

Install client tools:

sudo apt-get update
sudo apt-get install -y ldap-utils

Verify anonymous RootDSE over TLS:

ldapsearch -H ldaps://ldap.example.com:636 -x -b "" -s base namingContexts supportedLDAPVersion

Verify service bind:

ldapwhoami -H ldaps://ldap.example.com:636 -x -D "uid=svc-keycloak,ou=service-accounts,dc=example,dc=com" -W

Search user:

ldapsearch -H ldaps://ldap.example.com:636 -x -D "uid=svc-keycloak,ou=service-accounts,dc=example,dc=com" -W -b "ou=people,dc=example,dc=com" "(uid=alice)" dn uid cn mail

Keycloak LDAP mapper checklist:

connection:
    LDAP URL uses ldaps:// or StartTLS
    bind DN is service account
    users DN points to people OU
    groups DN points to groups OU

identity:
    username LDAP attribute is stable
    RDN LDAP attribute matches DN model
    UUID LDAP attribute is stable
    email and name attributes mapped

groups:
    group object class matches product
    membership attribute verified
    nested group behavior understood
    token group claim size controlled

11. Readiness Criteria#

selection ready:
    product choice matches Windows/Linux/cloud requirements
    schema and group model documented
    app integration pattern decided: LDAP direct or SSO IdP layer

security ready:
    LDAPS / StartTLS enabled
    anonymous bind disabled
    bind accounts least privilege
    password policy defined
    audit logs retained

operation ready:
    replication tested
    backup / restore tested
    monitoring and alerts enabled
    certificate rotation tested
    offboarding test completed