How to setup Rancher 2.x with Active Directory external authentication

This document (000020172) is provided subject to the disclaimer at the end of this document.


Overview and Intention

This is a quick guide aiming to get Rancher v2.x using external authentication via Active Directory with the least amount of effort. Of course there is much more to consider and configure in a production enterprise environment. For more detail on this function please refer to this Rancher article and fine tune as required. Configuring Active Directory

  • A running instance of Rancher v2.x, either a single node instance or High Availability (HA) cluster.
  • Local account to log onto the Rancher Server (usually admin)
  • A Windows Server running Active Directory
  • Name of the domain you wish to join
  • A restricted account that Rancher can use to bind and query the Directory with (Security Recommendations at the bottom of article)
  • A standard user account that will be used to test and enable the authentication (i.e your domain account)
  • Knowledge of where the users are in the Active Directory OU (Organisational Unit) structure
  • Network connectivity from the Rancher worker nodes to the Active Directory Servers (There is probably more than one, run nslookup on the domain name)
  • Also good to test ports 389 or 636 (TLS) as these need to be allowed
Steps on How To Get Rancher Talking to AD Quickly
(Tested with AD running Windows Server 2016/2019)

In this example I have used the below examples (yours will be different):

  • my domain is 'rancher.local'
  • All or my users are located under the Users OU in AD
  • my bind account is 'svc-rancher'

For more detail refer to Configuring Active Directory:

  1. Log into the Rancher UI using the initial local admin account.
  2. From the Global view, navigate to Security > Authentication
  3. Select Active Directory. The Configure an AD server form will be displayed.
  4. Add in the Hostname or IP address into the Hostname field
  5. Add 'rancher/svc-rancher' to the Service Account Username field
  6. Add 'cn=users,dc=rancher,dc=local' to the User Search Base
  7. Goto Section 3 add your domain account username and password
  8. Click 'Authenticate with Active Directory'
Security tips and Best Practices

WARNING: Once enabled all users in the Search base will be able to log into Rancher.

  1. Once auth is configured in Rancher change the relaxed default setting from 'Allow any valid Users' to login to 'only allow members of Cluster, Projects' to login. Access must now be specified instead of allowing any User onto the cluster.
  2. Under 'Global, Security, Roles' It is best to drop 'New User Default' setting from 'User' to 'User Base' which provide less privleges to new users and must increased as required not as a default.
  3. The bind account is critical for ongoing authentication so locking the account will break functionality.
    • If this account gets locked or the password changes your AD authentication will be broken. Setting the account and the password not to expire and removing lockout policies prevent disruption.
    • Remove interactive logon abilites as this account doesn't need to logon to a server and control it


This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

  • Document ID:000020172
  • Creation Date: 06-May-2021
  • Modified Date:06-May-2021
    • SUSE Rancher

< Back to Support Search

For questions or concerns with the SUSE Knowledgebase please contact: tidfeedback[at]

SUSE Support Forums

Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

Join Our Community

Support Resources

Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.

SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
Support FAQ

Open an Incident

Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

Go to Customer Center