Single sign-on with SAML

Requirements

Admin privileges in Sigma; see Account types.
An identity provider (IdP).

Understanding SSO and SAML

What is SAML?

SAML, Security Assertion Markup Language, 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 would like to gain access to. In this case, it’s Sigma.

An identity provider is a software service that performs authentication related services (OAuth, account status verification, account attribute declaration). Examples of IdPs include Okta, OneLogin, and Google SSO.

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

By default, Sigma supports SP-only authentication via the the Sigma login page. In order to additionally use IdP-initiated authentication from the IdP's console you must provide your IdP with a RelayState / StartURL.

Configure SSO for your Sigma Organization

Follow the steps below to connect SSO for your Sigma organization. This is a multi-stage process that involves SAML configuration in both the IdP and Sigma.

[Step 1] Configure your Identity Provider

Confirm your Sigma Cloud Service Provider

Sigma organizations can be hosted on AWS, Azure, and GCP. Your IdP configuration will differ based on what cloud provider yours is hosted on. Before you get started, please confirm your organization's cloud provider in your Administration Portal's Account page, under the Site heading. See Technical Specifications for more information.

Note: All GCP configurations must be custom. Do not use the Google app to configure.

company apps

Select and Configure your IdP

If your company uses Okta, you have an option to use a pre-configured application to set up SSO access to Sigma. Please visit your IdP to understand how to use this application. Instructions can be found by searching for "Sigma Computing" in your IdP’s marketplace.

If your company uses a different IdP, follow that IdP's instructions for setting up a SAML application and verify that the following fields are set. You can enter those fields manually, or import them using the Sigma metadata file:

https://{{prefix}}.sigmacomputing.com/api/v2/saml2/2/metadata.xml

The {{prefix}} must be replaced with the cloud prefix specific to your cloud, listed in the table below.

Field	Value
Cloud Prefix	GCP: `api` AWS: `aws-api` AWS-CA: `api.ca.aws` AWS-EU: `api.eu.aws` AWS-UK: `api.uk.aws` AWS-AU: `api.au.aws` Azure-US: `api.us.azure` Azure-EU: `api.eu.azure`
Audience URI	`https://{{prefix}}.sigmacomputing.com/api/v2/saml2/2/metadata.xml`
Assertion consumer service URL / Consumer URL / Login URL / Single sign on URL	`https://{{prefix}}.sigmacomputing.com/api/v2/saml2/assert`
NameID format	email ("urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress")
Attributes	“fullName” or “firstName”, “lastName” "userRole" The userRole attribute can be set to `lite`, `essential`, `pro`, or `admin` (default account types). It also supports `viewer` and `creator` (former default account types). If userRole isn't set in your IdP , `lite` is applied to new users by default. This can be helpful if a non-Sigma user in your organization signs up to view a shared dashboard. You can change this role in Sigma. See account types. This attribute is case-sensitive. When configuring default account types (Admin, Lite, Essential, Pro), the value indicated should be lower case (e.g. `essential`). Other account type configurations are also case-sensitive, and the value set in your IdP must match the value in Sigma exactly, or errors may occur when trying to provision users. If userRole isn't set in your IdP, existing users will keep their current account type. "userGroups" Team assignments for a SAML user are automatically synced upon logging into Sigma, provided the Sigma team name matches the name in your IdP. Changes to teams created in your IdP that do not match a Sigma team will be ignored. See Behavior of "userRole" and "userGroups" attributes.

RelayState / Start URL	`https://app.sigmacomputing.com/<YOUR-ORG>/finish-login`
Validator	GCP: `^https://api.sigmacomputing.com/api/v2/saml2/assert$` AWS: `^https://aws-api.sigmacomputing.com/api/v2/saml2/assert$`

[Step 2] Configure SAML in Sigma

Open your Admin Portal by selecting Administration in the user menu at the top right of your screen.
Select the Authentication page from the left hand panel.
Click the Edit button under Authentication Method and Options.
Select SAML from the Authentication Method dropdown menu.
Enter your Identity Provider login / Single Sign On URL, also referred to as a SAML 2.0 Endpoint (HTTP).
This information is found in your IdP portal.
Enter your the X.509 Certificate for your IdP. You can get this from your IdP.
In the Export Authentication field, click Edit to allow exports to approved domains.
Click Save.

Update your SAML certificate

Before your SAML certificate expires, you need to update it in the Administration portal to avoid losing access to your Sigma organization.

Open the Administration portal by selecting Administration in the user menu at the top right of your screen.
Select the Authentication page from the left hand panel.
Click Edit under Authentication Method and Options.
In the Identity Provider X.509 Certificate field, enter the new certificate from your IdP.
Click Save.

If your SAML certificate already expired and you are unable to log into your Sigma organization, contact Sigma Support. See Submit a support request.

Behavior of "userRole" and "userGroups" attributes

🚧
If you make account type or team membership assignments in your IdP, do not change these assignments in Sigma. Configurations set in your IdP take precedence over any configurations in Sigma. For example, if you change a user's role in Sigma, this role will not be written back to your IdP. The next time you log into Sigma, the user’s role will be reset to their IdP declared role.

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

Scenario	Behavior
No userRole is set in IdP, and no account type is set in Sigma.	The account type in Sigma defaults to `lite`.
No userGroups set in IdP, but team assignments are set in Sigma.	The team assignments in Sigma are preserved.
The userGroups in IdP and team assignments in Sigma do not match.	Team membership is recognized by name matching. Team assignments in your IdP that do not have a corresponding team in Sigma will be ignored. For example, a user is assigned to "Team A" and "Team B" in your IdP. However, only "Team A" has been created in in Sigma. The user will only be assigned membership to "Team A" in Sigma.

Updated 16 days ago

Related resources