diff --git a/docs/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/docs/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index 69c1737cc75..d5b04a01278 100644 --- a/docs/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/docs/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -3,6 +3,9 @@ title: Installing the Adapter weight: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + > **Important:** If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour. ### 1. Gain Access to the Local Cluster @@ -63,62 +66,62 @@ For the below instructions, replace `$MY_ACC_NUM` with your AWS account number a > **Note:** It is important that you follow the instructions below exactly. In particular, the command to install version 1.0.1 of the adapter (by using --set image.tag=v1.0.1) is key to ensure that node counts are accurate. -{{% tabs %}} -{{% tab "Let's Encrypt/ Public Certificate Authority" %}} + + -```bash -helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set image.tag=v1.0.1 -``` + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set image.tag=v1.0.1 + ``` -Alternatively, you can use a `values.yaml` and specify options like below: + Alternatively, you can use a `values.yaml` and specify options like below: -```yaml -image: - tag: v1.0.1 -aws: - enabled: true - accountNumber: "$MY_ACC_NUM" - roleName: $MY_ROLE_NAME -``` + ```yaml + image: + tag: v1.0.1 + aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME + ``` -> **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. + > **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. -You can then install the adapter with the following command: + You can then install the adapter with the following command: -```bash -helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml -``` + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml + ``` -{{% /tab %}} -{{% tab "Private CA Authority / Rancher-generated Certificates" %}} + + -```bash -helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set additionalTrustedCAs=true --set image.tag=v1.0.1 -``` + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set additionalTrustedCAs=true --set image.tag=v1.0.1 + ``` -Alternatively, you can use a `values.yaml` and specify options the below: + Alternatively, you can use a `values.yaml` and specify options the below: -```yaml -image: - tag: v1.0.1 -aws: - enabled: true - accountNumber: "$MY_ACC_NUM" - roleName: $MY_ROLE_NAME -additionalTrustedCAs: true -``` + ```yaml + image: + tag: v1.0.1 + aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME + additionalTrustedCAs: true + ``` -> **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. + > **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. -You can then install the adapter with the following command: + You can then install the adapter with the following command: -```bash -helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml -``` + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml + ``` -{{% /tab %}} -{{% /tabs %}} + + ### 5. Managing Certificate Updates diff --git a/docs/explanations/integrations-in-rancher/neuvector.md b/docs/explanations/integrations-in-rancher/neuvector.md index 3ce50a1ea0b..a3dc8ccee6a 100644 --- a/docs/explanations/integrations-in-rancher/neuvector.md +++ b/docs/explanations/integrations-in-rancher/neuvector.md @@ -3,6 +3,9 @@ title: NeuVector Integration weight: 22 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ### NeuVector Integration in Rancher New in Rancher v2.6.5, [NeuVector 5.x](https://open-docs.neuvector.com/) is an open-source container-centric security platform that is now integrated into Rancher. NeuVector offers real-time compliance, visibility, and protection for critical applications and data during runtime. NeuVector provides a firewall, container process/file system monitoring, security auditing with CIS benchmarks, and vulnerability scanning. For more information on Rancher security, please see the [security documentation](../../pages-for-subheaders/rancher-security.md). @@ -11,13 +14,13 @@ NeuVector can be enabled through a Helm chart that may be installed either throu ### Installing NeuVector with Rancher -The Harvester Helm Chart is used to manage access to the NeuVector UI in Rancher where users can navigate directly to deploy and manage their NeuVector clusters. +The Harvester Helm Chart is used to manage access to the NeuVector UI in Rancher where users can navigate directly to deploy and manage their NeuVector clusters. **To navigate to and install the NeuVector chart through Apps & Marketplace:** 1. Click **☰ > Cluster Management**. 1. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click **Explore**. -1. Go to **Apps & Marketplace > Charts**, and install **NeuVector** from the chart repo. +1. Go to **Apps & Marketplace > Charts**, and install **NeuVector** from the chart repo. 1. Different cluster types require different container runtimes. When configuring Helm chart values, go to the **Container Runtime** section, and select your runtime in accordance with the cluster type. Finally, click **Install** again. Some examples are as follows: @@ -29,11 +32,11 @@ Some examples are as follows: - GKE: `containerd` (see the [Google docs](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd) for more) :::note - + Only one container runtime engine may be selected at a time during installation. ::: - + **To navigate to and install the NeuVector chart through Cluster Tools:** 1. Click **☰ > Cluster Management**. @@ -102,63 +105,63 @@ Below are the minimum recommended computing resources for the NeuVector chart in ### Hardened Cluster Support - Calico and Canal -{{% tabs %}} -{{% tab "RKE1" %}} + + -- All NeuVector components are deployable if PSP is set to true. + - All NeuVector components are deployable if PSP is set to true. -**_New in v2.6.7_** + **_New in v2.6.7_** -You will need to set additional configuration for your hardened cluster environment as follows: + You will need to set additional configuration for your hardened cluster environment as follows: -1. Click **☰ > Cluster Management**. -1. Go to the cluster that you created and click **Explore**. -1. In the left navigation bar, click **Apps & Marketplace**. -1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`. + 1. Click **☰ > Cluster Management**. + 1. Go to the cluster that you created and click **Explore**. + 1. In the left navigation bar, click **Apps & Marketplace**. + 1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`. - - Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box (no other config needed): + - Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box (no other config needed): - ![Enable PSP for RKE1 Hardened Cluster](/img/psp-nv-rke.png) + ![Enable PSP for RKE1 Hardened Cluster](/img/psp-nv-rke.png) -1. Click **Install** at the bottom-right to complete. + 1. Click **Install** at the bottom-right to complete. -{{% /tab %}} -{{% tab "RKE2" %}} + + -- NeuVector components Controller and Enforcer are deployable if PSP is set to true. + - NeuVector components Controller and Enforcer are deployable if PSP is set to true. -**Applicable to NeuVector chart version 100.0.0+up2.2.0 only:** + **Applicable to NeuVector chart version 100.0.0+up2.2.0 only:** -- For Manager, Scanner, and Updater components, additional configuration is required as shown below: + - For Manager, Scanner, and Updater components, additional configuration is required as shown below: -``` -kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' -kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' -kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' -``` -
+ ``` + kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' + kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' + kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' + ``` +
-**_New in v2.6.7_** + **_New in v2.6.7_** -You will need to set additional configuration for your hardened cluster environment. + You will need to set additional configuration for your hardened cluster environment. ->**Note:** You must update your config in both RKE2 and K3s hardened clusters as shown below. + >**Note:** You must update your config in both RKE2 and K3s hardened clusters as shown below. -1. Click **☰ > Cluster Management**. -1. Go to the cluster that you created and click **Explore**. -1. In the left navigation bar, click **Apps & Marketplace**. -1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`. + 1. Click **☰ > Cluster Management**. + 1. Go to the cluster that you created and click **Explore**. + 1. In the left navigation bar, click **Apps & Marketplace**. + 1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`. - - Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box. Note that you must also enter a value greater than `zero` for `Manager runAsUser ID`, `Scanner runAsUser ID`, and `Updater runAsUser ID`: + - Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box. Note that you must also enter a value greater than `zero` for `Manager runAsUser ID`, `Scanner runAsUser ID`, and `Updater runAsUser ID`: - ![Enable PSP for RKE2 and K3s Hardened Clusters](/img/psp-nv-rke2.png) + ![Enable PSP for RKE2 and K3s Hardened Clusters](/img/psp-nv-rke2.png) -1. Click **Install** at the bottom-right to complete. + 1. Click **Install** at the bottom-right to complete. -{{% /tab %}} -{{% /tabs %}} + + ### SELinux-enabled Cluster Support - Calico and Canal diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md index 59d54542a92..6099909c1b0 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md @@ -73,24 +73,24 @@ To install `gcloud` and `kubectl`, perform the following steps: - Using gcloud config, to individually set your project ID, zone, and region. - + -1. Run gcloud init and follow the directions: + 1. Run gcloud init and follow the directions: - ``` - gcloud init - ``` - If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser: + ``` + gcloud init + ``` + If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser: - ``` - gcloud init --console-only - ``` -2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created. + ``` + gcloud init --console-only + ``` + 2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created. - - - + + + # 4. Confirm that gcloud is configured correctly diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md index 258dcafff67..f6631d30daa 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md @@ -3,311 +3,314 @@ title: Configuring Azure AD weight: 1115 --- -{{% tabs %}} -{{% tab "Rancher v2.5.16+" %}} +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -## 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). + ## Microsoft Graph API -### New User Setup + 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). -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. + ### New User Setup ->**Prerequisite:** Have an instance of Azure AD configured. + 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. ->**Notes:** -> ->- Azure AD integration only supports Service Provider initiated logins. ->- Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). + >**Prerequisite:** Have an instance of Azure AD configured. -#### Azure Active Directory Configuration Outline + >**Notes:** + > + >- Azure AD integration only supports Service Provider initiated logins. + >- Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). -Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started. - + #### Azure Active Directory Configuration Outline ->**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. + Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started. + - + >**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. -- [1. Register Rancher with Azure](#1-register-rancher-with-azure) -- [2. Create a new client secret](#2-create-a-new-client-secret) -- [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher) -- [4. Copy Azure Application Data](#5-copy-azure-application-data) -- [5. Configure Azure AD in Rancher](#6-configure-azure-ad-in-rancher) + - + - [1. Register Rancher with Azure](#1-register-rancher-with-azure) + - [2. Create a new client secret](#2-create-a-new-client-secret) + - [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher) + - [4. Copy Azure Application Data](#5-copy-azure-application-data) + - [5. Configure Azure AD in Rancher](#6-configure-azure-ad-in-rancher) -#### 1. Register Rancher with Azure + -Before enabling Azure AD within Rancher, you must register Rancher with Azure. + #### 1. Register Rancher with Azure -1. Log in to [Microsoft Azure](https://portal.azure.com/) as an administrative user. Configuration in future steps requires administrative access rights. + Before enabling Azure AD within Rancher, you must register Rancher with Azure. -1. Use search to open the **App registrations** service. + 1. Log in to [Microsoft Azure](https://portal.azure.com/) as an administrative user. Configuration in future steps requires administrative access rights. - ![Open App Registrations](/img/search-app-registrations.png) + 1. Use search to open the **App registrations** service. -1. Click **New registrations** and complete the **Create** form. + ![Open App Registrations](/img/search-app-registrations.png) - ![New App Registration](/img/new-app-registration.png) + 1. Click **New registrations** and complete the **Create** form. - 3.1. Enter a **Name** (something like `Rancher`). - + ![New App Registration](/img/new-app-registration.png) - 3.2. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options. + 3.1. Enter a **Name** (something like `Rancher`). + - >**Important:** In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below. + 3.2. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options. - 3.3. In the [**Redirect URI**](https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url) section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `/verify-auth-azure`. + >**Important:** In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below. - >**Tip:** You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web). + 3.3. In the [**Redirect URI**](https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url) section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `/verify-auth-azure`. - 3.4. Click **Register**. + >**Tip:** You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web). ->**Important:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. + 3.4. Click **Register**. -#### 2. Create a new client secret + >**Important:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. -From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD. + #### 2. Create a new client secret -1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure. + From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD. - ![Open Rancher Registration](/img/open-rancher-app-reg.png) + 1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure. -1. From the navigation pane on left, click **Certificates and Secrets**. + ![Open Rancher Registration](/img/open-rancher-app-reg.png) -1. Click **New client secret**. + 1. From the navigation pane on left, click **Certificates and Secrets**. - ![Create new client secret](/img//new-client-secret.png) + 1. Click **New client secret**. - 3.1. Enter a **Description** (something like `Rancher`). + ![Create new client secret](/img//new-client-secret.png) - 3.2. 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. + 3.1. Enter a **Description** (something like `Rancher`). - 3.3. Click **Add** (you don't need to enter a value—it will automatically populate after you save). - + 3.2. 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. Copy the key value and save it to an [empty text file](#tip). + 3.3. Click **Add** (you don't need to enter a value—it will automatically populate after you save). + - You'll enter this key into the Rancher UI later as your **Application Secret**. + 1. Copy the key value and save it to an [empty text file](#tip). - You won't be able to access the key value again within the Azure UI. + You'll enter this key into the Rancher UI later as your **Application Secret**. -#### 3. Set Required Permissions for Rancher + You won't be able to access the key value again within the Azure UI. -Next, set API permissions for Rancher within Azure. + #### 3. Set Required Permissions for Rancher -:::caution + Next, set API permissions for Rancher within Azure. -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. + :::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. -1. From the navigation pane on left, select **API permissions**. + ::: - ![Open Required Permissions](/img/select-req-permissions.png) + 1. From the navigation pane on left, select **API permissions**. -1. Click **Add a permission**. + ![Open Required Permissions](/img/select-req-permissions.png) -1. From the **Microsoft Graph**, select the following **Application Permissions**: - - `Group.Read.All` - - `User.Read.All` + 1. Click **Add a permission**. - ![Select API Permissions]/img/api-permissions.png) + 1. From the **Microsoft Graph**, select the following **Application Permissions**: + - `Group.Read.All` + - `User.Read.All` -1. Return to **API permissions** in the left nav bar. From there, click **Grant admin consent**. Then click **Yes**. + ![Select API Permissions]/img/api-permissions.png) - >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings. + 1. Return to **API permissions** in the left nav bar. From there, click **Grant admin consent**. Then click **Yes**. + >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings. -#### 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. + #### 4. Copy Azure Application Data -1. Obtain your Rancher **Tenant ID**. + 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. - 1. Use search to open **App registrations**. + 1. Obtain your Rancher **Tenant ID**. - ![Open App Registrations](/img/search-app-registrations.png) + 1. Use search to open **App registrations**. - 1. Find the entry you created for Rancher. + ![Open App Registrations](/img/search-app-registrations.png) - 1. Copy the **Directory ID** and paste it into your [text file](#tip). + 1. Find the entry you created for Rancher. - ![Tenant ID](/img/tenant-id.png) + 1. Copy the **Directory ID** and paste it into your [text file](#tip). - - You'll paste this value into Rancher as your **Tenant ID**. + ![Tenant ID](/img/tenant-id.png) -1. Obtain your Rancher **Application (Client) ID**. + - You'll paste this value into Rancher as your **Tenant ID**. - 1. Use search to open **App registrations** (if not already there). + 1. Obtain your Rancher **Application (Client) ID**. - 1. In **Overview**, find the entry you created for Rancher. + 1. Use search to open **App registrations** (if not already there). - 1. Copy the **Application (Client) ID** and paste it to your [text file](#tip). + 1. In **Overview**, find the entry you created for Rancher. - ![Application ID](/img/application-client-id.png) + 1. Copy the **Application (Client) ID** and paste it to your [text file](#tip). -1. Your endpoint options will typically be [Standard](#global) and [China](#china). With the Standard option, perform the steps below and Rancher will take care of the rest. + ![Application ID](/img/application-client-id.png) - - Enter the **Tenant ID**, **Application ID**, and **Application Secret** - - Click **Enable** + 1. Your endpoint options will typically be [Standard](#global) and [China](#china). With the Standard option, perform the steps below and Rancher will take care of the rest. -![Standard Endpoint Options](/img/tenant-application-id-secret2.png) - ->**For Custom Endpoints:** -> ->**Warning:** Custom Endpoints are not supported nor fully tested by Rancher. -> -> You will need to also 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. -> -> - **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). - -1. Log into Rancher. -1. In the top left corner, click **☰ > Users & Authentication**. -1. In the left navigation 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). - - The following table maps the values you copied in the Azure portal to the fields in Rancher. - - | Rancher Field | Azure Value | - | ------------------ | ------------------------------------- | - | Tenant ID | Directory ID | - | Application ID | Application ID | - | Application Secret | Key Value | - | Endpoint | https://login.microsoftonline.com/ | + - Enter the **Tenant ID**, **Application ID**, and **Application Secret** + - Click **Enable** + ![Standard Endpoint Options](/img/tenant-application-id-secret2.png) >**For Custom Endpoints:** - >
- >The following table maps the custom config values you copied in the Azure portal to the fields in Rancher: > - >| Rancher Field | Azure Value | - >| ------------------ | ------------------------------------- | - >| Graph Endpoint | Microsoft Graph API Endpoint | - >| Token Endpoint | OAuth 2.0 Token Endpoint | - >| Auth Endpoint | OAuth 2.0 Authorization Endpoint | - >
- >**Important:** When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL, like below: + >**Warning:** Custom Endpoints are not supported nor fully tested by Rancher. > - >https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c + > You will need to also 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. + > + > - **Microsoft Graph API endpoint** (Graph Endpoint) + > - **OAuth 2.0 token endpoint (v1)** (Token Endpoint) + > - **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint) -1. Click **Enable**. + #### 5. Configure Azure AD in Rancher -**Result:** Azure Active Directory authentication is configured. + 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). + + 1. Log into Rancher. + 1. In the top left corner, click **☰ > Users & Authentication**. + 1. In the left navigation 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). + + The following table maps the values you copied in the Azure portal to the fields in Rancher. + + | Rancher Field | Azure Value | + | ------------------ | ------------------------------------- | + | Tenant ID | Directory ID | + | Application ID | Application ID | + | Application Secret | Key Value | + | Endpoint | https://login.microsoftonline.com/ | -### Migrating from Azure AD Graph API to Microsoft Graph API + >**For Custom Endpoints:** + >
+ >The following table maps the custom config values you copied in the Azure portal to the fields in Rancher: + > + >| Rancher Field | Azure Value | + >| ------------------ | ------------------------------------- | + >| Graph Endpoint | Microsoft Graph API Endpoint | + >| Token Endpoint | OAuth 2.0 Token Endpoint | + >| Auth Endpoint | OAuth 2.0 Authorization Endpoint | + >
+ >**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 -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. + 1. Click **Enable**. -#### 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. - -1. Update the permissions of your Azure AD app registration as described [here](#3-set-required-permissions-for-rancher). -**This is critical.** - -1. Log into Rancher. - -1. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so. - - ![Rancher UI Banner](/img/rancher-ui-azure-update2.png) - -1. To complete the move to the new Microsoft Graph API, click **Update Endpoint**, then click **Save**. - - **Note:** Ensure that your Azure app has a [new set of permissions](#3-set-required-permissions-for-rancher) before starting the update. - - ![Update Endpoint](/img/rancher-button-to-update2.png) - -1. When you receive the pop-up warning message, click **Update**. - - ![Azure Update Pop-up](/img/azure-update-popup2.png) - -1. Refer to the [tables](#global) below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually. - -#### Air-Gapped Environments - -In air-gapped environments, admins should ensure that their endpoints are [whitelisted](#3.2) since the Graph Endpoint URL is changing. - -#### Rolling Back the Migration - -If you need to roll back your migration, please note the following: - -1. Admins are encouraged to use the proper restore process if they want to go back. Please see [backup docs](../../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md), [restore docs](../../../../new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md), and [examples](../../../../../reference-guides/backup-restore-configuration/examples.md) for reference. - -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.5.16 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). - -#### Global: - -Rancher Field | Deprecated Endpoints ----------------- | ------------------------------------------------------------- -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 ----------------- | ------------------------------------------------------------------ -Auth Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize -Endpoint | https://login.microsoftonline.com/ -Graph Endpoint | https://graph.microsoft.com -Token Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token - -#### China: - -Rancher Field | Deprecated Endpoints ----------------- | ---------------------------------------------------------- -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 ----------------- | ------------------------------------------------------------------------- -Auth Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize -Endpoint | https://login.partner.microsoftonline.cn/ -Graph Endpoint | https://microsoftgraph.chinacloudapi.cn -Token Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token + **Result:** Azure Active Directory authentication is configured. -{{% /tab %}} -{{% tab "Rancher v2.5.0 - v2.5.15" %}} + ### Migrating from Azure AD Graph API to Microsoft Graph API -## Azure AD 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. ->**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. -> -> ->- For new users, or existing users who wish to migrate, refer to the new flow instructions on the Rancher v2.5.16+ tab. -> -> ->- For existing users who do not wish to upgrade to v2.5.16+ after the Azure AD Graph API is retired, they will 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/about-authentication.md) to learn how to configure other open authentication providers. + #### 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. + + 1. Update the permissions of your Azure AD app registration as described [here](#3-set-required-permissions-for-rancher). + **This is critical.** + + 1. Log into Rancher. + + 1. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so. + + ![Rancher UI Banner](/img/rancher-ui-azure-update2.png) + + 1. To complete the move to the new Microsoft Graph API, click **Update Endpoint**, then click **Save**. + + **Note:** Ensure that your Azure app has a [new set of permissions](#3-set-required-permissions-for-rancher) before starting the update. + + ![Update Endpoint](/img/rancher-button-to-update2.png) + + 1. When you receive the pop-up warning message, click **Update**. + + ![Azure Update Pop-up](/img/azure-update-popup2.png) + + 1. Refer to the [tables](#global) below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually. + + #### Air-Gapped Environments + + In air-gapped environments, admins should ensure that their endpoints are [whitelisted](#3.2) since the Graph Endpoint URL is changing. + + #### Rolling Back the Migration + + If you need to roll back your migration, please note the following: + + 1. Admins are encouraged to use the proper restore process if they want to go back. Please see [backup docs](../../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md), [restore docs](../../../../new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md), and [examples](../../../../../reference-guides/backup-restore-configuration/examples.md) for reference. + + 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.5.16 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). + + #### Global: + + Rancher Field | Deprecated Endpoints + ---------------- | ------------------------------------------------------------- + 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 + ---------------- | ------------------------------------------------------------------ + Auth Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize + Endpoint | https://login.microsoftonline.com/ + Graph Endpoint | https://graph.microsoft.com + Token Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token + + #### China: + + Rancher Field | Deprecated Endpoints + ---------------- | ---------------------------------------------------------- + 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 + ---------------- | ------------------------------------------------------------------------- + Auth Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize + Endpoint | https://login.partner.microsoftonline.cn/ + Graph Endpoint | https://microsoftgraph.chinacloudapi.cn + Token Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token -{{% /tab %}} -{{% /tabs %}} + + + + ## 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. + > + > + >- For new users, or existing users who wish to migrate, refer to the new flow instructions on the Rancher v2.5.16+ tab. + > + > + >- For existing users who do not wish to upgrade to v2.5.16+ after the Azure AD Graph API is retired, they will 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/about-authentication.md) to learn how to configure other open authentication providers. + + + +