Active Directory & LDAP Integration

Cockpit supports integration with external LDAP directories and Microsoft Active Directory. This allows administrators to centralize user management, utilize corporate credentials, and automate permission mapping based on directory groups.

---

Authentication Workflow

The LDAP/AD integration delegates user verification to the target directory service through a multi-stage authentication process:

1. Login Request: The user enters their credentials (e.g., user@corp.awan.io) on the Cockpit login interface.
2. Domain Routing: Cockpit identifies the domain suffix and routes the request to the configured directory service endpoint.
3. Directory Bind (Search Phase): Cockpit connects to the directory server using a system account (the Bind DN) to locate the user's Distinguished Name (DN) in the directory tree.
4. User Verification (Authentication Phase): Cockpit performs a secondary bind operation using the user's specific DN and the password provided at login.
5. Group Retrieval & Role Mapping: Upon successful verification, Cockpit queries the user's group memberships (e.g., matching the memberOf attribute) and maps them to corresponding Cockpit groups and roles.

---

Directory Configuration Properties

To configure an external directory source, navigate to Administration > Identity Sources in the Cockpit console and define the following properties:

Property	Example Value	Description
Domain Name	corp.awan.io	The domain suffix associated with the directory source.
LDAP URL	ldaps://ad-controller.corp.awan.io:636	The endpoint URI of the directory server. Use ldaps:// to secure data in transit.
Base DN	dc=corp,dc=awan,dc=io	The root DN of the directory tree where searches are executed.
Bind DN	cn=svc-cockpit,ou=ServiceAccounts,dc=corp,dc=awan,dc=io	The system service account used by Cockpit to query user records.
Bind Password	********	The password associated with the system service account Bind DN.
User Search Filter	(&(objectClass=user)(sAMAccountName={username}))	The search query used to find the user object matching the input username.
Group Search Filter	(&(objectClass=group)(member={dn}))	The query used to retrieve the group memberships associated with the user's DN.

---

Mapping Directory Groups to Cockpit Roles

To configure permission mapping for directory users:

1. Log into Cockpit with administrative credentials.
2. Navigate to Access Control > Group Mappings.
3. Select Add Mapping.
4. Input the AD/LDAP Group DN (e.g., cn=devops-team,ou=Groups,dc=corp,dc=awan,dc=io).
5. Select the target Cockpit Group (e.g., Cluster Administrators) that contains the desired roles and permissions.
6. Save the mapping configuration.

Users belonging to the specified directory group will automatically receive the mapped Cockpit permissions upon login.