Active Directory & LDAP Integration

Instead of creating separate usernames and passwords for each employee inside Cockpit, you can connect Cockpit to your company's existing user catalog using LDAP or Microsoft Active Directory.

---

What is LDAP / Active Directory? 📇

💡 Analogy: The Company Phonebook

Imagine a large corporation with thousands of employees.

• Without LDAP: Every time a new person is hired, the office manager has to write down their name, phone number, and password in five different notebooks for different departments (creating local user accounts on every server).
• With LDAP: The company maintains one central digital phonebook (the LDAP server). When a user logs in, Cockpit simply checks their name and password against this central phonebook to see if they are a current employee.

How it Works (Step-by-Step):

1. User Logs In: A user enters their username (e.g., alice@corp.awan.io) on the Cockpit login page.
2. Cockpit Connects: Cockpit notices the @corp.awan.io domain and connects securely to your company's Active Directory server.
3. Directory Search (Bind DN): Cockpit logs in using a read-only service account (the Bind DN) to search the phonebook for "alice".
4. Password Verification: Once Cockpit finds Alice's record in the phonebook, it asks the LDAP server to verify Alice's password.
5. Group Retrieval & Permissions: If the password is correct, Cockpit looks up which departments (groups) Alice belongs to (e.g., DevOps Administrators) and gives her the corresponding access permissions.

---

Active Directory Configuration Properties

To connect Cockpit to your directory, navigate to Administration > Identity Sources in the Cockpit UI. You will need to fill in these properties, explained below:

Property	Example Value	Simple Explanation
Domain Name	corp.awan.io	The domain extension that triggers directory lookup.
LDAP URL	ldaps://ad-controller.corp.awan.io:636	The address of your Active Directory server. The ldaps part means it is secure.
Base DN	dc=corp,dc=awan,dc=io	The starting folder/point in the directory tree where search begins.
Bind DN	cn=svc-cockpit,ou=ServiceAccounts,dc=corp,dc=awan,dc=io	The username (distinguished name) of the service account Cockpit uses to search the directory.
Bind Password	********	The password for the service account above.
User Search Filter	(&(objectClass=user)(sAMAccountName={username}))	The rule Cockpit uses to find users. This search filter says: "Find a user whose login name matches the input username."
Group Search Filter	(&(objectClass=group)(member={dn}))	The rule Cockpit uses to find which groups the user belongs to.

---

Mapping Company Groups to Cockpit Permissions

Once Cockpit is connected to your company directory, you can map Active Directory groups to Cockpit user groups:

1. Log into Cockpit as an administrator.
2. Go to Access Control > Group Mappings.
3. Click Add Mapping.
4. Enter the AD/LDAP Group DN (the official directory path of the company group, e.g., cn=devops-team,ou=Groups,dc=corp,dc=awan,dc=io).
5. Select the matching Cockpit Group they should be placed in (e.g., Cluster Administrators).
6. Click Save.

Now, whenever anyone in the devops-team Active Directory group logs into Cockpit, they will automatically receive full administrator access without you needing to create a separate account for them!