From a8dd9b811bb0ebfa91c284e4a3ce3745b0cc3af7 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Fri, 1 Jun 2018 17:03:48 -0700 Subject: [PATCH] added diagrams and better explanation --- .../concepts/global-configuration/_index.md | 44 +++++++++++++--- .../authentication/_index.md | 47 ++++++------------ src/img/rancher/principal-ID.png | Bin 0 -> 9148 bytes src/img/rancher/sign-in-external.png | Bin 0 -> 11186 bytes src/img/rancher/sign-in.png | Bin 0 -> 17798 bytes src/img/rancher/sign-out-local.png | Bin 0 -> 10837 bytes src/img/rancher/users-page.png | Bin 0 -> 12538 bytes 7 files changed, 53 insertions(+), 38 deletions(-) create mode 100644 src/img/rancher/principal-ID.png create mode 100644 src/img/rancher/sign-in-external.png create mode 100644 src/img/rancher/sign-in.png create mode 100644 src/img/rancher/sign-out-local.png create mode 100644 src/img/rancher/users-page.png diff --git a/content/rancher/v2.x/en/concepts/global-configuration/_index.md b/content/rancher/v2.x/en/concepts/global-configuration/_index.md index 92f355363ed..7d5e983d68c 100644 --- a/content/rancher/v2.x/en/concepts/global-configuration/_index.md +++ b/content/rancher/v2.x/en/concepts/global-configuration/_index.md @@ -5,6 +5,7 @@ weight: 2075 After installing Rancher 2.0, you should configure it to support your users and environment. This section describes the global configurations you should make after installation. ## Authentication + One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters. This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account. @@ -20,21 +21,50 @@ The Rancher authentication proxy integrates with the following external authenti However, Rancher also provides local authentication. -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 accounts 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, 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 + +Configuration of external authentication requires: + +- A local user assigned the administrator role, called hereafter the _local principal_. +- An external user that can authentication with your external authentication service, called hereafter the _external principal_. + +Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects. + +1. Sign into Rancher as the local principal and complete configuration of external authentication. + + ![Sign In]({{< baseurl >}}/img/rancher/sign-in.png) + +2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID. + + ![Principal ID Sharing]({{< baseurl >}}/img/rancher/principal-ID.png) + +3. After you complete configuration, Rancher automatically signs out the local principal. + + ![Sign Out Local Principal]({{< baseurl >}}/img/rancher/sign-out-local.png) + +4. Then, Rancher automatically signs you back in as the external principal. + + ![Sign In External Principal]({{< baseurl >}}/img/rancher/sign-in-external.png) + +5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page. + + ![Sign In External Principal]({{< baseurl >}}/img/rancher/users-page.png) + +6. The external principal and the local principal share the same access rights. -<<<<<<< HEAD ## Users, Global Permissions, and Roles Within Rancher, each user authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned previously, users can either be local or external. -======= -You should know a few things about external authentication: -- When you configure AD or GitHub authentication, Rancher binds your current user account to the AD or GitHub account you're using to authenticate with Rancher. In other words, if you want to log into Rancher using the AD or GitHub account that you used to configure external authentication, you must use the local user account that's bound to your AD/GitHub account. +After you configure external authentication, the users that display on Users page changes. -- If you are signed into Rancher with a local user account, AD/GitHub accounts are not listed on the **Users** page. You must be assigned with an AD/GitHub account to view AD/GitHub users in Rancher. Additionally, The AD/GitHub account +- If you are logged in as a local user, only local users display. + +- If you are logged in an an external user, both external and local users display. ## Users and Roles ->>>>>>> documenting user account behavior during external auth setup Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by _global permissions_, and _cluster and project roles_. diff --git a/content/rancher/v2.x/en/tasks/global-configuration/authentication/_index.md b/content/rancher/v2.x/en/tasks/global-configuration/authentication/_index.md index fc52e302245..51598e9192f 100644 --- a/content/rancher/v2.x/en/tasks/global-configuration/authentication/_index.md +++ b/content/rancher/v2.x/en/tasks/global-configuration/authentication/_index.md @@ -22,13 +22,12 @@ You have three options for user authentication in {{< product >}}: In environments using Microsoft Active Directory (AD), you can configure Rancher to allow sign on using AD credentials. >>>>>>> documenting user account behavior during external auth setup ->**Prerequisites:** Create a service account in Active Directory with **read-only** access. {{< product >}} uses this account to verify group membership when a user makes a request using an API key. +>**Prerequisites:** +> +>- Create a service account in Active Directory with `read-only` access. {{< product >}} uses this account to verify group membership when a user makes a request using an API key. +>- Read [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/#external-authentication-configuration-and-principal-users). ->**Tip**: This procedure binds the logged-in user [local administrative user account](#to-configrue-local-authentication) to an Active Directory account. Therefore, we recommend creating both a new local administrative user account and a new Active Directory account that mirror each other. Use these accounts solely to integrate Active Directory authetication with Rancher. - -1. Sign into Rancher using a local administrative account (i.e. `Default Admin` or another administrative account that you create). - - In upcoming steps, you'll bind this local account to an Active Directory account. +1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). 2. From the **Global** view, select **Security > Authentication** from the main menu. @@ -38,10 +37,6 @@ In environments using Microsoft Active Directory (AD), you can configure Rancher 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](placeholder.md). - >**User Search Base vs. Group Search Base** > >When configuring AD authentication, you must enter a search base for your users. This base allows Rancher to search for users that are in your Active Directory. @@ -55,29 +50,22 @@ In environments using Microsoft Active Directory (AD), you can configure Rancher **Result:** - Active Directory authentication is configured. -- You are signed into Rancher with your Active Directory account. -- Your Active Directory account is associated with the local administrator that you used to configure external autentication. Note that your Active Directory account _is not_ listed on the **Users** page. Edit the local user that the Active Directory user is bound to instead. - ->**Note:** After successfully configuring Active Directory authentication, Active Directory accounts only display on the **Users** page if you are signed in using an Active Directory account or the local account you used to configure Active Directory authentication. If you are signed in with any other local user account, Active Directory accounts do not display. +- You are signed into Rancher with your Active Directory account (i.e., the _external principal_). ### Configuring GitHub Authentication In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials. ->**Tip**: This procedure binds a [local administrative user account](#to-configrue-local-authentication) to a GitHub account. Therefore, we recommend creating both a new local administrative user account and a new GitHub account that mirror each other. Use these accounts solely to integrate GitHub authetication with Rancher. +- Read [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/#external-authentication-configuration-and-principal-users) -1. Sign into GitHub using an account you want use to authenticate with Rancher. +1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). -2. Sign into Rancher using a local administrative account (i.e. `Default Admin` or another administrative account that you create). +2. From the **Global** view, select **Security > Authentication** from the main menu. - In upcoming steps, you'll bind this local account to the GitHub account from the previous step. +3. Select **GitHub**. -3. From the **Global** view, select **Security > Authentication** from the main menu. - -4. Select **GitHub**. - -5. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration. +4. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration. >**What's an Authorization Callback URL?** > @@ -85,15 +73,15 @@ In environments using GitHub, you can configure Rancher to allow sign on using G >When you use external authentication, sign on authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authorization completes successfully, the Authorization Callback URL is the location that the user reenters your application. -6. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into {{< product >}}. +5. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into {{< product >}}. >**Where do I find the Client ID and Client Secret?** > >From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. -7. Click **Authenticate with GitHub**. +6. Click **Authenticate with GitHub**. -8. Use the **Site Access** options to configure the scope of user authorization. +7. Use the **Site Access** options to configure the scope of user authorization. - **Allow any valid Users** @@ -107,15 +95,12 @@ In environments using GitHub, you can configure Rancher to allow sign on using G Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.
-9. Click **Save**. +8. Click **Save**. **Result:** - GitHub authentication is configured. -- You are signed into Rancher with your GitHub account. -- Your GitHub account is associated with the local administrator that you used. Note that your GitHub account _is not_ listed on the **Users** page. Edit the local user that the GitHub account is bound to instead. - ->**Note:** After successfully configuring GitHub authentication, GitHub accounts only display on the **Users** page if you are signed in using a GitHub account or the local account you used to configure GitHub authentication. If you are signed in with any other local user account, GitHub accounts do not display. +- You are signed into Rancher with your GitHub account (i.e., the _external principal_).