From 42c2db96634ea6520929223c5201c9c1b8d62ab4 Mon Sep 17 00:00:00 2001 From: Max Sokolovsky Date: Fri, 17 Feb 2023 15:48:59 +0000 Subject: [PATCH 1/7] Update Azure AD documentation, change permission requirements --- .../configure-azure-ad.md | 118 +++++++++--------- 1 file changed, 58 insertions(+), 60 deletions(-) diff --git a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md index afa1938f806..a463481f90d 100644 --- a/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.6/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -2,13 +2,15 @@ title: Configure Azure AD --- - - + + ## Microsoft Graph API Microsoft Graph API is now the flow through which you will set up Azure AD. The below sections will assist [new users](#new-user-setup) in configuring Azure AD with a new instance as well as assist existing Azure app owners in [migrating to the new flow](#migrating-from-azure-ad-graph-api-to-microsoft-graph-api). +The Microsoft Graph API flow in Rancher is constantly evolving. We recommend that you use the latest patched version of 2.6, as it is still in active development and will continue to receive new features and improvements. + ### New User Setup If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher. @@ -26,7 +28,7 @@ Configuring Rancher to allow your users to authenticate with their Azure AD acco :::tip -Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later. +Before you start, open two browser tabs: one for Rancher, and one for the Azure portal. This will help with copying and pasting configuration values from the portal to Rancher. ::: @@ -39,9 +41,7 @@ Before enabling Azure AD within Rancher, you must register Rancher with Azure. 1. Use search to open the **App registrations** service. - ![Open App Registrations](/img/search-app-registrations.png) - -1. Click **New registrations** and complete the **Create** form. +1. Click **New registration** and complete the form. ![New App Registration](/img/new-app-registration.png) @@ -80,20 +80,17 @@ From the Azure portal, create a client secret. Rancher will use this key to auth ![Open Rancher Registration](/img/open-rancher-app-reg.png) -1. From the navigation pane on left, click **Certificates and Secrets**. +1. From the navigation pane, click **Certificates & secrets**. 1. Click **New client secret**. ![Create new client secret](/img/new-client-secret.png) 1. Enter a **Description** (something like `Rancher`). -1. Select duration for the key from the options under **Expires**. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration. +1. Select the duration from the options under **Expires**. This drop-down menu sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key more frequently. +Note that users won't be able to log in to Rancher if it detects that the application secret has expired. To avoid this problem, rotate the secret in Azure and update it in Rancher before it expires. 1. Click **Add** (you don't need to enter a value—it will automatically populate after you save). -1. Copy the key value and save it to an [empty text file](#tip). - - You'll enter this key into the Rancher UI later as your **Application Secret**. - - You won't be able to access the key value again within the Azure UI. +1. You'll enter this key into the Rancher UI later as your **Application Secret**. Since you won't be able to access the key value again within the Azure UI, keep this window open for the rest of the setup process. #### 3. Set Required Permissions for Rancher @@ -101,86 +98,80 @@ Next, set API permissions for Rancher within Azure. :::caution -Ensure that you set the permissions of type Application and NOT Delegated. Otherwise, you may not be able to login to Azure AD. This issue will persist even after you disable/re-enable Azure AD and will require an hour wait, or manual deletion of a cache value to resolve. +Ensure that you set Application permissions, and *not* Delegated permissions. Otherwise, you won't be able to login to Azure AD. ::: -1. From the navigation pane on left, select **API permissions**. - - ![Open Required Permissions](/img/select-req-permissions.png) +1. From the navigation pane on, select **API permissions**. 1. Click **Add a permission**. -1. From the **Microsoft Graph**, select the following **Application Permissions**: - - `Group.Read.All` - - `User.Read.All` +1. From the Microsoft Graph API, select the following **Application Permissions**: `Directory.Read.All` - ![Select API Permissions](/img/api-permissions-2-6.png) + ![Select API Permissions](/img/api-permissions.png) -1. Return to **API permissions** in the left nav bar. From there, click **Grant admin consent**. Then click **Yes**. +:::note - :::note +In Rancher versions 2.6.7-2.6.10, you'll need to use `User.Read.All` and `Group.Read.All` for permissions. This was changed to allow for lower-scoped permissions (such as `Directory.Read.All`) in v2.6.11. - You must be signed in as an Azure administrator to successfully save your permission settings. +::: - ::: +1. Return to **API permissions** in the nav bar. From there, click **Grant admin consent**. Then click **Yes**. The app's permissions should look like the following: + +![Open Required Permissions](/img/select-req-permissions.png) + +:::note + +Rancher doesn't validate the permissions you grant to the app in Azure. We only support the use of the `Directory.Read.All` application permission. + +::: #### 4. Copy Azure Application Data -As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file. +![Application ID](/img/app-configuration.png) 1. Obtain your Rancher **Tenant ID**. 1. Use search to open **App registrations**. - ![Open App Registrations](/img/search-app-registrations.png) - 1. Find the entry you created for Rancher. - 1. Copy the **Directory ID** and paste it into your [text file](#tip). - - ![Tenant ID](/img/tenant-id.png) - - - You'll paste this value into Rancher as your **Tenant ID**. + 1. Copy the **Directory ID** and paste it into Rancher as your **Tenant ID**. 1. Obtain your Rancher **Application (Client) ID**. - 2.1. Use search to open **App registrations** (if not already there). + 1. If you aren't already there, use search to open **App registrations**. - 2.2. In **Overview**, find the entry you created for Rancher. + 1. In **Overview**, find the entry you created for Rancher. - 2.3. Copy the **Application (Client) ID** and paste it to your [text file](#tip). + 1. Copy the **Application (Client) ID** and paste it into Rancher as your **Application ID**. - ![Application ID](/img/application-client-id.png) - -1. Your endpoint options will typically be [Standard](#global) and [China](#china). With these options, you need only enter the **Tenant ID**, **Application ID**, and **Application Secret** (Rancher will take care of the rest). +1. In most cases, your endpoint options will either be [Standard](#global) or [China](#china). For either of these options, you only need to enter the **Tenant ID**, **Application ID**, and **Application Secret**. ![Standard Endpoint Options](/img/tenant-application-id-secret.png) **For Custom Endpoints:** -**Warning:** Custom Endpoints are not supported nor fully tested by Rancher. +**Warning:** Custom Endpoints are not tested or fully supported by Rancher. -You will need to also manually enter the Graph, Token, and Auth Endpoints. +You'll also need to manually enter the Graph, Token, and Auth Endpoints. - From App registrations, click Endpoints: ![Click Endpoints](/img/endpoints.png) -- Copy the following endpoints to your clipboard and paste them into your [text file](#tip) (these values will be your Rancher endpoint values). Make sure to copy the v1 version of the endpoints. +- The following endpoints will be your Rancher endpoint values. Make sure to use the v1 version of these endpoints: - **Microsoft Graph API endpoint** (Graph Endpoint) - **OAuth 2.0 token endpoint (v1)** (Token Endpoint) - **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint) #### 5. Configure Azure AD in 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](#tip). +To complete configuration, enter information about your AD instance in the Rancher UI. 1. Log into Rancher. -1. In the top left corner, click **☰ > Users & Authentication**. -1. In the left navigation menu, click **Auth Provider**. +1. In the upper left corner of the toolbar, click **☰ > Users & Authentication**. +1. In the nav menu, click **Auth Provider**. 1. Click **AzureAD**. 1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#4-copy-azure-application-data). @@ -206,7 +197,7 @@ The following table maps the custom config values you copied in the Azure portal **Important:** When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL, like below: -https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c +https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c 1. Click **Enable**. @@ -215,14 +206,19 @@ The following table maps the custom config values you copied in the Azure portal ### Migrating from Azure AD Graph API to Microsoft Graph API -Since [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) was deprecated in June 2022 and will be retired at the end of 2022, users should update their Azure AD App to use the new [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) in Rancher. +Since the [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) is deprecated and slated to retire in June 2023, admins should update their Azure AD App to use the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) in Rancher. +This needs to be done well in advance of the endpoint being retired. +If Rancher is still configured to use the Azure AD Graph API when it is retired, users may not be able to log into Rancher using Azure AD. #### Updating Endpoints in the Rancher UI ->**Important:** Admins should create a [backup](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) right before they commit to the endpoint migration in Step 4 below. +:::caution -1. Update the permissions of your Azure AD app registration as described [here](#3-set-required-permissions-for-rancher). -**This is critical.** +Admins should create a [Rancher backup](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) before they commit to the endpoint migration described below. + +::: + +1. [Update](#3-set-required-permissions-for-rancher) the permissions of your Azure AD app registration. This is critical. 1. Log into Rancher. @@ -254,7 +250,11 @@ If you need to roll back your migration, please note the following: 1. Azure app owners who want to rotate the Application Secret will need to also rotate it in Rancher as Rancher does not automatically update the Application Secret when it is changed in Azure. In Rancher, note that it is stored in a Kubernetes secret called `azureadconfig-applicationsecret` which is in the `cattle-global-data` namespace. -1. **Caution:** If admins upgrade to Rancher v2.6.7 with an existing Azure AD setup and choose to disable the auth provider, they won't be able to restore the previous setup and also will not be able to set up Azure AD anew using the old flow. Admins will then need to register again with the new auth flow. Rancher now uses the new Graph API and, therefore, users need set up the [proper permissions in the Azure portal](#3-set-required-permissions-for-rancher). +:::caution + +If you upgrade to Rancher v2.6.7+ with an existing Azure AD setup, and choose to disable the auth provider, you won't be able to restore the previous setup. You also won't be able to set up Azure AD anew using the old flow. You'll need to re-register with the new auth flow. Since Rancher now uses the Graph API, users need set up the [proper permissions in the Azure portal](#3-set-required-permissions-for-rancher). + +::: #### Global: @@ -264,7 +264,6 @@ Auth Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/authorize Endpoint | https://login.microsoftonline.com/ Graph Endpoint | https://graph.windows.net/ Token Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/token ---- Rancher Field | New Endpoints ---------------- | ------------------------------------------------------------------ @@ -281,7 +280,6 @@ Auth Endpoint | https://login.chinacloudapi.cn/{tenantID}/oauth2/authorize Endpoint | https://login.chinacloudapi.cn/ Graph Endpoint | https://graph.chinacloudapi.cn/ Token Endpoint | https://login.chinacloudapi.cn/{tenantID}/oauth2/token ---- Rancher Field | New Endpoints ---------------- | ------------------------------------------------------------------------- @@ -294,19 +292,19 @@ Token Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2 -## Azure AD Graph API +## Deprecated Azure AD Graph API >**Important:** > ->- The [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) was deprecated in June 2022 and will be retired at the end of 2022. We will update our docs to advise the community when it is retired. Rancher now uses the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) as the new flow to set up Azure AD as the external auth provider. +>- The [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) is deprecated and will be retired by Microsoft at any time after June 30, 2023, without advance notice. We will update our docs to advise the community when it is retired. Rancher now uses the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) as the new flow to set up Azure AD as the external auth provider. > > ->- For new users, or existing users who wish to migrate, refer to the new flow instructions on the Rancher v2.6.7 tab. +>- If you're a new user, or wish to migrate, refer to the new flow instructions for Rancher v2.6.7+. > > ->- For existing users who do not wish to upgrade to v2.6.7 after the Azure AD Graph API is retired, they will need to either: +>- If you don't wish to upgrade to v2.6.7+ after the Azure AD Graph API is retired, you'll need to either: - Use the built-in Rancher auth or - Use another third-party auth system and set that up in Rancher. Please see the [authentication docs](../../../../pages-for-subheaders/authentication-config.md) to learn how to configure other open authentication providers. - \ No newline at end of file + From 50ca14309ab0c635e36c75a66d484e1e07a6a76f Mon Sep 17 00:00:00 2001 From: Max Sokolovsky Date: Thu, 2 Mar 2023 15:48:39 -0500 Subject: [PATCH 2/7] [2.6] Add notes about disabling an auth provider --- .../authentication-config.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md index c61ade4854d..a67bd206a64 100644 --- a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md +++ b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md @@ -109,3 +109,30 @@ If you need to reconfigure or disable then re-enable a provider that had been pr is logged in to Rancher as an external user, not the local admin. ::: + +## Disabling An Auth Provider + +When you disable an auth provider, Rancher deletes all resources associated with it, such as: +- Secrets +- Global role bindings +- Cluster role template bindings +- Project role template bindings +- External users associated with the provider, who never logged in as local users to Rancher + +As this operation may lead to a loss of many resources, you may want to add a safeguard on the provider. +To ensure this cleanup process doesn't run when the auth provider is disabled, add a special annoation to the corresponding auth config. + +For example, to add a safeguard to the Azure AD provider, annotate the `azuread` authconfig object: + +`kubectl annotate --overwrite authconfig azuread management.cattle.io/auth-provider-cleanup='user-locked'` + +Rancher won't perform cleanup until you set the annotation to `unlocked`. + +### Running Resource Cleanup Manually + +Rancher might retain resources from a disabled auth provider configuration in the local cluster, even after you configure another auth provider. +For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, +you can manually trigger cleanup on resources configured by Provider A. + +To manually trigger cleanup for a disabled auth provider, add the `management.cattle.io/auth-provider-cleanup` annotation with the `unlocked` value +to its auth config. From 650427834821328ae548343bbf87b619607aae01 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 6 Mar 2023 16:52:28 -0500 Subject: [PATCH 3/7] Update versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md --- .../version-2.6/pages-for-subheaders/authentication-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md index a67bd206a64..b106d3a728a 100644 --- a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md +++ b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md @@ -130,7 +130,7 @@ Rancher won't perform cleanup until you set the annotation to `unlocked`. ### Running Resource Cleanup Manually -Rancher might retain resources from a disabled auth provider configuration in the local cluster, even after you configure another auth provider. +Rancher might retain resources from a previously disabled auth provider configuration in the local cluster, even after you configure another auth provider. For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, you can manually trigger cleanup on resources configured by Provider A. From 6b4b8e06753189e75162bd1dff5cfc358fd931b8 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 6 Mar 2023 16:53:02 -0500 Subject: [PATCH 4/7] Update versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md --- .../version-2.6/pages-for-subheaders/authentication-config.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md index b106d3a728a..ef588409140 100644 --- a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md +++ b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md @@ -131,8 +131,7 @@ Rancher won't perform cleanup until you set the annotation to `unlocked`. ### Running Resource Cleanup Manually Rancher might retain resources from a previously disabled auth provider configuration in the local cluster, even after you configure another auth provider. -For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, -you can manually trigger cleanup on resources configured by Provider A. +For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, you can manually trigger cleanup on resources configured by Provider A. To manually trigger cleanup for a disabled auth provider, add the `management.cattle.io/auth-provider-cleanup` annotation with the `unlocked` value to its auth config. From e133c0aae4b631f22b4339a45136cab7cf548263 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 6 Mar 2023 16:53:34 -0500 Subject: [PATCH 5/7] Update versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md --- .../version-2.6/pages-for-subheaders/authentication-config.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md index ef588409140..c1787591568 100644 --- a/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md +++ b/versioned_docs/version-2.6/pages-for-subheaders/authentication-config.md @@ -130,8 +130,7 @@ Rancher won't perform cleanup until you set the annotation to `unlocked`. ### Running Resource Cleanup Manually -Rancher might retain resources from a previously disabled auth provider configuration in the local cluster, even after you configure another auth provider. -For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, you can manually trigger cleanup on resources configured by Provider A. +Rancher might retain resources from a previously disabled auth provider configuration in the local cluster, even after you configure another auth provider. For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, you can manually trigger cleanup on resources configured by Provider A. To manually trigger cleanup for a disabled auth provider, add the `management.cattle.io/auth-provider-cleanup` annotation with the `unlocked` value to its auth config. From 069a36c745aaaf3240b415eda858ef33f6d16e86 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Tue, 7 Mar 2023 09:21:46 -0800 Subject: [PATCH 6/7] Add 2.6.11 entry to versions table --- src/pages/versions.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/pages/versions.md b/src/pages/versions.md index 6395406913b..a16b141042c 100644 --- a/src/pages/versions.md +++ b/src/pages/versions.md @@ -21,10 +21,10 @@ Below are the documentation and release notes for the currently released version - + - - + +
v2.6.10v2.6.11 DocumentationRelease NotesSupport MatrixRelease NotesSupport Matrix
@@ -58,6 +58,12 @@ Below are the documentation and release notes for previous versions of Rancher 2 Below are the documentation and release notes for previous versions of Rancher 2.6.x: + + + + + + From 2c30ebf80df6808201f4fad19cd2cdd4633dafa7 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Tue, 7 Mar 2023 10:06:09 -0800 Subject: [PATCH 7/7] Remove 2.5 from 'Current versions' section of versions table --- src/pages/versions.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/pages/versions.md b/src/pages/versions.md index a16b141042c..c4835d83a8a 100644 --- a/src/pages/versions.md +++ b/src/pages/versions.md @@ -28,18 +28,6 @@ Below are the documentation and release notes for the currently released version
v2.6.10DocumentationRelease NotesSupport Matrix
v2.6.9 Documentation
-Below are the documentation and release notes for the currently released version of Rancher 2.5.x: - - - - - - - -
v2.5.17DocumentationRelease Notes
- -
- ### Past versions Below are the documentation and release notes for previous versions of Rancher 2.7.x: