In environments using Microsoft Active Directory (AD), you can configure Rancher to allow sign on using AD credentials.
- Create a service account in Active Directory with
read-onlyaccess. Rancher uses this account to verify group membership when a user makes a request using an API key.
- Read External Authentication Configuration and Principal Users.
Sign into Rancher using a local user assigned
administratorglobal permissions (i.e., the local principal).
From the Global view, select Security > Authentication from the main menu.
Select Active Directory.
Complete the Configure an Active Directory server form.
You may need to log in to your domain controller to find the information requested in the form.
Using TLS? Make sure you have an LDAP certificate installed.
User Search Base vs. Group Search Base
When configuring AD authentication, you must enter a search base for your users. This search base allows Rancher to search for users that are in your Active Directory.
Note: This field is only for search bases and not for search filters.
- If your users and groups are in the search base, complete only the User Search Base.
- If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
If your Active Directory deviates from the standard AD schema, complete the Customize Schema form to match it. Otherwise, skip this step.
Search Attribute As of Rancher v2.0.1, the Search Attribute field defaults with three specific values by default:
sAMAccountName|sn|givenName. After AD is configured, when a user enters text to add users or groups, Rancher automatically queries the AD server and attempts to match fields by sAMAccountName, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
The default field value
sAMAccountName|sn|givenName, but you can configure this field to a subset of these fields. The pipe (
|) between the fields separates these fields.
sn: Last Name
givenName: First Name
With this search attribute, Rancher creates search filters for users and groups, but you cannot add your own search filters in this field.
Enter your AD username and password in Test and enable authentication to confirm that Rancher is configured to use AD authentication.
- Active Directory authentication is configured.
- You are signed into Rancher with your Active Directory account (i.e., the external principal).