---
title: "SAML"
slug: "saml"
updated: 2026-07-20T14:31:49Z
published: 2026-07-20T14:31:49Z
canonical: "help.hyperscience.ai/saml"
---

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

SAML (Security Assertion Markup Language) is an open standard that allows identity providers (IdPs) to pass authorization credentials to service providers (SPs) via transactions that use XML (extensible markup language) for communication between the SP and the IdP.

## On-premise / private cloud instances

### Local setup

#### Required configuration steps

Hyperscience currently supports SP-Initiated SSO. To enable SAML authentication in Hyperscience:

1. Add the following setting to your “.env*”* file:

```plaintext
# Enables SAML Authentication
HS_LOGIN_ENABLE_SAML=true
```

> [!CAUTION]
> **Important!**
> 
> Only ONE of SAML, OpenID Connect, LDAP, or Google authentication can be enabled.

1. Set the value of *SAML_ENTITY_ID* to the same value that is registered with your IdP. The Entity ID should be a unique identifier for your Hyperscience installation and is usually set to its URL.

```plaintext
SAML_ENTITY_ID=http://your.hyperscience.url
```

1. Make an XML metadata file that describes the configuration of your IdP available to your Hyperscience installation. We provide 2 options for this step:

#### Remote metadata URL

If your IdP's metadata is publicly available, you can point Hyperscience to that URL:

```plaintext
SAML_METADATA_URL=http://idp.metadata.url
```

For example, your *SAML_METADATA_URL* variable may look something like this:

```plaintext
SAML_METADATA_URL=https://www.server.com:8080/context/saml/metadata
```

#### Local metadata file

If the metadata is not hosted or is not accessible to your Hyperscience installation, you may download its file from your IdP and make it accessible to Hyperscience:

1. Create the `/mnt/hs/certs` folder on each machine running Hyperscience: `mkdir -p /mnt/hs/certs`
2. Apply the proper SELinux context, if enabled (Redhat has this context enabled by default): `chcon -t container_file_t -R /mnt/hs/certs`
3. Create the `/mnt/hs/certs/metadata.xml` file, and enter the IdP metadata in that file.
4. Set `SAML_METADATA_PATH=/etc/nginx/certs/metadata.xml`.

> [!NOTE]
> This internal-path specification does not exist on the machine running Hyperscience; you can copy and paste this value into the “.env” file.

1. Provide the group values that will map to the admin role in Hyperscience. Currently, we accept one possible admin role.

```plaintext
SAML_ADMIN_PERMISSION_ROLE=your_admin_group
```

#### Identity configuration

A user's identity in SAML is mapped to their username in Hyperscience. By default, Hyperscience assumes that identity is case-sensitive but configurable. See the table below for more details:

| **Environment Variable** | **Default** | **Description** |
| --- | --- | --- |
| `SAML_DJANGO_USER_MAIN_ATTRIBUTE_CASE_SENSITIVE` | `TRUE` | Identity in the IdP is case-sensitive. |

#### Configuring attribute mapping

Hyperscience supports SAML attribute mapping, allowing you to auto-populate user-specific information in Hyperscience based on the data stored in your IdP. Below is a list of the supported attribute values. These values are fully customizable.

| **Environment Variable** | **Default (Attribute Name)** | **Description** |
| --- | --- | --- |
| `SAML_USER_AUTH_ATTR` | `authorities` | The name of the attribute used to identify the user's group |
| `SAML_USER_FIRST_NAME_ATTR` | `FirstName` | Name of IdP's attribute for a user's first name |
| `SAML_USER_LAST_NAME_ATTR` | `LastName` | Name of IdP's attribute for a user's last name |
| `SAML_USER_EMAIL_ATTR` | `mail` | Name of IdP's attribute for a user's email address |

#### Configuring assertions and authentication request options

**Response and assertions signature requirements**

Hyperscience supports both signed and unsigned assertions and responses from the identity provider. In addition, you can configure Hyperscience to accept only signed responses. You can control this behavior via the following “.env” file variables (default values shown below):

```bash
SAML_WANT_ASSERTIONS_SIGNED=False
SAML_WANT_RESPONSE_SIGNED=True
```

> [!NOTE]
> Note that the *SAML_WANT_RESPONSE_SIGNED* variable is available only in v32 and later.

**Encrypted assertions**

In certain deployment scenarios, an identity provider encrypts the assertions within a response. To enable Hyperscience to decrypt such responses you need to:

1. Obtain a certificate and key for decryption from the identity provider. See your identity provider’s documentation for specific steps on how to complete this process.
2. Create the `/mnt/hs/certs/saml` folder on each machine running Hyperscience: `mkdir -p /mnt/hs/certs/saml`
3. Apply the proper SELinux context, if enabled (Redhat has it enabled by default):
  - `chcon -t container_file_t -R /mnt/hs/certs`
  - `chcon -t container_file_t -R /mnt/hs/certs/saml`
4. Create the following files:
  - `/mnt/hs/certs/saml/encrypt-private-key.pem` (holding the PEM-encoded private key of the decryption certificate)
  - `/mnt/hs/certs/saml/encrypt-public-cert.pem` (holding the PEM-encoded decryption certificate)
5. Set `SAML_CONFIG_DIR=/etc/nginx/certs/saml`
6. Set `SAML_DECRYPT_ASSERTIONS=True`

> [!NOTE]
> This internal-path specification does not exist on the machine running Hyperscience; you can copy and paste this value into the “.env” file.

**Signed authentication requests**

Certain deployment scenarios may require Hyperscience to send signed authentication requests to the identity provider. To configure this behavior, follow these steps:

1. Obtain the certificate and key for request signing. Doing so may require additional setup on the identity provider’s side. See the instructions for your IdP.
2. Create the `/mnt/hs/certs/saml` folder on each machine running Hyperscience: `mkdir -p /mnt/hs/certs/saml`
3. Apply the proper SELinux context, if applicable:
  - `chcon -t container_file_t -R /mnt/hs/certs`
  - `chcon -t container_file_t -R /mnt/hs/certs/saml`
4. Create the following files:
  - `/mnt/hs/certs/saml/sign-private-key.pem `(holding the PEM-encoded private key of the signing certificate)
  - `/mnt/hs/certs/saml/sign-public-cert.pem` (holding the PEM-encoded signing certificate)
5. Set `SAML_CONFIG_DIR=/etc/nginx/certs/saml`

> [!NOTE]
> This internal-path specification does not exist on the machine running Hyperscience; you can copy and paste this value into the “.env” file.
6. Set `SAML_AUTHN_REQUESTS_SIGNED=True`

#### (Optional) Overriding Assertion Consumer Service URL

If you're running v33.1.28 or later, you can use the `SAML_ACS_URL ".env"` file variable to override the assertion consumer service (ACS) URL. Hyperscience tries to construct the ACS URL automatically based on application configurations and request headers. In some cases, however, (e.g., certain load-balancer setups, load balancers terminating HTTPS, Kubernetes deployments), a valid URL cannot be generated, leading to errors upon login. In these cases, include the `SAML_ACS_URL` variable in your `".env" `file, and set it to a URL in the following format: `<full_URL_including_protocol_to_Hyperscience_base>/saml2/acs/`

#### (Optional) Remote metadata signature validation

By default, Hyperscience validates remote metadata signatures using the embedded certificate. If you want to use another certificate instead, you can do so by entering its path as a value for the `SAML_METADATA_CERT_PATH` ".env" file variable.

**Important!**

If you choose to provide a certificate file, the file and its path must meet these requirements:

- The certificate must be in PEM format.
- Because Hyperscience runs in containers, the certificate file (e.g., *cert.pem*) must be present on the host and made available to the application through a bind mount. We recommend placing the metadata file in an existing bind mount for this purpose, such as` /mnt/hs/certs`.
- You must set the path to the location of the mount inside the container. Using the previous example, you would enter the following in your ".env" file:

```bash
SAML_METADATA_CERT_PATH=/etc/nginx/certs/cert.pem
```

### Remote setup

#### Okta

These instructions will configure Hyperscience to use an Okta application as an IdP. They use as many default values as possible, with the minimal configuration necessary on the Hyperscience side.

To set up your Okta application:

1. Configure the General settings:
  1. Configure your application to use SAML authentication.
  2. Set your **Single sign on URL** to the domain where Hyperscience is hosted, at the path `/saml2/acs/,` ***including the trailing slash***.
  3. Set your **Audience URI** to your application's domain. This value must match the value of the `SAML_ENTITY_ID` setting.
  4. Set the **Application username** to the field that you want to use to populate usernames inside Hyperscience.

![okta_general.png](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/17580407307405.png)
2. To map first name, last name, and email from Okta to Hyperscience, set the following user attributes. These values will work with Hyperscience out of the box.

![okta_user_attributes.png](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/17580420240269.png)
3. We require group information to determine a user's access permissions inside Hyperscience. To send this information, create an Okta filter that includes all groups of users who will be accessing Hyperscience. You can use the **Contains** or **Match Regex** filter functionality to do so. These groups should match the values of *SAML_STAFF_PERMISSION_ROLES* and *SAML_ADMIN_PERMISSION_ROLE.*

![OktaEditedScreenshot2.png](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/5792469305613.png) For more specific information on the Regex configuration, refer to [OKTA’s documentation](https://support.okta.com/help/s/article/how-to-filter-groups-with-regex-in-okta?language=en_US) for specific examples.
4. You can find the link to your IdP's metadata by clicking **Identity Provider metadata**, as shown below. Copy this link's URL, and set the value of `SAML_METADATA_URL` to this URL.

![okta_metadata_revised.png](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/5792380172557.png)
5. Configure your Hyperscience “.env” file:

```bash
# Required settings
HS_LOGIN_ENABLE_SAML=true
SAML_ENTITY_ID=http://<your_Hyperscience_URL>
SAML_METADATA_URL=https://<your_domain>.okta.com/app/<app_ID>/sso/saml/metadata
SAML_ADMIN_PERMISSION_ROLE=admin_group
```

> [!NOTE]
> To learn how to map authentication groups from your identity provider to Hyperscience permission groups, see the "Managing Authentication Groups" article for your version of Hyperscience ( [v38](/v38/docs/managing-authentication-groups) | [v39](/v39/docs/managing-authentication-groups) | [v40](/v40/docs/managing-authentication-groups) | [v41](https://help.hyperscience.com/v41/docs/managing-authentication-groups) | [v42](/v42/docs/managing-authentication-groups) | [v43](/v43/docs/managing-authentication-groups) ).

### Troubleshooting

For the purpose of troubleshooting, you can enable SAML debug mode. When this mode is enabled, the system produces detailed log entries with requests, assertions, and other data. To enable debug mode, enter the following in the ".env" file:

```bash
SAML_DEBUG=true
```

## SaaS instances

The steps required to integrate your SAML IdP with Hyperscience depend on the version of Hyperscience you’re running.

### New deployments of v38 and later

If you want to integrate your SAML IdP with Hyperscience, you can set up and manage that integration in the Hyperscience application.

> [!NOTE]
> This feature is only available for new deployments of v38 and later. If you’ve upgraded to v38 and currently have SAML authentication set up in your instance, your integration will still be managed by Hyperscience. See [v37 and earlier / Upgrades to v38](/deployment/docs/saml#v37-and-earlier-upgrades-to-v38) for more information.

#### Prerequisites

Before starting the setup process described below, ensure that you have:

- Communicated to your Hyperscience representative that you want to manage your SAML setup in your application
- Added at least one user record to your SAML authentication provider

#### Integrating your IdP with Hyperscience

1. In your IdP, create an application. Hyperscience will use this application to connect to your IdP.
2. In your IdP, create at least one user group for Hyperscience administrators and assign a user to it. You need this group name for the next steps.
3. In the Hyperscience application, go to the System Settings page (**Administration** > **System Settings**), and in the **View** drop-down menu at the top of the page, click on **Security & Identity**.
4. In the **Identity Provider** card, click **Edit**.
5. Select the **Enabled** checkbox.
6. In the **Identity Provider Name** field, enter a name for the IdP. This name will appear on the **Log In** button on the login page (**Log In With <Identity Provider Name>**, e.g., **Log In With Azure AD**).
7. In the **Identity Provider Organization** field, enter a name for the main point of contact for the IdP at your organization.
8. Click on **SAML**.
9. Enter the requested information in the top five fields. The first two fields are required, and either the third or fourth field is also required, depending on your preferred configuration.
10. In the bottom six fields (**Username Field Name on the SAML Data** up to and including **Staff Groups on the IdP Side (Comma Separated: GroupA,GroupB)**), enter the requested field mappings from your IdP to Hyperscience. This information can be obtained from the metadata XML from the IdP.
11. Select the checkboxes for any of the optional settings you would like to apply to your integration.
12. Click **Show Hyperscience configuration for selected identity provider.**
13. Copy the information from the Information to use with your identity provider window that appears, and paste it into the respective fields in your IdP.
14. Click **Save** at the top of the **Identity Provider** card.
15. Create additional groups in your IdP for non-admin users, and map them to their Hyperscience roles by following the instructions in Adding an authentication group.

### v37 and earlier / Upgrades to v38

You can integrate your SAML authentication provider with Hyperscience by providing the following information to your Hyperscience representative:

- The SAML group name for users accessing the Hyperscience instance
- The SAML group name for users who should be in the “System Admin” permission group in Hyperscience
- IdP metadata
  - SAML metadata XML file
  - IdP Cert (b64-encoded), if not included in the metadata XML file
  - SAML Request Binding (defaults to HTTP POST)
- SAML SSO URL
- SAML SSO destination
- SAML username assertion
  - This assertion should contain the user’s email address.
  - Defaults to *subjectNameId*.
- Should SP sign SAML requests sent to the IdP? (yes/no)
  - If yes, specify the signature algorithm (defaults to SHA-256).
- Should IdP sign SIGM requests sent to the SP? (yes/no)
  - If yes, specify the signature algorithm (defaults to SHA-256).

After we receive this information, we will set up the integration with your IdP and Hyperscience.