# SAML Configuration in Azure

- Updated on Dec 17, 2024
- Published on Dec 16, 2024

- 3 minute(s) read

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.

## 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**.

> 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**.

.png?sv=2026-02-06&spr=https&st=2026-07-27T09%3A17%3A26Z&se=2026-07-27T09%3A30%3A26Z&sr=c&sp=r&sig=I89vQKVdINqAhHPTaGebJ3pvFC9klP2XPdChUTZqfpQ%3D)

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.

## 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.

> 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
```

b. Download the actual metadata XML by clicking the **Download** link next to the **Federation Metadata XML** item in the “SAML Signing Certificate” section.

.png?sv=2026-02-06&spr=https&st=2026-07-27T09%3A17%3A26Z&se=2026-07-27T09%3A30%3A26Z&sr=c&sp=r&sig=I89vQKVdINqAhHPTaGebJ3pvFC9klP2XPdChUTZqfpQ%3D)

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.