SAML Configuration in Azure

  • Updated on Dec 17, 2024
  • Published on Dec 16, 2024
  • 3 minute(s) read
Prev Next

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.

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.

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:

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

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:

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

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.

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.