public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-08-19 08:31:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

edited Chris Kim's adfs content.

Browse Source
This commit is contained in:
Mark Bishop
2018-08-28 17:58:10 -07:00
parent 582b1f8128
commit b24d0bcdea
3 changed files with 84 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md
+21 -16
View File
@@ -6,29 +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 Rancher installed.
> - Your Rancher Server URL will be substituted for `<rancher-server>` 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 `<ad-server>` 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.
## Prerequisites
### Setup Outline
- You must have Rancher installed.
- Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the `<RANCHER_SERVER>` placeholder.
- You must have a global administrator account on your Rancher installation.
- You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured.
- Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the `<AD_SERVER>` placeholder.
- 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.
## 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.
- [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-adfs-setup)
Configure Rancher Server to use Microsoft AD FS for authentication
- [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.
### [Next: Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md
+43 -28
View File
@@ -1,54 +1,66 @@
---
title: 1 - Microsoft AD FS Setup
title: 1 — Configuring Microsoft AD FS for Rancher
weight: 1205
---
## Microsoft AD FS Setup
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. Open the **AD FS Management** console.
![AD FS Management Console Screenshot]({{< baseurl >}}/img/rancher/adfs/adfs-overview.png)
1. Log into your AD server as an administrative user.
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. 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.
![ADFS Add RPT Wizard Step 2]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-2.png)
{{< 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`.
![ADFS Add RPT Wizard Step 3]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-3.png)
{{< 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.
![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)
{{< 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.
![ADFS Add RPT Wizard Step 6]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-6.png)
1. Add `https://<rancher-server>/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)
{{< figure src="/img/rancher/adfs/adfs-add-rpt-6.png" width="600" >}}
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. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
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)
{{< 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.
![ADFS Add RPT Wizard Step 10]({{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-10.png)
{{< figure src="/img/rancher/adfs/adfs-add-rpt-10.png" width="600" >}}
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)
{{< figure src="/img/rancher/adfs/adfs-add-rpt-11.png" width="600" >}}
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)
{{< figure src="/img/rancher/adfs/adfs-edit-cr.png" width="400" >}}
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:
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 |
| -------------------------------------------- | ------------------- |
@@ -56,11 +68,14 @@ weight: 1205
| 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)
<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
https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml
```
### [Next: Rancher AD FS Setup]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
**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/)
content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/_index.md
+20 -11
View File
@@ -1,16 +1,17 @@
---
title: 2 - Rancher AD FS Setup
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`
>- 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`
## Rancher Setup
1. From the **Global** view, select **Security > Authentication** from the main menu.
@@ -18,24 +19,32 @@ _Available as of v2.0.7_
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. **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. **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. **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. **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.
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. **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.