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

Merge pull request #437 from maxsokolovsky/forward-port-verbiage-changes-from-2.6

Browse Source 
Forward-port verbiage changes from v2.6
This commit is contained in:
Billy Tat
2023-02-21 12:52:35 -08:00
committed by GitHub
parent 5ffe73f193 b290851cda
commit cab4c37ccf
1 changed files with 35 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md
+35 -27
View File
@@ -6,6 +6,8 @@ title: Configure Azure AD
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.7, 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.
@@ -23,8 +25,7 @@ Configuring Rancher to allow your users to authenticate with their Azure AD acco
:::tip
Before you start, open two browser tabs: one for Rancher, one for the Azure portal. That will help in easily copying and pasting
configuration values from the portal to Rancher.
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.
:::
@@ -76,13 +77,13 @@ 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 & 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.
Note that users won't be able to log in to Rancher when it detects that the application secret has expired, so rotate the secret in Azure and update in Rancher before it expires.
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).
<a id="secret"></a>
@@ -94,11 +95,11 @@ 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.
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 the left, select **API permissions**.
1. From the navigation pane on, select **API permissions**.
1. Click **Add a permission**.
@@ -106,13 +107,13 @@ Ensure that you set the permissions of type Application and NOT Delegated. Other
![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**. The app's permissions should look like the following:
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 does not validate the permissions you grant to the app in Azure. We only support the use of the `Directory.Read.All` application permission.
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.
:::
@@ -130,38 +131,42 @@ Rancher does not validate the permissions you grant to the app in Azure. We only
1. Obtain your Rancher **Application (Client) ID**.
1. Use search to open **App registrations** (if not already there).
1. If you aren't already there, use search to open **App registrations**.
1. In **Overview**, find the entry you created for Rancher.
1. Copy the **Application (Client) ID** and paste it into Rancher as your **Application ID**.
1. Your endpoint options will typically be either [Standard](#global) or [China](#china). With these options, you only enter the **Tenant ID**, **Application ID**, and **Application Secret**.
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 tested or fully supported by Rancher.
:::caution
You will need to also manually enter the Graph, Token, and Auth Endpoints.
Custom Endpoints are not tested or fully supported by Rancher.
:::
You'll also need to manually enter the Graph, Token, and Auth Endpoints.
- From <b>App registrations</b>, click <b>Endpoints</b>:
![Click Endpoints](/img/endpoints.png)
- Note the following endpoints - these values will be your Rancher endpoint values. Make sure to use 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.
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).
@@ -196,21 +201,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 2020
and will be retired in June 2023, admins 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 old Azure AD Graph API when it is retired, users may not be able to log into Rancher using Azure AD.
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
:::caution
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 described below.
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 the permissions of your Azure AD app registration as described [here](#3-set-required-permissions-for-rancher). This is critical.
1. [Update](#3-set-required-permissions-for-rancher) the permissions of your Azure AD app registration. This is critical.
1. Log into Rancher.
@@ -242,7 +245,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.7.0+ 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.7.0+ 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:
@@ -281,12 +288,13 @@ Token Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2
>**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 for <a href="#microsoft-graph-api/" target="_blank">Rancher v2.7.0+</a>.
>- If you're a new user, or wish to migrate, refer to the new flow instructions for <a href="#microsoft-graph-api/" target="_blank">Rancher v2.7.0+</a>.
>
>
>- For existing users who do not wish to upgrade to v2.7.0+ after the Azure AD Graph API is retired, they will need to either:
>- If you don't wish to upgrade to v2.7.0+ 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.