Rancher LDAP Authentication Setup Guide

Step‑by‑step guide to connect Rancher to an LDAP server for centralized authentication and role‑based access control.

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

Log in to Rancher as an admin and open Global > Security > Authentication.
Select LDAP as the authentication provider.
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).

Click Test Connection to verify Rancher can reach the LDAP server and retrieve a test user.
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.
Save the configuration.

Expected Checks

Log out of Rancher and log back in using an LDAP user’s username and password.
Confirm the username appears in the top‑right corner of the UI.
Navigate to Global > Security > Groups and verify the LDAP groups are listed with the correct Rancher role assignments.
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:

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"}}'

This reverts authentication to the local database, allowing you to log in with the local admin account.
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

Trust the LDAP TLS Certificate

If you connect over LDAPS, Rancher will reject the connection unless the server’s certificate is trusted by the host’s certificate store. Add the CA to /etc/ssl/certs or use ldap:// with a valid Server URL. A failed “Test Connection” will show a TLS error.

Pick the Correct Login Attribute

The Login Attribute must match the attribute that users actually use to log in. For OpenLDAP it’s usually uid; for Windows AD it’s often sAMAccountName or userPrincipalName if you prefer UPN logins.

Verify Group Member Attribute

Role mapping relies on the LDAP group object exposing a member attribute that contains each user’s DN. Common values are member (RFC 2307) or uniqueMember (RFC 2307bis). If your directory uses a different attribute, Rancher will not see the group memberships.

Quick Validation

Run ldapsearch against the bind DN and user base to confirm the bind works.
Use Rancher’s “Test Connection” after entering TLS and bind details.
Log in with a test user and check the assigned role in Global → Security → Groups.

Configure Rancher LDAP Authentication for Centralized User Management