diff --git a/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md index e7722028540..6c702ad298f 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md @@ -6,121 +6,27 @@ _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 Rancher installed. +> - Your Rancher Server URL will be substituted for `` in the following guides. +>- You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured. +> - Your AD FS Server IP/DNS Name will be substituted for `` in the following guides. +>- You must be able to add `Relying Party Trusts` on your AD FS Server. +>- You must have a global admin account on your Rancher installation. + ### Setup Outline -Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to expect AD FS queries. +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. -- [Microsoft AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/#microsoft-ad-fs-setup) +- [Microsoft AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup) Set up Microsoft AD FS to expect Rancher for authentication -- [Rancher AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/#rancher-setup) +- [Rancher AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup) Configure Rancher Server to use Microsoft AD FS for authentication - ->**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). - -## Microsoft AD FS Setup - -1. Open the `AD FS Management Console` - ![AD FS Management Console Screenshot]({{< baseurl >}}/img/rancher/adfs/adfs-overview.png) - -1. Select `Add Relying Party Trust...` in the right actions menu. - ![ADFS Add RPT Wizard Step 1]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-1.png) - -1. Select `Enter data about the relying party manually` as the option for obtaining data about the relying party - ![ADFS Add RPT Wizard Step 2]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-2.png) - -1. Enter a `Display name` for your Relying Party Trust - ![ADFS Add RPT Wizard Step 3]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-3.png) - -1. Select `AD FS profile` as the configuration profile for your relying party trust - ![ADFS Add RPT Wizard Step 4]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-4.png) - -1. Leave the `optional token encryption certificate` empty, as Rancher ADFS will not be using one. - ![ADFS Add RPT Wizard Step 5]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-5.png) - -1. Select `Enable support for the SAML 2.0 WebSSO protocol` - and enter `https:///v1-saml/adfs/saml/acs` for the service URL - ![ADFS Add RPT Wizard Step 6]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-6.png) - -1. Add `https:///v1-saml/adfs/saml/metadata` as the Relying party trust identifier - ![ADFS Add RPT Wizard Step 7]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-7.png) - -1. This tutorial will not cover multi-factor authentication; please refer to the Microsoft documentation if you would like to configure mutli-factor authentication. - ![ADFS Add RPT Wizard Step 8]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-8.png) - -1. Select `Permit all users to access this relying party` - ![ADFS Add RPT Wizard Step 9]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-9.png) - -1. After reviewing your settings, select `Next` to add the relying party trust - ![ADFS Add RPT Wizard Step 10]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-10.png) - -1. Select `Open the Edit Claim Rules...` and click `Close` - ![ADFS Add RPT Wizard Step 11]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-11.png) - -1. Click `Add Rule...` - ![ADFS Edit Claim Rules]({{< baseurl >}}/img/rancher/adfs/adfs-edit-cr.png) - -1. Select `Send LDAP Attributes as Claims` as the Claim rule template - ![ADFS Add Transform Claim Rule Step 1]({{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-1.png) - -1. Set the `Claim rule name` to your desired name, 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 | - ![ADFS Add Transform Claim Rule Step 2]({{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-2.png) - -1. Download the `federationmetadata.xml` from your AD server at: -``` -https:///federationmetadata/2007-06/federationmetadata.xml -``` - - -## Rancher Setup - -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. - - 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`. - - -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. - >**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. diff --git a/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md new file mode 100644 index 00000000000..b782ce171f6 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md @@ -0,0 +1,66 @@ +--- +title: 1 - Microsoft AD FS Setup +weight: 1205 +--- + +## Microsoft AD FS Setup + +1. Open the **AD FS Management** console. + ![AD FS Management Console Screenshot]({{< baseurl >}}/img/rancher/adfs/adfs-overview.png) + +1. Select **Add Relying Party Trust...** in the right actions menu. + ![ADFS Add RPT Wizard Step 1]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-1.png) + +1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party. + ![ADFS Add RPT Wizard Step 2]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-2.png) + +1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`. + ![ADFS Add RPT Wizard Step 3]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-3.png) + +1. Select **AD FS profile** as the configuration profile for your relying party trust. + ![ADFS Add RPT Wizard Step 4]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-4.png) + +1. Leave the **optional token encryption certificate** empty, as Rancher ADFS will not be using one. + ![ADFS Add RPT Wizard Step 5]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-5.png) + +1. Select **Enable support for the SAML 2.0 WebSSO protocol** + and enter `https:///v1-saml/adfs/saml/acs` for the service URL. + ![ADFS Add RPT Wizard Step 6]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-6.png) + +1. Add `https:///v1-saml/adfs/saml/metadata` as the **Relying party trust identifier** + ![ADFS Add RPT Wizard Step 7]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-7.png) + +1. This tutorial will not cover multi-factor authentication; please refer to the Microsoft documentation if you would like to configure multi-factor authentication. + ![ADFS Add RPT Wizard Step 8]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-8.png) + +1. You may select either of these options depending on your desired use case. However, for the purposes of this guide, select **Permit all users to access this relying party**. + ![ADFS Add RPT Wizard Step 9]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-9.png) + +1. After reviewing your settings, select **Next** to add the relying party trust. + ![ADFS Add RPT Wizard Step 10]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-10.png) + +1. Select **Open the Edit Claim Rules...** and click **Close**. + ![ADFS Add RPT Wizard Step 11]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-11.png) + +1. On the **Issuance Transform Rules** tab, click **Add Rule...**. + ![ADFS Edit Claim Rules]({{< baseurl >}}/img/rancher/adfs/adfs-edit-cr.png) + +1. Select **Send LDAP Attributes as Claims** as the Claim rule template. + ![ADFS Add Transform Claim Rule Step 1]({{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-1.png) + +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 | + ![ADFS Add Transform Claim Rule Step 2]({{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-2.png) + +1. Download the `federationmetadata.xml` from your AD server at: +``` +https:///federationmetadata/2007-06/federationmetadata.xml +``` + +### [Next: Rancher AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/) diff --git a/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/_index.md new file mode 100644 index 00000000000..6435d83b64e --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/_index.md @@ -0,0 +1,47 @@ +--- +title: 2 - Rancher AD FS Setup +weight: 1205 +--- +_Available as of v2.0.7_ + +>**Important Notes For Configuring Your AD FS Server:** +> +>- The SAML 2.0 WebSSO Protocol Service URL is: `https:///v1-saml/adfs/saml/acs` +>- The Relying Party Trust Identifier URL is: `https:///v1-saml/adfs/saml/metadata` +>- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https:///federationmetadata/2007-06/federationmetadata.xml` + +## Rancher Setup + +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:///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. diff --git a/src/img/rancher/adfs/adfs-add-rpt-1.png b/src/img/rancher/adfs/adfs-add-rpt-1.png index 4da63c44f00..ba22ca3b8ec 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-1.png and b/src/img/rancher/adfs/adfs-add-rpt-1.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-10.png b/src/img/rancher/adfs/adfs-add-rpt-10.png index 8ea35096194..ed87592060e 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-10.png and b/src/img/rancher/adfs/adfs-add-rpt-10.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-11.png b/src/img/rancher/adfs/adfs-add-rpt-11.png index b99dcc615d3..e5a3c491d48 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-11.png and b/src/img/rancher/adfs/adfs-add-rpt-11.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-2.png b/src/img/rancher/adfs/adfs-add-rpt-2.png index a70e1be7a38..3e3c0e9ac77 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-2.png and b/src/img/rancher/adfs/adfs-add-rpt-2.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-4.png b/src/img/rancher/adfs/adfs-add-rpt-4.png index 34344ad8b81..1fb88da0856 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-4.png and b/src/img/rancher/adfs/adfs-add-rpt-4.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-5.png b/src/img/rancher/adfs/adfs-add-rpt-5.png index 8bc1e4dc9ec..f71fb4d8865 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-5.png and b/src/img/rancher/adfs/adfs-add-rpt-5.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-6.png b/src/img/rancher/adfs/adfs-add-rpt-6.png index a25c63f101a..b7aafbd4e14 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-6.png and b/src/img/rancher/adfs/adfs-add-rpt-6.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-7.png b/src/img/rancher/adfs/adfs-add-rpt-7.png index d3362d67093..25cb3f4db83 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-7.png and b/src/img/rancher/adfs/adfs-add-rpt-7.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-8.png b/src/img/rancher/adfs/adfs-add-rpt-8.png index 150457aae14..dedef705029 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-8.png and b/src/img/rancher/adfs/adfs-add-rpt-8.png differ diff --git a/src/img/rancher/adfs/adfs-add-rpt-9.png b/src/img/rancher/adfs/adfs-add-rpt-9.png index cbf5f9055c2..4ab58aec937 100644 Binary files a/src/img/rancher/adfs/adfs-add-rpt-9.png and b/src/img/rancher/adfs/adfs-add-rpt-9.png differ diff --git a/src/img/rancher/adfs/adfs-add-tcr-1.png b/src/img/rancher/adfs/adfs-add-tcr-1.png index 628f31cb522..1458439809b 100644 Binary files a/src/img/rancher/adfs/adfs-add-tcr-1.png and b/src/img/rancher/adfs/adfs-add-tcr-1.png differ diff --git a/src/img/rancher/adfs/adfs-add-tcr-2.png b/src/img/rancher/adfs/adfs-add-tcr-2.png index 1b317b378ba..affa9ab0aea 100644 Binary files a/src/img/rancher/adfs/adfs-add-tcr-2.png and b/src/img/rancher/adfs/adfs-add-tcr-2.png differ diff --git a/src/img/rancher/adfs/adfs-edit-cr.png b/src/img/rancher/adfs/adfs-edit-cr.png index f1d92df3525..2a1171eda5a 100644 Binary files a/src/img/rancher/adfs/adfs-edit-cr.png and b/src/img/rancher/adfs/adfs-edit-cr.png differ diff --git a/src/img/rancher/adfs/adfs-overview.png b/src/img/rancher/adfs/adfs-overview.png index 8def480fdff..9eb81a73540 100644 Binary files a/src/img/rancher/adfs/adfs-overview.png and b/src/img/rancher/adfs/adfs-overview.png differ