--- title: "SAML Configuration in Azure" slug: "saml-configuration-in-azure" updated: 2024-12-17T11:11:02Z published: 2024-12-17T11:11:02Z canonical: "help.hyperscience.ai/saml-configuration-in-azure" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt > Use this file to discover all available pages before exploring further. # SAML Configuration in Azure These instructions explain how to configure Hyperscience to use an Azure application as an identity provider. For more information about configuring SAML in Azure, see Microsoft’s [Single sign-on SAML protocol](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-saml-single-sign-on). ## 1) Create a new enterprise application under your Azure Active Directory. ## 2) In the “Single sign-on” section of the application, choose “SAML.” ## 3) Complete the “Basic SAML Configuration” section. - Both the **Identifier** and **Reply URL** fields should contain the URL of the Hyperscience instance. - The other fields should be left empty. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/SAML_Azure_Basic SAML Configuration.png) ## 4) Complete the “User Attributes & Claims” section. In the authentication flow for a user, the Hyperscience application requires a list of groups that the user belongs to. Groups are sent via a *group claim*, which can be configured in the **User Attributes & Claims** tab. To add a group claim: 1. Click **Add a group claim**, and select which Azure AD groups to send. - If you are unsure, select **Groups assigned to the application**. 2. In the **Source** **attribute** drop-down list, select **Group ID**. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/SAML_Azure_Group Claims.png) > [!NOTE] > Using group `displayName` instead of `groupId` > > To avoid working with Group ID, you can select **Groups assigned to the application**. Then, in the **Source attribute** drop-down list, select **Cloud-only group display name**, which sends the group name in the group claim. ## 5) Configure signing options in the “SAML Signing Certificate” section. In the **Signing Option** drop-down list, select **Sign SAML response and assertion**. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/SAML_Azure_Signing Option(1).png) With the above steps completed, the configuration of your Azure Enterprise application is finished. However, you may want to remain logged in to retrieve the values listed in the next step. ## 6) Update the “.env” file for the Hyperscience application. Add the following lines to your “.env” file: ```bash HS_LOGIN_ENABLE_SAML=true SAML_ENTITY_ID=https://hyperscience.example.com SAML_METADATA_URL=https://login.microsoftonline.com/427a.....562/federationmetadata/2007-06/federationmetadata.xml?appid=919cd79.... SAML_ADMIN_PERMISSION_ROLE=e13e408.... SAML_USER_AUTH_ATTR=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups SAML_USER_FIRST_NAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname SAML_USER_LAST_NAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname SAML_USER_EMAIL_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress SAML_USERNAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name ``` Note that you need to change the values of `SAML_ENTITY_ID`, `SAML_METADATA_URL`, and `SAML_ADMIN_PERMISSION_ROLE` to match your Azure AD configuration: - The value of `SAML_ENTITY_ID` should be the same as the value of the Identifier field in the “Basic SAML configuration” section. - The value of `SAML_METADATA_URL` can be copied from the **App Federation Metadata URL** field in the “SAML Signing Certificate” section. - The value `SAML_ADMIN_PERMISSION_ROLE` should be the identifier of the group dedicated to system administrators in the Hyperscience application. - The value here is dependent on how [step 4](/deployment/docs/saml-configuration-in-azure#4-complete-the-“user-attributes-claims”-section) in this guide was completed. If it was completed according to this guide, the Group Claims should be set to **Group ID**, and the value set here should be the group ID of the corresponding group. - Example of a group ID: `e4552156-2d43-4403-9299-7b3d` - Example of a value that is not a group ID: `CoreOps` - If **Group ID** is not set, then you’ll need to set the corresponding value here for the group’s **Source** attribute that is set in Azure. ## Alternative configuration using *SAML_METADATA_PATH* instead of *SAML_METADATA_URL* Hyperscience’s SAML integration requires SAML metadata. It can be provided via a URL or via an XML file stored on every virtual machine. > [!CAUTION] > This configuration is **not recommended** — the recommended configuration uses the `SAML_METADATA_URL` configuration property. By using a metadata XML file, there is a higher risk of different virtual machines in the Hyperscience installation to be configured differently. a. Add the following variables to your ".env" file, editing the values of `SAML_ENTITY_ID`, `SAML_METADATA_URL`, and `SAML_ADMIN_PERMISSION_ROLE` to match your Azure AD configuration: ```bash HS_LOGIN_ENABLE_SAML=true SAML_ENTITY_ID=https://hyperscience.example.com SAML_METADATA_PATH=/etc/nginx/certs/metadata.xml SAML_ADMIN_PERMISSION_ROLE=e13e408.... SAML_USER_AUTH_ATTR=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups SAML_USER_FIRST_NAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname SAML_USER_LAST_NAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname SAML_USER_EMAIL_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress SAML_USERNAME_ATTR=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name ``` > [!NOTE] > The path given for `SAML_METADATA_PATH` is a path that is valid inside Hyperscience containers. It should start with `/etc/nginx/certs`. b. Download the actual metadata XML by clicking the **Download** link next to the **Federation Metadata XML** item in the “SAML Signing Certificate” section. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/SAML_Azure_Federation Metadata XML(1).png) c. Save the downloaded file under your `$HS_PATH/certs` directory as `metadata.xml`. - If the directory `$HS_PATH/certs` does not exist, you need to create it. - The directory should be owned by the user and group with `id` `1000`; run `chown 1000:1000 $HS_PATH/certs` to assign ownership accordingly. d. The `metadata.xml` file should be owned by the user and group with `id` `1000`; run `chown 1000:1000 $HS_PATH/cersts/metadata.xml` to assign ownership accordingly.