From 91c28cb38701298c2f53b8815c4dad592d34605c Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Thu, 27 Feb 2020 18:44:43 -0700 Subject: [PATCH] Revise docs on Shibboleth and OpenLDAP --- .../authentication/openldap/_index.md | 69 +------- .../openldap/openldap-config/_index.md | 72 +++++++++ .../authentication/shibboleth/_index.md | 148 ++++-------------- .../authentication/shibboleth/about/_index.md | 49 ++++++ .../shibboleth-with-openldap-groups.svg | 3 + 5 files changed, 155 insertions(+), 186 deletions(-) create mode 100644 content/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config/_index.md create mode 100644 content/rancher/v2.x/en/admin-settings/authentication/shibboleth/about/_index.md create mode 100644 static/img/rancher/shibboleth-with-openldap-groups.svg diff --git a/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md index 2a59301ad9b..4338bc3f86a 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md @@ -29,79 +29,12 @@ Rancher must be configured with a LDAP bind account (aka service account) to sea > If the certificate used by the OpenLDAP 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. ## Configuration Steps -### Open OpenLDAP Configuration 1. Log into the Rancher UI using the initial local `admin` account. 2. From the **Global** view, navigate to **Security** > **Authentication** 3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed. -### Configure OpenLDAP Server Settings - -In the section titled `1. Configure an OpenLDAP server`, complete the fields with the information specific to your server. Please refer to the following table for detailed information on the required values for each parameter. - -> **Note:** -> -> If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. - -**Table 1: OpenLDAP server parameters** - -| Parameter | Description | -|:--|:--| -| Hostname | Specify the hostname or IP address of the OpenLDAP server | -| Port | Specify the port at which the OpenLDAP 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). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. | -| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. | -| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). | -| Service Account Password | The password for the service account. | -| User Search Base | Enter 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 this field empty. For example: "ou=groups,dc=acme,dc=com".| - ---- - -### Configure User/Group Schema - -If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it. -Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP. - -> **Note:** -> -> If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. - -#### User Schema - -The table below details the parameters for the user schema configuration. - -**Table 2: User schema configuration parameters** - -| Parameter | Description | -|:--|:--| -| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | -| Username Attribute | The user attribute whose value is suitable as a display name. | -| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. | -| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. | -| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP 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. | -| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. | -| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. | - ---- - -#### Group Schema - -The table below details the parameters for the group schema configuration. - -**Table 3: Group schema configuration parameters** - -| Parameter | Description | -|:--|:--| -| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | -| Name Attribute | The group attribute whose value is suitable for a display name. | -| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. | -| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. | -| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. | -| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. | -| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). | - ---- +Then configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](../openldap-config) ### Test Authentication diff --git a/content/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config/_index.md new file mode 100644 index 00000000000..047a20919e5 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config/_index.md @@ -0,0 +1,72 @@ +--- +title: OpenLDAP Configuration Reference +weight: 2 +--- + +This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher. + +For further details on configuring OpenLDAP, refer to the [official documentation.](https://www.openldap.org/doc/) + +- [OpenLDAP server configuration](#openldap-server-configuration) +- [User/group schema configuration](#user-group-schema-configuration) + - [User schema configuration](#user-schema-configuration) + - [Group schema configuration](#group-schema-configuration) + +# OpenLDAP Server Configuration + +You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic. + +If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. + +
OpenLDAP Server Parameters
+ +| Parameter | Description | +|:--|:--| +| Hostname | Specify the hostname or IP address of the OpenLDAP server | +| Port | Specify the port at which the OpenLDAP 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). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. | +| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. | +| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). | +| Service Account Password | The password for the service account. | +| User Search Base | Enter 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 this field empty. For example: "ou=groups,dc=acme,dc=com".| + +# User/Group Schema Configuration + +If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it. + +Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP. + +If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. + +### User Schema Configuration + +The table below details the parameters for the user schema configuration. + +
User Schema Configuration Parameters
+ +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Username Attribute | The user attribute whose value is suitable as a display name. | +| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. | +| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. | +| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP 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. | +| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. | +| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. | + +### Group Schema Configuration + +The table below details the parameters for the group schema configuration. + +
Group Schema Configuration Parameters
+ +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Name Attribute | The group attribute whose value is suitable for a display name. | +| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. | +| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. | +| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. | +| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). | \ No newline at end of file diff --git a/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/_index.md index 0e10c20617b..5ca461f13c7 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/_index.md @@ -5,30 +5,34 @@ weight: 1210 _Available as of v2.4.0_ +If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials. + +In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI. + +If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for. + +> The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](./about) + This section covers the following topics: -- Prerequisites for Shibboleth -- Configuring Shibboleth +- [Setting up Shibboleth in Rancher](#setting-up-shibboleth-in-rancher) + - [Shibboleth Prerequisites](#shibboleth-prerequisites) + - [Configuring Shibboleth](#configuring-shibboleth) + - [SAML Provider Caveats](#saml-provider-caveats) +- [Setting up OpenLDAP in Rancher](#setting-up-openldap-in-rancher) + - [OpenLDAP Prerequisites](#openldap-prerequisites) + - [Configuring OpenLDAP](#configuring-openldap) + - [Troubleshooting](#troubleshooting) -- About OpenLDAP -- OpenLDAP Authentication Flow -- Prerequisites for OpenLDAP -- OpenLDAP Configuration -- Configure OpenLDAP Server Settings -- Configure User/Group Schema - - User Schema - - Group Schema -- Test Authentication -- Troubleshooting +# Setting up Shibboleth in Rancher -### Prerequisites for Shibboleth +### Shibboleth Prerequisites > >- You must have a Shibboleth IdP Server configured. >- Following are the Rancher Service Provider URLs needed for configuration: Metadata URL: `https:///v1-saml/shibboleth/saml/metadata` Assertion Consumer Service (ACS) URL: `https:///v1-saml/shibboleth/saml/acs` ->- Export a `metadata.xml` file from your IdP Server. For more information, see the Shibboleth documentation. - +>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home) ### Configuring Shibboleth If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. @@ -67,24 +71,20 @@ If your organization uses Shibboleth for user authentication, you can configure **Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins. +### SAML Provider Caveats -# About OpenLDAP +If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups. -If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI. - -### OpenLDAP Authentication Flow - -1. When a user attempts to log in with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes. -2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings. -3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password. -4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute. +- There is no validation on users or groups when assigning permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of. -> **Note:** -> -> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). +To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP. +# Setting up OpenLDAP in Rancher -### Prerequisites for OpenLDAP +### OpenLDAP Prerequisites Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below). @@ -92,102 +92,14 @@ Rancher must be configured with a LDAP bind account (aka service account) to sea > > If the certificate used by the OpenLDAP 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. -### Open OpenLDAP Configuration +### Configuring OpenLDAP 1. Log into the Rancher UI using the initial local `admin` account. 2. From the **Global** view, navigate to **Security** > **Authentication** 3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed. -### Configure OpenLDAP Server Settings - -In the section titled `1. Configure an OpenLDAP server`, complete the fields with the information specific to your server. Please refer to the following table for detailed information on the required values for each parameter. - -> **Note:** -> -> If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. - -**Table 1: OpenLDAP server parameters** - -| Parameter | Description | -|:--|:--| -| Hostname | Specify the hostname or IP address of the OpenLDAP server | -| Port | Specify the port at which the OpenLDAP 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). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. | -| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. | -| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). | -| Service Account Password | The password for the service account. | -| User Search Base | Enter 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 this field empty. For example: "ou=groups,dc=acme,dc=com".| - ---- - -# Configure User/Group Schema - -If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it. -Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP. - -> **Note:** -> -> If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. - -### User Schema - -The table below details the parameters for the user schema configuration. - -**Table 2: User schema configuration parameters** - -| Parameter | Description | -|:--|:--| -| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | -| Username Attribute | The user attribute whose value is suitable as a display name. | -| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. | -| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. | -| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP 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. | -| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. | -| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. | - ---- - -### Group Schema - -The table below details the parameters for the group schema configuration. - -**Table 3: Group schema configuration parameters** - -| Parameter | Description | -|:--|:--| -| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | -| Name Attribute | The group attribute whose value is suitable for a display name. | -| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. | -| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. | -| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. | -| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. | -| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). | - ---- - -# Test Authentication - -Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful. - -> **Note:** -> -> The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step. - -1. Enter the **username** and **password** for the OpenLDAP account that should be mapped to the local principal account. -2. Click **Authenticate With OpenLDAP** to test the OpenLDAP connection and finalise the setup. - -**Result:** - -- OpenLDAP authentication is configured. -- The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account. - -> **Note:** -> -> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. +Then configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.]({{}}/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config) # Troubleshooting If you are experiencing issues while testing the connection to the OpenLDAP 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]({{}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation. - -{{< saml_caveats >}} diff --git a/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/about/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/about/_index.md new file mode 100644 index 00000000000..7af334d0c70 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/authentication/shibboleth/about/_index.md @@ -0,0 +1,49 @@ +--- +title: Group Permissions with Shibboleth and OpenLDAP +weight: 1 +--- + +_Available as of Rancher v2.4_ + +This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher. + +Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration. + +One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI. + +This section covers the following topics: + +- [Terminology] +- [OpenLDAP authentication flow] + +### Terminology + +- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships. +- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider. +- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider. +- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider. + +### Adding OpenLDAP Group Permissions to Rancher Resources + +The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for. + +For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher. + +In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported. + +When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password. + +Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups has permissions for. + +![Adding OpenLDAP Group Permissions to Rancher Resources]({{}}/img/rancher/shibboleth-with-openldap-groups.svg) + +### OpenLDAP Authentication Flow + +1. When a user attempts to log in with his or her LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes. +2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings. +3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password. +4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute. + +> **Note:** +> +> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users]({{}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). \ No newline at end of file diff --git a/static/img/rancher/shibboleth-with-openldap-groups.svg b/static/img/rancher/shibboleth-with-openldap-groups.svg new file mode 100644 index 00000000000..7f3694c842e --- /dev/null +++ b/static/img/rancher/shibboleth-with-openldap-groups.svg @@ -0,0 +1,3 @@ + + +
First-time login to Rancher
First-time...
Adding OpenLDAP Group Permissions to Rancher Resources
Adding OpenLDAP Group Permissions to Rancher Resources
Redirect user to Shibboleth
Redirect us...
Rancher
Ranch...
Shibboleth
Shibb...
OpenLDAP
OpenL...
Rancher
Admin
Ranch...
Search for groups
Search for gro...
Search for groups
Search for gro...
Provide groups to Rancher
Provide groups t...
  OpenLDAP Group Member
  OpenLDAP Group Member
Rancher admin or user with sufficient privileges can add an OpenLDAP group to a resource such as a cluster, project, or namespace.
Rancher admin or...
An existing OpenLDAP group member logs in to Rancher. Shibboleth validates credentials and provides group details from OpenLDAP.
An existing Open...
Select group for Rancher resource
Select group for...
Access resources that group has permissions for
Access resources...
User enters username and password
User enters userna...
Validate credentials
Validate creden...
Provide user details
Provide user de...
SAML assertion to Rancher with user attributes, including groups
SAML assertion...Viewer does not support full SVG 1.1 \ No newline at end of file