Illumina Innovates with Rancher and Kubernetes
If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.
Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the OpenLDAP authentication integration.
Note: Before you start, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.
Note:
Before you start, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.
You’ll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.
Usually a (non-admin) Domain User account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.
Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least Read and List Content permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.
Using TLS? If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
Using TLS?
If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
admin
In the section titled 1. Configure an Active Directory server, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.
1. Configure an Active Directory server
Note: If you are unsure about the correct values to enter in the user/group Search Base field, please refer to Identify Search Base and Schema using ldapsearch.
If you are unsure about the correct values to enter in the user/group Search Base field, please refer to Identify Search Base and Schema using ldapsearch.
Table 1: AD Server parameters
User Search Base
In the section titled 2. Customize Schema you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.
2. Customize Schema
Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.
Note: If you are unfamiliar with the schema used in your Active Directory domain, please refer to Identify Search Base and Schema using ldapsearch to determine the correct configuration values.
If you are unfamiliar with the schema used in your Active Directory domain, please refer to Identify Search Base and Schema using ldapsearch to determine the correct configuration values.
The table below details the parameters for the user schema section configuration.
Table 2: User schema configuration parameters
userPrincipalName
sAMAccountName
userAccountControl
User Enabled Attribute
The table below details the parameters for the group schema configuration.
Table 3: Group schema configuration parameters
Group Member Mapping Attribute
Search Attribute
User Member Attribute
Once you have completed the configuration, proceed by testing the connection to the AD server. Authentication with the configured Active Directory will be enabled implicitly if the test is successful.
Note: The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned admin privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.
The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned admin privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.
Result:
Note: You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.
You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.
In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hirarchy and schema of your AD server.
The ldapsearch tool allows you to query your AD server to learn about the schema used for user and group objects.
ldapsearch
For the purpose of the example commands provided below we will assume:
ad.acme.com
389
acme
jdoe
secret
First we will use ldapsearch to identify the Distinguished Name (DN) of the parent node(s) for users and groups:
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ -h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"
This command performs an LDAP search with the search base set to the domain root (-b "dc=acme,dc=com") and a filter targeting the user account (sAMAccountNam=jdoe), returning the attributes for said user:
-b "dc=acme,dc=com"
sAMAccountNam=jdoe
Since in this case the user’s DN is CN=John Doe,CN=Users,DC=acme,DC=com [5], we should configure the User Search Base with the parent node DN CN=Users,DC=acme,DC=com.
CN=John Doe,CN=Users,DC=acme,DC=com
CN=Users,DC=acme,DC=com
Similarly, based on the DN of the group referenced in the memberOf attribute [4], the correct value for the Group Search Base would be the parent node of that value, ie. OU=Groups,DC=acme,DC=com.
OU=Groups,DC=acme,DC=com
The output of the above ldapsearch query also allows to determine the correct values to use in the user schema configuration:
Object Class
Username Attribute
Login Attribute
Note: If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the Login Attribute to userPrincipalName instead.
If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the Login Attribute to userPrincipalName instead.
We’ll also set the Search Attribute parameter to sAMAccountName|name. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.
Next, we’ll query one of the groups associated with this user, in this case CN=examplegroup,OU=Groups,DC=acme,DC=com:
CN=examplegroup,OU=Groups,DC=acme,DC=com
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ -h ad.acme.com -b "ou=groups,dc=acme,dc=com" \ -s sub "CN=examplegroup"
This command will inform us on the attributes used for group objects:
Again, this allows us to determine the correct values to enter in the group schema configuration:
Name Attribute
Looking at the value of the member attribute, we can see that it contains the DN of the referenced user. This corresponds to the distinguishedName attribute in our user object. Accordingly will have to set the value of the Group Member User Attribute parameter to this attribute.
Group Member User Attribute
In the same way, we can observe that the value in the memberOf attribute in the user object corresponds to the distinguishedName [5] of the group. We therefore need to set the value for the Group DN Attribute parameter to this attribute.
Group DN Attribute
If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.