---
myst:
html_meta:
"description lang=en": "Connecting Kasm Workspaces to Active Directory Federation Services on Windows Server 2016."
"keywords": "Kasm, Microsoft, ADFS, Active Directory, SAML"
"property=og:locale": "en_US"
---
```{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
**View Cerificate**
```
3. Select the **Details** tab, then click **Copy to File**.
```{figure} /images/saml/adfs/copy_certificate.png
:align: center
**Copy Certificate**
```
4. In the **Certificate Export Wizard**, click **Next**.
```{figure} /images/saml/adfs/certificate_export_wizard.png
:align: center
**Export Certificate**
```
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
**Certificate Contents**
```
### Create a new SAML configuration in Kasm
1. Log into the Kasm UI as an administrator.
2. Select **Access Management** -> **Authentication** -> **SAML** -> **Add 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 => )
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 | :code:`http://schemas.xmlsoap.org/claims/Group` |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Entity Id | http:///adfs/services/trust |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Single Logout Service: | https:///adfs/ls/?wa=wsignout1.0 |
+-------------------------------------------+-----------------------------------------------------+
| Identity Provider: Single Sign On Service | https:///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 | *Checked* |
+-------------------------------------------+-----------------------------------------------------+
| Want Name ID | *Checked* |
+-------------------------------------------+-----------------------------------------------------+
```
```{figure} /images/saml/adfs/kasm_saml_configurations.webp
:align: center
**Kasm SAML Configurations**
```
6. Click **Save** 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
**Claims Aware**
```
4. Select **Enter data about the relying party manually** and click **Next**.
```{figure} /images/saml/adfs/manual.png
:align: center
**Relaying Party Manually**
```
5. Enter a **Display Name** and select **Next** e.g (Kasm ADFS).
```{figure} /images/saml/adfs/display_name.png
:align: center
**Display Name**
```
6. Click **Next** to accept the defaults for the **Configure Certificate** step.
```{figure} /images/saml/adfs/encrypt_claims.png
:align: center
**Configure Certificate**
```
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
**Enable SSO**
```
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
**Add Service Provider**
```
9. Select **Permit Everyone**, then click **Next**.
```{figure} /images/saml/adfs/access_control_policy.png
:align: center
**Permit Access**
```
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
**ADFS Properties**
```
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/ls/?wa=wsignout1.0** in the **Trusted URL**. Click **OK**, then **OK** again.
```{figure} /images/saml/adfs/saml_logout.png
:align: center
**Logout Configuration**
```
### 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
**Edit Issuance Policy**
```
2. Click **Add Rule**.
```{figure} /images/saml/adfs/issuance_policy.png
:align: center
**Modify Issuance Policy**
```
3. In the **Claim rule template** field, select **Send LDAP Attributes as Claims**. Click **Next**.
```{figure} /images/saml/adfs/select_template.png
:align: center
**Select Template**
```
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
**Email Claim**
```
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
**Claim Rule Template**
```
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
**Save Email Claim Rule**
```
12. Back in the **Edit Claim Issuance Policy** window, click **OK**
```{figure} /images/saml/adfs/finish_issuance_policy.png
:align: center
**Edit Issuance Policy**
```
### 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.webp
:align: center
**Kasm Login**
```
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
**ADFS Login**
```
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
**ADFS Logout**
```
### 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 **Access Management** -> **Groups** then click **Add Group**.
3. Enter a **Name** and **Priority**.
4. Save the new group by clicking **Save**.
```{figure} /images/groups/new_group.webp
:align: center
**New Group**
```
5. On the groups screen, using the arrow menu select **Edit** on the group that was just created.
6. Navigate to the **SSO Group Mappings** tab 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 **Submit**.
```{figure} /images/saml/adfs/saml_group.webp
:align: center
**SAML SSO Group Mapping**
```
7. Login via SAML as a user that is a member of the group. Notice the users is automatically placed in the Kasm group.