updates based on users and groups and user refresh

2026-09-24 20:18:18 +00:00 · 2019-03-25 22:05:23 -07:00
parent c6df1c3753
commit 29223da65b
11 changed files with 66 additions and 65 deletions
@@ -12,7 +12,7 @@ This centralized user authentication is accomplished using the Rancher authentic

 <!-- todomark add diagram -->

-### External vs. Local Authentication
+## External vs. Local Authentication

 The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted.

@@ -28,11 +28,19 @@ The Rancher authentication proxy integrates with the following external authenti
 | [Keycloak]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/keycloak/)              | v2.1.0           |
 | [Okta]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/okta/)                      | v2.2.0           |
 <br/>
-However, Rancher also provides local authentication.
+However, Rancher also provides [local authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/local/).

-In most cases, you should use an external authentication service over local, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if Active Directory is down.
+In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if Active Directory is down.

-### External Authentication Configuration and Principal Users
+## Users and Groups
+
+Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users, who are a member of that group in the authentication provider, will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).
+
+> **Note:** Local authentication does not support creating or managing groups.
+
+For more information, see [Users and Groups]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/user-groups/)
+
+## External Authentication Configuration and Principal Users

 Configuration of external authentication requires:

@@ -171,7 +171,7 @@ As your final step in Azure, copy the data that you'll use to configure Rancher

 From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.

-Enter the values that you copied to your [text file]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/azure-ad/#tip).
+Enter the values that you copied to your [text file](#tip).

 1. Log into Rancher. From the **Global** view, select **Security > Authentication**.

@@ -58,13 +58,7 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati

 **Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.

->**Keycloak Identity Provider Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to 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.
+{{< saml_caveats >}}

 ## Annex: Troubleshooting

@@ -1,12 +1,16 @@
 ---
-title: Configuring Local Authentication
+title: Local Authentication
 weight: 1111
 aliases:
    - /rancher/v2.x/en/tasks/global-configuration/authentication/local-authentication/
 ---

+Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Ranchehr. By default, the `admin` user that logs in to Rancher for the first time is a local user.
+
+## Adding Local Users
+
 Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.

-1.	From the **Global** view, select **Users** from the main menu.
+1.	From the **Global** view, select **Users** from the navigation bar.

 2.	Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done.
@@ -30,12 +30,7 @@ Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on you
 - [1 — Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
 - [2 — Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)

->**Active Directory Federation Service Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to 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.
+{{< saml_caveats >}}


 ### [Next: Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
@@ -47,10 +47,4 @@ Setting | Value

 **Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.

->**Okta Identity Provider Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to 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.
+{{< saml_caveats >}}
@@ -45,9 +45,4 @@ If your organization uses Ping Identity Provider (IdP) for user authentication,

 **Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.

->**Ping Identity Provider Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to 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.
+{{< saml_caveats >}}
@@ -1,42 +1,51 @@
 ---
 title: Users and Groups
-weight: 1215
+weight: 1
 ---

+Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.

-## Managing Users and Groups
+Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).

-When you configure an authentication provider, users from that provider will be able to log into your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.
+## Managing Members

-Access to cluster, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to the resource. When you add a group to a resources, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see  [Role Based Access Control]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).
+When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/local/) user account, you will not be able to search for GitHub users or groups.

-When adding a new member to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered.
+All users, whether they are local users or from an authentication provider, can be viewed and managed. From the **Global** view, click on **Users**.

-> **NOTE:** SAML-based authentication providers do not support user or group search. The only groups that you will see with these providers are the ones to which you belong. The only users you will see are ones that have already logged into your Rancher server.
+{{< saml_caveats >}}

-> **NOTE:** Searching is limited to the authentication provider you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a local user account, you will not be able to search for GitHub users or groups.
+## User Information

-All users, whether they are local or from an authentication provider, can be viewed and managed from the **Global** **Users** page. New local users can be added from this page as well.
+Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.

+Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.

-> **NOTE:** Local authentication does not support creating or managing groups.
-
-## Refreshing User Information
+### Automatically Refreshing User Information

 _Available as of v2.2.0_

-Rancher maintains information about each user that logs in through an authentication provider. This information includes a list of groups that the user belongs to and whether the user is allowed to access your Rancher server. Rancher does this so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.
+Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh.  From the **Global** view, click on **Settings**. Two settings control this behavior:

-When a user logs into the UI using an authentication provider, Rancher automatically updates this user information. Additionally, Rancher will periodically refresh this user information. You can contol how often Rancher performs this refresh by navigating to the **Global** **Settings** page. Two settings control this behavior:
+- **`auth-user-info-max-age-seconds`**

- **auth-user-info-max-age-seconds**
+    This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This settting defaults to `3600` seconds, i.e. 1 hour.

-    This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This settting defaults to `3600` seconds (1 hour).
+- **`auth-user-info-resync-cron`**

- **auth-user-info-resync-cron**
+    This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *`, i.e. once a day at midnight. See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting.

-    This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *` (once a day at midnight). See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting.

-It is also possible to manually refresh user information from the **Global** **Users** page.
+> **Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.

-> **NOTE:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.
+### Manually Refreshing User Information
+
+If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.
+
+1. From the **Global** view, click on **Users** in the navigation bar.
+
+1. Click on **Refresh Global Memberships**.
+
+**Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.
+
+>**Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.
@@ -24,13 +24,6 @@ The following table lists the options and settings available for each cluster ty

 Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.

->**Ping and MS FS Caveats:**
->
->- IdP does not support search or lookup. When adding users to clusters, the exact IDs must be entered correctly.
->- When adding users to a cluster, group IDs are not supported unless the admin who turned on access control is a member of the group.
->- When adding a group that includes an admin to clusters, add it from the drop-down rather than the search bar. If you add the group using the search bar, the group will not get added.
-
-
 1. From the **Global** view, open the cluster that you want to add members to.

 2. From the main menu, select **Members**. Then click **Add Member**.
@@ -12,12 +12,6 @@ After projects are created, there are certain aspects that can be changed later.

 Following project creation, you can add users as project members so that they can access its resources.

->**Ping, Keycloak, and MS FS Caveats:**
->
->- IdP does not support search or lookup. When adding users to projects, the exact IDs must be entered correctly.
->- When adding users to a project, group IDs are not supported unless the admin who turned on access control is a member of the group.
->- When adding a group that includes an admin to projects, add it from the drop-down rather than the search bar. If you add the group using the search bar, the group will not get added.
-
 1. From the **Global** view, open the project that you want to add members to.

 2. From the main menu, select **Members**. Then click **Add Member**.
@@ -0,0 +1,15 @@
+
+<blockquote>
+<p><strong>SAML Provider Caveats:</strong></p>
+
+<ul>
+<li>SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.</li>
+<li>When adding users, the exact user IDs (i.e. <code>UID Field</code>) must be entered correctly. As you type the user ID, there will be no search for other  user IDs that may match.</li>
+
+<li><p>When adding groups, you <em>must</em> 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.</p>
+
+<ul>
+<li>The group drop-down shows <em>only</em> the groups that you are a member of. You will not be able to add groups that you are not a member of.</li>
+</ul></li>
+</ul>
+</blockquote>