Set up single sign-on with SAML

Sigma supports single sign-on (SSO) with SAML. SAML SSO can provide a more streamlined and secure sign in experience for users by allowing users to sign in with one set of credentials, minimizing security risks such as credential theft.

This document covers the following: an introduction to SAML, how to configure SAML SSO for your Sigma organization, and the behavior of a user’s account type and/or teams when configuring SAML.

System and user requirements

• You must be assigned the Admin account type to configure SAML SSO for your organization.
• You must have an identity provider (IdP) set up and able to access it.

Understanding SSO and SAML

Security Assertion Markup Language (SAML) is a widely used security protocol. It provides secure authentication and authorization between a service provider (SP) and an identity provider (IdP).

• A service provider is the web application that you want to gain access to, such as Sigma.
• An identity provider is a software service that performs authentication related services (SAML, account status verification, account attribute declaration). Examples of IdPs include Okta and Azure Entra ID.

Service Provider (SP) and Identity Provider (IdP) authentication

By default, Sigma supports SP-initiated authentication via the Sigma login page. To also use IdP-initiated authentication from the IdP console, you must provide your IdP with a RelayState value that you can retrieve from Sigma.

📘

If your organization is currently using password authentication, all members of your organization will retain access to their assets and documents after transitioning to SAML SSO authentication, as long as their email addresses remain the same.

Configure SAML SSO for your Sigma Organization

To configure SAML SSO for your Sigma organization, perform the required steps in your IdP and Sigma:

1. Configure your identity provider with information from Sigma.

   • If you want to authenticate to multiple Sigma organizations with one IdP, enable unique SAML entity IDs. See Enable unique SAML entity IDs.

2. Configure SAML SSO in Sigma with information from your IdP.

Identify your cloud service provider

Sigma organizations can be hosted on Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). Your configuration options and the values that you need to configure the IdP are different depending on your cloud provider.

Before configuring SAML SSO, determine your Sigma organization's cloud provider:

• Go to Administration > Account > General Settings. Your cloud provider is listed in the Site section.

Step 1: Configure your identity provider

Depending on what IdP you use and where your Sigma organization is hosted, you can do one of the following to configure your IdP:

• Configure your IdP manually.
• Configure your IdP using an existing application.

Configure your IdP manually

If your company uses a different IdP than Okta, follow the documentation provided by that IdP on how to set up a SAML application, then provide the relevant details from your Sigma organization.

You can import the required fields using the Sigma metadata file and other relevant URLs for your organization, or by entering them manually.

• Retrieve the IdP configuration from Sigma.
• Manually configure IdP settings

Retrieve the IdP configuration from Sigma

To retrieve the relevant details for your IdP configuration from Sigma, do the following. The URL and URI values are specific to your organization:

1. Go to Administration > Authentication.
2. In Authentication Method and Options, select Edit.
3. Select SAML or password from the Authentication Method dropdown menu.
4. Retrieve the relevant URLs for your IdP:
   • Copy the Service provider entity ID.
   • Copy the Assertion consumer service URL, or ACS URL.
   • Copy the Relay state.
5. Return to your IdP and provide the relevant information.
6. To complete the configuration in Sigma, retrieve the IdP Login URL, which might be listed as the SAML 2.0 Endpoint (HTTP), and the IdP's X.509 signing certificate, then complete the steps in Step 2: Configure SAML SSO in Sigma.

💡

Your IdP might support importing most configuration details directly from the metadata URL, listed in Sigma as the Service provider entity ID.

Manually configure IdP settings

If you choose to manually construct and enter the relevant IdP configuration details, refer to the following table.

🚩

You must manually update the URL and URI values to use the {{baseUrl}} specific to where your Sigma organization is hosted. The {{baseUrl}} value is listed in the API endpoint column of the Supported cloud platforms and regions table.

The following table includes the relevant details to configure SAML in your IdP with Sigma as an SP:

(Optional) Enable unique SAML entity IDs

If you plan to set up multiple SAML integrations with Sigma in your IdP, such as to support logging in to different Sigma organizations, you can enable the use of unique SAML entity IDs. Enable unique SAML entity IDs in each Sigma organization that you plan to configure as an SP.

📘

If you plan to use an existing application to configure your IdP, the unique SAML entity IDs are not pre-filled and must be retrieved from Sigma. Consider configuring your IdP manually instead. See Manually configure IdP settings.

1. Go to Administration > Authentication.
2. In Authentication Method and Options, select Edit.
3. If SAML is not already set up for your Sigma organization, select SAML or password or SAML from the Authentication Method dropdown menu.
4. Turn on the toggle for Enable unique SAML entity ID.
5. Retrieve the relevant URLs for your IdP:
   • Copy the Service provider entity ID.
   • Copy the Assertion consumer service URL, or ACS URL.
   • Copy the Relay state.
6. Return to your IdP and provide the relevant information.
7. To complete the configuration in Sigma, retrieve the IdP Login URL, which might be listed as the SAML 2.0 Endpoint (HTTP), and the IdP X.509 certificate, then complete the steps in Step 2: Configure SAML SSO in Sigma.

Configure your IdP using an existing application

If your company uses Okta as your IdP and your cloud provider is either AWS US-West or GCP, you can use a pre-configured application to set up SSO access to Sigma:

• Sigma on AWS in the Okta integrations list.

• Sigma on GCP in the Okta integrations list.

  📘

  If you use the Sigma on GCP SAML integration, you must make the following changes:

  • For Entity ID, add a “/2” after “saml2” to be correctly formatted. Your Entity ID must be https://api.sigmacomputing.com/api/v2/saml2/2/metadata.xml, not https://api.sigmacomputing.com/api/v2/saml2/metadata.xml.
  • For ACS URL, if your Sigma organization is hosted on AWS, add aws- before api. For example, https://aws-api.sigmacomputing.com/api/v2/saml2/assert.

If you plan to configure unique SAML entity IDs to support authenticating to multiple Sigma organizations from one IdP, set up your configuration manually. See Manually configure IdP settings.

For more information on setting up SAML for specific IdPs, see the Sigma Community post on Guidelines For Configuring OAuth and SAML Authentication.

Step 2: Configure SAML SSO in Sigma

After providing the relevant information to your IdP, finish setting up SAML SSO by performing configuration steps in Sigma. To configure SAML SSO in Sigma, do the following:

📘

Before you start, retrieve the following details from your IdP:

• IdP Login URL, which might be listed as the SAML 2.0 Endpoint (HTTP).
• IdP X.509 signing Certificate.

1. Go to Administration > Authentication.

2. In Authentication Method and Options, select Edit.

3. Select SAML or password from the Authentication Method dropdown menu.

   💡

   When transitioning authentication methods for your Sigma organization from basic authentication to SAML, the best practice is to transition first to the SAML or password option rather than directly to requiring SAML only login for all users. With the authentication method set to SAML or password, you retain the ability to log in with a password during the transition to your IdP-based login, ensuring that you are not locked out during the configuration change. After you have confirmed that users can log in using SAML, you can transition to SAML-only login.

4. Enter your Identity Provider Login URL retrieved from your IdP. If your IdP only lists a SAML 2.0 Endpoint (HTTP), the login URL expected by Sigma is the same.

5. Enter your Identity Provider X.509 Certificate retrieved from your IdP.

6. Select Save.

7. Test your SAML configuration by logging out and logging back into Sigma. Your Sigma organization login page should now display a "Log in with SSO" option.

8. After testing to ensure users can log in using SAML, you can update your selection in the Authentication Method dropdown to choose SAML, which enforces SAML login for all users.

Update your SAML certificate in Sigma

To avoid losing access to your Sigma organization, you must ensure your SAML certificate is updated before it expires. You can view your SAML certificate’s expiration date in your IdP. Sigma sends you email notifications as this expiration date approaches at 30, 14, 7, and 1 days until the certificate expiration.

To update your SAML certificate in Sigma:

1. Go to Administration > Authentication.
2. In Authentication Method and Options, select Edit.
3. For Identity Provider X.509 Certificate, provide the new certificate from your IdP.
4. Select Save.

📘

Sigma recommends configuring certificate expiration notifications in your IdP.

If your SAML certificate has already expired and you are unable to sign in to your Sigma organization, contact your CSM or AE for assistance.

Behavior of "userRole" and "userGroups" attributes

🚧

If you make account type assignments with the userRole attribute or team membership assignments with the userGroups attribute in your IdP, do not change account type or team membership assignments in Sigma.

Configurations set in your IdP take precedence over any configurations in Sigma. For example, if you change a user's account type in Sigma, the userRole attribute is not changed in the IdP. The next time that user logs in to Sigma, the user’s account type is reset to the match the account type assigned in the userRole attribute in the IdP.

The expected behavior of the "userRole" and "userGroups" attributes depends on how they are configured in your IdP: