.. title:: Azure Active Directory SAML Setup Azure Active Directory SAML Setup ================================= 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. Check **Enable** and enter a **Display Name**. e.g (Azure AD) 5. Enter `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` in **Group Member Attribute** 6. Enter `emailAddress` in **NameID Attribute** .. figure:: /images/saml/azure/kasm_saml_configurations.png :width: 70% :align: center **Kasm SAML Configurations** 5. Leave this page open and continue to the next steps. Add a new application in Azure ------------------------------ 1. Navigate to **Azure Active Directory** in the Portal. .. figure:: /images/saml/azure/portal.png :width: 70% :align: center **Azure Portal** 2. Under the **Manage** section of the menu, select **Enterprise applications**. .. figure:: /images/saml/azure/enterprise_apps.png :width: 40% :align: center **Enterprise Applications** 3. Click the **New Application** button and select **Non-Gallery application**. Provide a name. e.g (**Kasm**) and click **Add** .. figure:: /images/saml/azure/create_application.png :width: 70% :align: center **New Applications** Basic SAML Configurations ------------------------- 1. Select **Single Sign-On** under the **Manage** Menu. 2. Select **SAML**. 3. Select **Edit** next to the **Basic SAML Configuration** .. figure:: /images/saml/azure/single_sign_on.png :width: 70% :align: center **SAML Single Sign-On** 4. Copy the **Service Provider** entries from the Kasm SAML Configurations started in the previous section into the Basic SAML configurations and click **Save** , and close the section. +------------------------+--------------------------------------------+ | **Kasm Property Name** | **Azure Property Name** | +------------------------+--------------------------------------------+ | Entity ID | Identifier (Entity ID) | +------------------------+--------------------------------------------+ | Single Sign On Service | Reply URL (Assertion Consumer Service URL) | +------------------------+--------------------------------------------+ | Single Logout Service | Logout URL | +------------------------+--------------------------------------------+ | Relay State | Relay State | +------------------------+--------------------------------------------+ .. figure:: /images/saml/azure/basic_saml_configurations.png :width: 70% :align: center **Basic SAML Configurations** User Attributes and Claims -------------------------- 1. Select **Single Sign-On** under the **Manage** Menu. 2. Select **SAML**. 3. Select **Edit** next to the **User Attributes and Claims** 4. Click **Add a Group to Claim** .. figure:: /images/saml/azure/add_group_to_claims.png :width: 70% :align: center **Add a Group to Claim** 5. Select **Security Groups**, leave the **Source Attributes** as **Group ID** and click **Save** then close the section. .. figure:: /images/saml/azure/group_claims.png :width: 70% :align: center **Group Claims** SAML Signing Certificate ------------------------ 1. Select **Single Sign-On** under the **Manage** Menu. 2. Select **SAML**. 3. Click **Download** next to **Certificate (Base64)** in the **SAML Signing Certificate** section . Save this file for later 4. Select **Edit** next to the **SAML Signing Certificate** 5. Change the **Singing Algorithm** to **SHA-1** and click **Save**. Close the section. .. figure:: /images/saml/azure/saml_singing_certificate.png :width: 70% :align: center **Singing Certificate** 6. Open the Base64 certificate that was downloaded in the earlier step in a text editor. Copy the contents into the **X509 Certificate** setting in the **Identity Provider** section of the Kasm configuration .. figure:: /images/saml/azure/x509_certificate.png :width: 70% :align: center **X509 Certificate** Set Up Kasm ----------- 1. Select **Single Sign-On** under the **Manage** Menu. 2. Select **SAML**. 3. Review *Section 4* , **Set Up Kasm**. Copy the properties into the **Identity Provider** options in the Kasm Configuration. +--------------------------------------------+-------------------------+ | **Kasm Property Name** | **Azure Property Name** | +--------------------------------------------+-------------------------+ | Single Sign On Service / SAML 2.0 Endpoint | Login URL | +--------------------------------------------+-------------------------+ | Entity ID | Azure AD Identifier | +--------------------------------------------+-------------------------+ | Single Logout Service / SLO Endpoint | Logout URL | +--------------------------------------------+-------------------------+ .. figure:: /images/saml/azure/identity_provider.png :width: 70% :align: center **Identity Provider** 4. In the **Advanced Settings** of check **Want Assertion Signed** and click **Submit** Mapping Users ------------- You must assign users or groups to the Azure Kasm application. This will provide users access to login. Azure will then pass all user group memberships during login so that Kasm can determine Authorization (e.g mapping AD groups to Kasm groups) In this example, a **Kasm Users** and **Kasm Admin** groups were defined. 1. Navigate to **Azure Active Directory** in the Portal. 2. Under the Manage section of the menu, select **Enterprise applications**. 3. Search for **Kasm** and select it. 4. Click **Users and Groups** under the **Manage** menu. 5. Click **Add Users** and add the desired users and group assignments. 6. Inspect the desired groups and note the **Object ID**. This will be used to map to Kasm groups. .. figure:: /images/saml/azure/group_assignments.png :width: 70% :align: center **Group Assignments** 7. Log into the Kasm UI as an administrator. 8. Select **Groups**, then using the three dot menu click **View** next to the **Administrators** Group. 9. Scroll to the bottom of the screen and select **Add SSO Mapping**. 10. Select "SAML - Azure AD" as the **SSO Provider** and enter the **Object Id** for the desired Azure AD Security group previously configured into the **Group Attributes** field. .. figure:: /images/saml/azure/update_group.png :width: 70% :align: center **Add SSO Mapping** Testing Access -------------- 1. Log out of the Kasm UI if already logged in. 2. Navigate to the Kasm UI login page. .. figure:: /images/saml/azure/kasm_login.png :width: 70% :align: center **Kasm Login** 3. Click Azure AD to initiate the SAML SSO process. .. figure:: /images/saml/azure/azure_login.png :width: 70% :align: center **Azure Login** Known Issues ------------ SLO Error AADSTS75005 ^^^^^^^^^^^^^^^^^^^^^ Azure AD may present the following error when a user logs out the application: .. code-block:: Bash AADSTS75005: The request is not a valid SAML 2.0 protocol message. In some Azure AD deployments, Microsoft will generate a SLO URL similar to :code:`https://login.microsoftonline.com//saml2` This endpoint requires an encoding that is not currently supported by Kasm. The workaround is to utilize the older federated SLO endpoint :code:`https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0` for the **Single Logout Service/SLO Endpoint** in the Kasm SAML Configuration.