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

Table of Contents

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
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.