Configure Rancher LDAP Authentication for Centralized User Management

Desired Outcome

Enable Rancher to authenticate users against an external LDAP directory and assign Rancher roles based on LDAP group membership, so administrators manage credentials in one place.

Prerequisites

• A Rancher server version 2.6 or later running and accessible.
• Network connectivity from the Rancher server to the LDAP server (typically TCP 389 or 636 for LDAPS).
• A read‑only LDAP service account (bind DN) with permission to search the user and group bases.
• Administrator access to the Rancher UI or API.

Procedure

1. Log in to Rancher as an admin and open Global > Security > Authentication.
2. Select LDAP as the authentication provider.
3. Fill in the fields:
• Server URL: ldap://ldap.example.com or ldaps://ldap.example.com:636
• Bind DN: cn=rancherbind,ou=serviceAccounts,dc=example,dc=com
• Bind Password: the password for the service account.
• User Search Base: ou=Users,dc=example,dc=com
• Login Attribute: usually uid or sAMAccountName.
• Group Search Base: ou=Groups,dc=example,dc=com
• Group Member Attribute: member (or uniqueMember for some directories).
4. Click Test Connection to verify Rancher can reach the LDAP server and retrieve a test user.
5. Under Role Mapping, add LDAP groups and select the Rancher role (e.g., admin, member, read-only) that should be granted to members of each group.
6. Save the configuration.

Expected Checks

1. Log out of Rancher and log back in using an LDAP user’s username and password.
2. Confirm the username appears in the top‑right corner of the UI.
3. Navigate to Global > Security > Groups and verify the LDAP groups are listed with the correct Rancher role assignments.
4. Attempt an action that requires a role the user does not have (e.g., create a cluster with a user mapped only to read-only) and verify the operation is denied.

Recovery / Rollback

If LDAP authentication prevents admin access:

1. Disable LDAP via the Rancher API (requires direct API access or a local admin account that still exists). Example request:

curl -k -u "local-admin:local-password" \
  -X PUT "https://rancher.example.com/v3/settings/auth-config" \
  -H "Content-Type: application/json" \
  -d '{"value":{"type":"local"}}'

2. This reverts authentication to the local database, allowing you to log in with the local admin account.
3. Re‑enable LDAP after correcting the connection details (e.g., fixing the bind DN or network issue) and repeat the procedure.

As a precaution, export the current auth settings before making changes:

curl -k -u "local-admin:local-password" \
  -X GET "https://rancher.example.com/v3/settings/auth-config" \
  -o auth-config-backup.json