public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 04:28:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated AD docs

Browse Source 
- Added notes regarding the use of UPN vs. NetBIOS style login names. 
- Clarified implications of the credentials used in the the test step.
This commit is contained in:
Jan B
2018-07-20 18:50:39 -07:00
committed by Mark Bishop
parent 8a4ff42b28
commit a6e5975726
1 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md
+23 -17
View File
@@ -5,7 +5,9 @@ aliases:
- /rancher/v2.x/en/tasks/global-configuration/authentication/active-directory/
---
Rancher can be configured to communicate with an existing Microsoft Active Directory server for the purpose user authentication. This allows users to use their AD account credentials for login into the Rancher UI as well as managing access to clusters and projects based on AD user identity or group membership.
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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/openldap) integration.
> **Note:**
>
@@ -13,11 +15,11 @@ Rancher can be configured to communicate with an existing Microsoft Active Direc
## Prerequisites
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 searches and read attributes of users and groups under your AD domain.
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 privileges to view, but not modify other objects in the domain partition.
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 both **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.
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?**
>
@@ -46,9 +48,9 @@ In the section titled `1. Configure an Active Directory server`, complete the
| Port | Specify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS).|
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the AD server unreachable. |
| Service Account Username | Enter the username of an AD account with read(-only) access to your domain partition that will be used by Rancher to lookup users and groups (see [Prerequisites](#prerequisites)). You must specify this username in the logon (slashed) format, e.g. "mydomain\rancheruser". |
| Service Account Username | Enter the username of an AD account with read-only access to your domain partition (see [Prerequisites](#prerequisites)). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com"). |
| Service Account Password | The password for the service account. |
| Default Login Domain | Enter your AD domain, e.g. "acme". |
| Default Login Domain | When you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field **must** be left empty. |
| User Search Base | The Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".|
@@ -74,9 +76,9 @@ The table below details the parameters for the user schema section configuration
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of your users AD credentials, ie. what they would enter when logging in to Rancher. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. |
| User Member Attribute | The attribute containing the groups that a user is a member of. |
| Search Attribute | When a user enters text to add users or groups, Rancher queries the AD server and attempts to match fields by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. As of Rancher v2.0.1, this parameter defaults to: "sAMAccountName\|sn\|givenName".|
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. |
| User Enabled Attribute | The attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard `userAccountControl`. |
| Disabled Status Bitmask | This is the value of the `User Enabled Attribute` designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see [here](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)). |
@@ -102,23 +104,23 @@ The table below details the parameters for the group schema configuration.
### Test Authentication
When you have completed the configuration, proceed by testing the connection to the AD server with your own AD credentials.
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:**
>
> On completing this step of the configuration, the AD user pertaining to the credentials entered here will be mapped to the local principal account. You should therefore ensure to specifically enter credentials of an AD account that you want to be assigned the administrative role in Rancher going forward.
> 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.
1. Enter the **username** and **password** for your AD account.
2. Click **Authenticate with Active Directory** to test the Active Directory connection and map this user to the local admin account.
1. Enter the **username** and **password** for the AD account that should be mapped to the local principal account.
2. Click **Authenticate with Active Directory** to finalise the setup.
**Result:**
- AD authentication is configured.
- You are signed into Rancher with your AD account (mapped to the local user assigned the administrator role, ie. the local principal account).
- Active Directory authentication has been enabled.
- You have been signed into Rancher as administrator using the provided AD credentials.
> **Note:**
>
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of AD services.
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services.
## Annex: Identify Search Base and Schema using ldapsearch
@@ -159,7 +161,11 @@ The output of the above `ldapsearch` query also allows to determine the correct
- `Login Attribute`: **sAMAccountName** [3]
- `User Member Attribute`: **memberOf** [4]
With regards to the `Search Attribute` parameter, it makes sense here to set it to **sAMAccountName|name**. This will allow users to be added in the Rancher UI both by entering their username or full name.
> **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.
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.
### Identify Group Schema
@@ -188,4 +194,4 @@ In the same way, we can observe that the value in the **memberOf** attribute in
## Annex: Troubleshooting
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 issue cause. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
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]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.