Merge pull request #712 from rancher/staging

MS ADFS into live
2026-09-25 04:28:15 +00:00 · 2018-08-28 22:38:54 -07:00
parent 63555b76f0 d03898b2a7
commit 655b37fcfe
26 changed files with 167 additions and 43 deletions
@@ -6,47 +6,34 @@ _Available as of v2.0.7_

 If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.

->**Prerequisites:**
->
->- You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured.
->- Export a `federationmetadata.xml` file from your AD FS Server. For more information, see the [PingIdentity video](https://docs.pingidentity.com/bundle/ping_sm_videoLibrary/page/p1_IdentityBridgeADFS.html).
+## Prerequisites

-1.	From the **Global** view, select **Security > Authentication** from the main menu.

-1.	Select **Microsoft Active Directory Federation Services**.
+- You must have Rancher installed.

-1.	Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The examples below describe how you can map AD attributes to fields within Rancher.
-	
-    1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`).
+  - Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the `<RANCHER_SERVER>` placeholder.

-	1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`).
-	
-    1. **UID Field**: Enter an AD attribute that is unique to every user (example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn`).
-	
-    1. **Groups Field**: Make entries for managing group memberships (example: `http://schemas.xmlsoap.org/claims/Group`).
-	
-    1. **Rancher API Host**: Enter the URL for your Rancher Server.
+  - You must have a global administrator account on your Rancher installation.

-	1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your AD FS.
-    
-        You can generate one using an openssl command. For example:
-    
-        ```
-        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
-        ```
-    1. **Metadata XML**: The `federationmetadata.xml` file exported from your AD FS server. You can find this file at `https://your-AD-Server/federationmetadata/2007-06/federationmetadata.xml`.
+- You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured.

- 
-1. After you complete the **Configure AD FS Account** form, click **Authenticate with AD FS**, which is at the bottom of the page.
+	- Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the `<AD_SERVER>` placeholder.

-    Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.
+	- You must have access to add [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) on your AD FS Server.

-    >**Note:** You may have to disable your popup blocker to see the AD FS login page.

-**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.
+
+## Setup Outline
+
+Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.
+
+- [1 — Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
+- [2 — Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)

 >**Active Directory Federation Service Caveats:**
 >
 >- AD FS does not support search or lookup. When adding users to [clusters]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/) or [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/), the exact IDs must be entered correctly.
 >- When adding users to [clusters]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/) or [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/), group IDs are not supported unless the admin who turned on access control is a member of the group.
->- When adding a group that includes an admin to [clusters]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/) or [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/), add it from the drop-down rather than the search bar. If you add the group using the search bar, the group will not get added.
+>- When adding a group that includes an admin to [clusters]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/) or [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/), add it from the drop-down rather than the search bar. If you add the group using the search bar, the group will not get added.
+
+### [Next: Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
@@ -0,0 +1,81 @@
+---
+title: 1 — Configuring Microsoft AD FS for Rancher
+weight: 1205
+---
+
+Before configuring Rancher to support AD FS users, you must add Rancher as a [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts) in AD FS. 
+
+1. Log into your AD server as an administrative user.
+
+1. Open the **AD FS Management** console. Select **Add Relying Party Trust...** from the **Actions** menu and click **Start**.
+  
+    {{< figure src="/img/rancher/adfs/adfs-overview.png" width="800" >}}
+
+1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party.
+    
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-2.png" width="600" >}}
+
+1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`.
+
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-3.png" width="600" >}}
+  
+1. Select **AD FS profile** as the configuration profile for your relying party trust.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-4.png" width="600" >}}
+  
+1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-5.png" width="600" >}}
+  
+1. Select **Enable support for the SAML 2.0 WebSSO protocol**
+  and enter `https://<rancher-server>/v1-saml/adfs/saml/acs` for the service URL.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-6.png" width="600" >}}
+  
+1. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-7.png" width="600" >}}
+  
+1. This tutorial will not cover multi-factor authentication; please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs) if you would like to configure multi-factor authentication.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-8.png" width="600" >}}
+  
+1. From **Choose Issuance Authorization RUles**, you may select either of the options available according to use case. However, for the purposes of this guide, select **Permit all users to access this relying party**.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-9.png" width="600" >}}
+
+1. After reviewing your settings, select **Next** to add the relying party trust.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-10.png" width="600" >}}
+  
+1. Select **Open the Edit Claim Rules...** and click **Close**.
+  
+    {{< figure src="/img/rancher/adfs/adfs-add-rpt-11.png" width="600" >}}
+  
+1. On the **Issuance Transform Rules** tab, click **Add Rule...**.
+  
+    {{< figure src="/img/rancher/adfs/adfs-edit-cr.png" width="400" >}}
+  
+1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**.
+
+    {{< figure src="/img/rancher/adfs/adfs-add-tcr-1.png" width="600" >}}
+  
+1. Set the **Claim rule name** to your desired name (for example, `Rancher Attributes`) and select **Active Directory** as the **Attribute store**. Create the following mapping to reflect the table below:
+
+    | LDAP Attribute                               | Outgoing Claim Type |
+    | -------------------------------------------- | ------------------- |
+    | Given-Name                                   | Given Name          |
+    | User-Principal-Name                          | UPN                 |
+    | Token-Groups - Qualified by Long Domain Name | Group               |
+    | SAM-Account-Name                             | Name                |
+    <br/>
+    {{< figure src="/img/rancher/adfs/adfs-add-tcr-2.png" width="600" >}}
+
+1. Download the `federationmetadata.xml` from your AD server at: 
+```
+https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml
+```
+
+**Result:** You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.
+
+### [Next: Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
@@ -0,0 +1,56 @@
+---
+title: 2 — Configuring Rancher for Microsoft AD FS
+weight: 1205
+---
+_Available as of v2.0.7_
+
+After you complete [Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.
+
+>**Important Notes For Configuring Your AD FS Server:**
+> 
+>- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
+>- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
+>- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
+
+
+1.	From the **Global** view, select **Security > Authentication** from the main menu.
+
+1.	Select **Microsoft Active Directory Federation Services**.
+
+1.	Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The examples below describe how you can map AD attributes to fields within Rancher.
+	
+    1. **Display Name Field**: Enter the AD attribute that contains the display name of users. 
+    
+        Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
+
+	1. **User Name Field**: Enter the AD attribute that contains the user name/given name. 
+    
+        Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
+	
+    1. **UID Field**: Enter an AD attribute that is unique to every user.
+    
+        Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn`
+	
+    1. **Groups Field**: Make entries for managing group memberships. 
+    
+        Example: `http://schemas.xmlsoap.org/claims/Group`
+	
+    1. **Rancher API Host**: Enter the URL for your Rancher Server.
+
+	1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.
+    
+        You can generate one using an openssl command. For example:
+    
+        ```
+        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
+        ```
+    1. **Metadata XML**: The `federationmetadata.xml` file exported from your AD FS server. You can find this file at `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`.
+
+ 
+1. After you complete the **Configure AD FS Account** form, click **Authenticate with AD FS**, which is at the bottom of the page.
+
+    Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.
+
+    >**Note:** You may have to disable your popup blocker to see the AD FS login page.
+
+**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.
@@ -185,7 +185,7 @@ RKE uses a YAML config file to install and configure your Kubernetes cluster. Th

    >**Want records of all transactions with the Rancher API?** 
    >
-    >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing).
+    >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}/rke/v0.1.x/en/config-options/add-ons/api-auditing).


 2. Rename the file to `rancher-cluster.yml`.
@@ -119,7 +119,7 @@ In [clusters launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioni
 Option | Description |
 ---------|----------|
 Kubernetes Version | The version of Kubernetes installed on each cluster node. For more detail, see [Upgrading Kubernetes](#upgrading-kubernetes). |
- Network Provider | The [container networking interface]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/) that powers networking for your cluster.<br/><br/>**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. |
+ Network Provider | The [container networking interface]({{< baseurl >}}/rancher/v2.x/en/faq/networking/#cni-providers) that powers networking for your cluster.<br/><br/>**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. |
 Project Network Isolation | As of Rancher v2.0.7, if you're using the Canal network provider, you can choose whether to enable or disable inter-project communication. |
 Nginx Ingress | If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster. |
 Metrics Server Monitoring | Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal. |
@@ -6,7 +6,7 @@ aliases:
  - /rancher/v2.x/en/upgrades/single-node-rollbacks
 ---

-If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrade-scenarios/single-node-upgrade/). Rolling back restores:
+If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade). Rolling back restores:

 - Your previous version of Rancher.
 - Your data backup created before upgrade.
@@ -7,13 +7,13 @@ The following instructions will guide you through upgrading a high-availability

 >**Note:** If you installed Rancher using the RKE Add-on yaml, see the following documents to migrate or upgrade.
 >
->* [Migrating from RKE Add-On Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/migrating-from-rke-add-on)
-
-    As of release v2.0.8, Rancher supports installation and upgrade by Helm chart, although RKE installs/upgrades are still supported as well. If you want to change upgrade method from RKE Add-on to Helm chart, follow this procedure.
-
+>* [Migrating from RKE Add-On Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on)
+>
+>       As of release v2.0.8, Rancher supports installation and upgrade by Helm chart, although RKE installs/upgrades are still supported as well. If you want to change upgrade method from RKE Add-on to Helm chart, follow this procedure.
+>
 >* [High Availability (HA) Upgrade - RKE Add-On Install]({{< baseurl >}}/rancher/v2.x/en/upgrades/ha-server-upgrade)
-
-    If you want to continue using RKE for upgrades, follow this procedure.
+>
+>       If you want to continue using RKE for upgrades, follow this procedure.

 ## Prerequisites

@@ -23,7 +23,7 @@ This document is for upgrading Rancher HA installed with the RKE Add-On yaml. Se

    >**Want records of all transactions with the Rancher API?** 
    >
-    >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file (`rancher-cluster.yml`). For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing).
+    >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file (`rancher-cluster.yml`). For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}/rke/v0.1.x/en/config-options/add-ons/api-auditing).

 1. <a id="snapshot"></a> Enter the following command. Replace `<SNAPSHOT.db>` with any name that you want to use for the snapshot (e.g. `upgrade.db`).

@@ -1,6 +1,6 @@
 ---
 title: Migrating from Rancher v1.6 to v2.x
-weight: 10000
+weight: 8500
 draft: true
 ---

@@ -3,7 +3,7 @@ title: User-Defined Add-Ons
 weight: 263
 ---

-Besides the [network plug-in]({{< baseurl >}}/rke/v0.1.x/en/config-options/network-plugins/) and [ingress controllers]({{< baseurl >}}/rke/v0.1.x/en/config-options/ingress-controllers/), you can define any add-on that you want deployed after the Kubernetes cluster is deployed.
+Besides the [network plug-in]({{< baseurl >}}/rke/v0.1.x/en/config-options/add-ons/network-plugins) and [ingress controllers]({{< baseurl >}}/rke/v0.1.x/en/config-options/add-ons/ingress-controllers/), you can define any add-on that you want deployed after the Kubernetes cluster is deployed.

 There are two ways that you can specify an add-on.

@@ -101,4 +101,4 @@ If the Docker socket is different than the default, you can set the `docker_sock

 ### Labels

-You have the ability to add an arbitrary map of labels for each node. It can be used when using the [ingress controller's]({{< baseurl >}}/rke/v0.1.x/en/config-options/ingress-controllers/) `node_selector` option.
+You have the ability to add an arbitrary map of labels for each node. It can be used when using the [ingress controller's]({{< baseurl >}}/rke/v0.1.x/en/config-options/add-ons/ingress-controllers/) `node_selector` option.