```{title} Active Directory Federation Services (ADFS) SAML Setup
```

## Active Directory Federation Services (ADFS) SAML Setup

This guide walks through a basic setup for connecting Kasm to ADFS on Windows Server 2016 via SAML. Active Directory
user accounts are assumed to have a populated email address attribute.

### ADFS Signing Certificate

1. From the ADFS Management console, expand **Service**, and select **Certificates**.
2. Right-Click the **Token-signing** certificate and select **View Certificate**.

```{figure} /images/saml/adfs/view_certificate.png
:align: center
:width: 90%
```

3. Select the **Details** tab, then click **Copy to File**.

```{figure} /images/saml/adfs/copy_certificate.png
:align: center
:width: 70%
```

4. In the **Certificate Export Wizard**, click **Next**.

```{figure} /images/saml/adfs/certificate_export_wizard.png
:align: center
:width: 90%
```

5. Select **Base-64 encoded X.509 (CER)** . Click **Next**.
6. Select a desired output file and click **Next**.
7. Click **Finish**.
8. Open the certificate in your preferred text editor.  This data will be used in the creation of the Kasm SAML configuration in the next section.

```{figure} /images/saml/adfs/cert_data.png
:align: center
:width: 70%
```

### Create a new SAML configuration in Kasm

1. Log into the Kasm UI as an administrator.
2. Select **Authentication** -> **SAML** -> **Create New Configuration**.
3. The **SAML 2.0 Configuration** page will auto-generate the **Entity ID**, **Single Sign On Service**, **Single Logout Server**, and **Relay State** values.
4. Edit the auto-generated **Entity ID** value to remove the query argument in the URL. (e.g <https://kasm.server/api/metadata/?id=123>  => <https://kasm.server/api/metadata/> )
5. Update the form with the following entries.

```{eval-rst}
+-------------------------------------------+-----------------------------------------------------+
| **Setting**                               | **Value**                                           |
+-------------------------------------------+-----------------------------------------------------+
| ADFS                                      | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Debug                                     | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Digest Algorithm                          | http://www.w3.org/2001/04/xmlenc#sha256             |
+-------------------------------------------+-----------------------------------------------------+
| Enabled                                   | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Group Member Attribute                    | http://schemas.xmlsoap.org/claims/Group             |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Entity Id              | http://<adfs server>/adfs/services/trust            |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Single Logout Service: | https://<adfs server>/adfs/ls/?wa=wsignout1.0       |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Single Sign On Service | https://<adfs server>/adfs/ls/                      |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: X509 Certificate       | *Certificate data from the previous section*        |
+-------------------------------------------+-----------------------------------------------------+
| Name                                      | ADFS                                                |
+-------------------------------------------+-----------------------------------------------------+
| NameID Attribute                          | emailAddress                                        |
+-------------------------------------------+-----------------------------------------------------+
| Signature Algorithm                       | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256   |
+-------------------------------------------+-----------------------------------------------------+
| Want Attribute Statement                  | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Want Assertion Signed Statement           | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Want Name ID                              | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
| Want Name ID                              | *Checked*                                           |
+-------------------------------------------+-----------------------------------------------------+
```

```{figure} /images/saml/adfs/kasm_saml_configurations.png
:align: center
:width: 70%

**Kasm SAML Configurations**
```

6. Click **Submit** to save the changes.
7. Click the **Edit** icon to re-open to SAML configuration. Leave this page open and continue to the next steps.

### ADFS Party Trust

1. Log into the ADFS Management Console.
2. Right-Click **Relying Party Trusts** and select **Add Relying Party Trust**. The wizard will open.
3. Select **Claims aware** then click **Start**.

```{figure} /images/saml/adfs/claims_aware.png
:align: center
:width: 90%
```

4. Select **Enter data about the relying party manually** and click **Next**.

```{figure} /images/saml/adfs/manual.png
:align: center
:width: 90%
```

5. Enter a **Display Name** and select **Next** e.g (Kasm ADFS).

```{figure} /images/saml/adfs/display_name.png
:align: center
:width: 90%
```

6. Click **Next** to accept the defaults for the **Configure Certificate** step.

```{figure} /images/saml/adfs/encrypt_claims.png
:align: center
:width: 90%
```

7. Select **Enable support for the SAML 2.0 WebSSO Protocol**.  Enter the **Single Sign On Server** URL from the **Service Provider** section of the KASM SAML configuration page started in the previous section. Click **Next**.

```{figure} /images/saml/adfs/enable_sso.png
:align: center
:width: 90%
```

8. In the **Relay party trust identifier**, enter the **Entity ID** from the Service Provider section from the Kasm SAML configuration page started in the previous section. Click **Add**, then Click **Next**.

```{figure} /images/saml/adfs/trust_providers.png
:align: center
:width: 90%
```

9. Select **Permit Everyone**, then click **Next**.

```{figure} /images/saml/adfs/access_control_policy.png
:align: center
:width: 90%
```

10. No changes are needed for the **Ready to Add Trust** section. Click **Next**.
11. At the **Finish** screen, Uncheck **Configure claims issuance policy for this application**, then click **Close**.
12. Right click the new trust (e.g Kasm ADFS) and select **Properties**.

```{figure} /images/saml/adfs/trust_properties.png
:align: center
:width: 90%
```

13. Select the **Endpoints** tab, then click **Add SAML**.
14. Select **SAML Logout** as the **Endpoint type** and select **POST** as the **Binding**.
15. Enter **https://\<adfs.server>/adfs/ls/?wa=wsignout1.0** in the **Trusted URL**. Click **OK**, then **OK** again.

```{figure} /images/saml/adfs/saml_logout.png
:align: center
:width: 70%
```

### ADFS Edit Claim Issuance Policy

1. From the ADFS management console, select **Relying Party Trusts**, right click trust previously configured (.e.g Kasm ADFS) and select **Edit Claim Issuance Policy**.

```{figure} /images/saml/adfs/edit_issuance_policy.png
:align: center
:width: 90%
```

2. Click **Add Rule**.

```{figure} /images/saml/adfs/issuance_policy.png
:align: center
:width: 90%
```

3. In the **Claim rule template** field, select **Send LDAP Attributes as Claims**. Click **Next**.

```{figure} /images/saml/adfs/select_template.png
:align: center
:width: 90%
```

4. Enter a name in **Claim rule name**, then select **Active Directory** in the **Attribute store** drop down.
5. Select **E-Mail-Addresses** as the **LDAP Attribute**. Select **E-Mail-Address** as the **Outgoing Claim Type**.
6. In another entry, select **Is-Member-Of-DL** in **LDAP Attribute** and select **Group** in the **Outgoing Claim Type**. Click **Finish**.

```{figure} /images/saml/adfs/email_claim.png
:align: center
:width: 90%
```

6. Create another rule to expose the email address as the NameID. Click **Add Rule**.
7. Select **Transform an Incoming Claim** from the **Claim rule template** dropdown. Click **Next**.

```{figure} /images/saml/adfs/transform_claim.png
:align: center
:width: 90%
```

08. Enter a name in **Claim rule name**.
09. Select **E-Mail Address** for **Incoming claim type**.
10. Select **Name ID** for **Outgoing claim type**.
11. Select **Email** for **Outgoing name ID format** and click **Finish**.

```{figure} /images/saml/adfs/transform_email_claim.png
:align: center
:width: 90%
```

12. Back in the **Edit Claim Issuance Policy** window, click **OK**

```{figure} /images/saml/adfs/finish_issuance_policy.png
:align: center
:width: 90%
```

### Verifying Access

1. Navigate to the Kasm UI Login screen. An "ADFS" button is visible representing the SAML config.
2. Click **ADFS**

```{figure} /images/saml/adfs/kasm_login.png
:align: center
:width: 70%
```

3. The user is navigated to the ADFS login portal. Enter the username/password of the desired user.

```{figure} /images/saml/adfs/adfs_login.png
:align: center
:width: 70%
```

4. The user is redirected and logged into Kasm.
5. From the Kasm UI select Logout. The user is logged out and redirected to the ADFS logout page.

```{figure} /images/saml/adfs/adfs_logout.png
:align: center
:width: 70%
```

### ADFS Group Mapping

In the previous configuration ADFS was configured to pass along the user's Active Directory group membership in the SAML assertions.
Administrators can leverage this to automatically map users to groups defined in Kasm based off their group membership in Active Directory.

1. Log into the Kasm UI as an administrator.
2. Select **Groups** then click **Create New Group**.
3. Enter a **Name** and **Priority**.
4. Save the new group by clicking **Submit**.

```{figure} /images/groups/edit_group.png
:align: center
:width: 70%
```

5. On the groups screen, using the three dot menu select **View** on the group that was just created.
6. Scroll to the bottom of the screen and select **Add SSO Mapping**.
7. Select the SAML IDP that was created above "SAML - ADFS" for the **SSO Provider**.
8. Enter the group DN in **Group Attributes** (e.g CN=MyGroup,OU=MyOrg,DC=kasm,DC=core).
9. Click **Add**.

```{figure} /images/saml/adfs/saml_group.png
:align: center
:width: 70%
```

7. Login via SAML as a user that is a member of the group. Notice the users is automatically placed in the Kasm group.