Configure SAML
You can configure Security Assertion Markup Language (SAML) using ThoughtSpot’s command line interface, tscli, or through the Admin Console.
SAML SSO authentication
ThoughtSpot supports the Single Sign-On (SSO) authentication method with the Security Assertion Markup Language (SAML) authentication and authorization framework. With SAML SSO, users can authenticate to the SAML identity provider (IDP) at your federation to access the ThoughtSpot application, or the embedded ThoughtSpot content in an external web application. It also allows them to navigate seamlessly between different application interfaces with their existing credentials.
By default, local authentication is enabled. After you configure SAML authentication, you can configure the ThoughtSpot login page to default to SSO login by contacting ThoughtSpot Support. Note that if you change the default login experience to SSO, local users cannot authenticate.
Use this article to learn how to configure a SAML integration with an external IDP.
The SAML SSO authentication involves several entities and components.
SAML authentication with multiple IDPs
You may have multiple groups of users who need to sign in to ThoughtSpot but are managed by separate IDPs. You can configure SAML SSO login for more than one Identity Provider. You can only configure this using tscli.
ThoughtSpot supports configuration of a maximum of 5 IDPs. |
SAML entities
SAML is an XML standard that allows secure exchange of user authentication and authorization data between trusted partners. It enables the following entities to exchange identity, authentication, and authorization information:
-
Identity Provider (IDP)
The Identity Management system that maintains the user identity information. IDP acts as a SAML authority and authenticates SSO users. ThoughtSpot supports SAML authentication framework with popular Identity Providers such as Okta, Azure Active Directory, PingFederate, Microsoft AD FS, and Onelogin. This is not an exhaustive list. To determine if ThoughtSpot supports your preferred IDP, talk to your ThoughtSpot contact.
After you complete the SAML configuration in ThoughtSpot that this article describes, refer to your Identity Provider’s SAML documentation for specific information on setting up SAML with that IDP. -
Service Provider (SP)
The provider of a business function or application service; for example ThoughtSpot. The SP relies on the IDP to authenticate users before allowing access to its services. -
Federated user
A user whose identity information is managed by the IDP. The federated users have SSO credentials and authenticate to IDP to access various application services.
SAML assertion and attributes
Both SP-initiated and IDP-initiated authentication workflows rely upon assertions that are exchanged between the SAML endpoints through a web browser.
Some of the most commonly used elements are:
-
SAML assertion
The user authentication and authorization information issued by the IDP. SAML assertions contain all the information necessary for a service provider to confirm if the user identity is valid.ThoughtSpot supports 2 methods to increase the duration of validity for your SAML assertion: the
SessionNotOnOrAfter
attribute and themaxAuthenticationAge
parameter. You can ask ThoughtSpot to disable either one of these checks. If you use both, and either check fails, ThoughtSpot does not authenticate the user. Some IDPs do not support use ofSessionNotOnOrAfter
. If your IDP does not support use ofSessionNotOnOrAfter
, remove that attribute from your IDP assertion and ask ThoughtSpot Support to enablemaxAuthenticationAge
. -
Metadata
Data in the XML format to establish interoperability between the IDP and SP. It contains the URLs of the endpoints, entity ID, and so on. -
Assertion Services Consumer (ACS) URL
The endpoint URL to which the user’s browser sends the SAML response received from the IDP after authenticating a user. -
Entity ID
A unique service name to identify the client application from which the SSO login request originates. -
SAML attributes
The attributes associated with the user; for example, username and email address.
Enable SAML Authentication
You need admin privileges to enable SAML SSO authentication. You can set up SAML through the shell on ThoughtSpot using a tscli
-based configurator, or through the Admin Console.
Configuration prerequisites
Before you configure SAML, collect the following information:
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
|
❏ |
ThoughtSpot service address
A fully qualified and resolvable domain name for the ThoughtSpot service. For example, thoughtspot.thoughtspot-customer.com. If you do not have the DNS name, you can use the front-end IP address. However, using the DNS name instead of the IP address is a best practice.
Service port
Enter 443
in this box. This is the port of the server where your ThoughtSpot instance is running.
Unique service name
The unique key used by your Identity Provider(s) to identify the client. For example, urn:thoughtspot:callosum:saml, or https://ssoappname.sso-provider.com/ab12c3de4. This is also called the SP Entity ID.
Skew time in seconds
The allowed skew time, after which the authentication response is rejected and sent back from the IDP. 86400 is a popular choice. The default is 3600.
IDP label
[TSCLI only. For multiple IDP only, with --multi
flag] Unique key to identify this IDP when using multiple identity providers. Cannot start with a period (.
).
Do you want to make this IDP default?
[TSCLI only. For multiple IDP only, with --multi
flag] Specifies if this IDP should be the default. Type y
to make this IDP the default, and n
to make the next IDP you configure the default. When users signg in to ThoughtSpot from the ThoughtSpot URL, the login screen takes them to the default IDP to sign in. To use other, non-default IDPs that you configured with the --multi
flag, users must sign in to ThoughtSpot from the other IDP’s login page.
IDP Metadata XML File
The absolute path to your Identity Providers' metadata file. This file is provided by your IDP(s). You need this file so that the configuration persists over upgrades. It is a best practice to set it up on persistent/HA storage (NAS volumes) or in the same absolute path on all nodes in the cluster. For example, idp-meta.xml. If your IDP(s) needs an Assertion Consumer Service URL to create the metadata file, use https://<hostname_or_IP>:443/callosum/v1/saml/SSO
. Note that this URL is case-sensitive.
If your IDP(s) does not allow you to import the IDP metadata XML file, you must map values between ThoughtSpot and your IDP manually. This allows the ThoughtSpot system to automatically pick up certain attributes and subjects, such as a user’s email address, display name, and username. Map the username attribute value in your IDP(s) (userPrincipalName
in Okta, for example) to NameId
, map the email
attribute value to mail
, and optionally map the display name
subject value to displayName
. Attributes and subjects appear in separate sections of your SAML assertion. It is mandatory to fill out the mail field. If your company cannot meet this requirement, contact ThoughtSpot Support.
For additional support with the attribute and subject statements, refer to your IDP’s SAML documentation. ThoughtSpot supports SAML authentication framework with popular Identity Providers such as Okta, Azure Active Directory, PingFederate, Microsoft AD FS, and Onelogin. This is not an exhaustive list. To determine if ThoughtSpot supports your preferred IDP, talk to your ThoughtSpot contact.
Automatically add SAML users to ThoughtSpot: (yes/no)
Choose whether or not to add SAML users to ThoughtSpot when they first authenticate. If you choose 'yes', then new users will be automatically created in ThoughtSpot upon first successful SSO login. If you choose 'no', then SAML users will not be added in ThoughtSpot upon first successful SSO login. Instead, you must add users manually or through Active Directory.
Also use ThoughtSpot internal authentication: (y/n)
If 'y', then ThoughtSpot local/internal users (including local administrative users) will still be authenticated outside the scope of SSO.
samlMaxAuthenticationAge (tscli configuration only)
By default, ThoughtSpot sets your samlMaxAuthenticationAge
to 18114400 (seconds). If you experience an unauthorized error when logging in via SAML, your AuthnInstant
value may be set to a different, older value. To resolve this issue, find your AuthnInstant
value in the IDP login assertion. Set the samlMaxAuthenticationAge
to a value older than that value.
This is only one reason why you may receive an unauthorized error when logging in via SAML; if updating your samlMaxAuthenticationAge
value does not resolve this issue, contact ThoughtSpot Support.
You can only configure this setting when configuring SAML using tscli.
Configure SAML using tscli
The configuration persists across updates to newer releases of ThoughtSpot. |
To set up SAML on ThoughtSpot for user authentication, follow these steps:
-
Log in to the Linux shell using SSH.
-
Execute the command to launch the interactive SAML configuration.
tscli saml configure
If you want to configure multiple IDPs, add
--multi
to the end of the command. After you fill out the configuration prompts for one IDP, the configurator asksDo you want to add an IDP metadata?
Typey
to configure another IDP. Note that ThoughtSpot supports configuration of a maximum of 5 IDPs.tscli saml configure --multi
To change your default IDP, add
--change_default_idp
to the end of the command. When users sign in to ThoughtSpot from the ThoughtSpot URL, the login screen will take them to the default IDP. To use other, non-default IDPs that you configured with the--multi
flag, users must sign in to ThoughtSpot from the other IDP’s login page.tscli saml configure --change_default_idp
-
Complete the configurator prompts with the information and files you collected in Configuration prerequisites.
-
When the configuration is complete, download ThoughtSpot’s metadata file,
spring_saml_metadata.xml
. This file contains the public key you need if you want to encrypt your SAML assertions. To download this file, navigate tohttps://<hostname-or-IP>/callosum/v1/saml/metadata
. The file automatically downloads.
Configure the IDP
To enable the IDP to recognize your host application and ThoughtSpot as a valid service provider, you must configure the IDP with required attributes and metadata. This includes the spring_saml_metadata.xml
file that you downloaded in step 4 of Configure SAML using tscli.
ThoughtSpot supports SAML authentication with several identity and access management providers, such as Okta, Azure Active Directory, PingFederate, Microsoft AD FS, Onelogin and so on. If you want to use one of these providers as your IDP, make sure you read the SAML configuration steps described in the Identity provider’s documentation site.
To determine if ThoughtSpot supports your preferred IDP, contact ThoughtSpot Support.
Complete your configuration of the IDP using the IDP’s SAML documentation. Upload or copy the contents of the spring_saml_metadata.xml
to your IDP server. If you did not download the spring_saml_metadata.xml
file, navigate to https://<your_ThoughtSpot_hostname-or-IP>/callosum/v1/saml/metadata
. The file automatically downloads.
After you configure the IDP, open a web browser and go to the ThoughtSpot login page. It should now show the Single Sign On option.
Configure SAML using the Admin Console
You need admin privileges to enable SAML SSO authentication.
ThoughtSpot Training
For best results, we recommend that you take the following ThoughtSpot U course: Single Sign On (SSO).
See other training resources at ThoughtSpot U.
If you configure authentication through SAML, you cannot also configure authentication through Active Directory. |
-
Configure the ThoughtSpot application instance on your IDP server.
-
Sign in to your ThoughtSpot application instance.
-
From the top navigation bar, select the Admin tab.
-
Select SAML from the side navigation bar that appears.
-
Click the Configure button in the middle of the screen.
-
Fill in the parameters with the information you collected in the Configuration prerequisites.
-
When the configuration is complete, download ThoughtSpot’s metadata file,
spring_saml_metadata.xml
. This file contains the public key you need if you want to encrypt your SAML assertions. To download this file, navigate tohttps://<hostname-or-IP>/callosum/v1/saml/metadata
. The file automatically downloads.
ThoughtSpot adds external users, or users that authenticate through SAML or Active Directory, to the all group by default. This group has no privileges. You must manually assign users to ThoughtSpot groups to give them privileges, such as can upload user data, or can manage data. |
Configure the IDP
To enable the IDP to recognize your host application and ThoughtSpot as a valid service provider, you must configure the IDP with required attributes and metadata. This includes the spring_saml_metadata.xml
file that you downloaded in step 7 of Configure SAML using the Admin Console.
ThoughtSpot supports SAML authentication with several identity and access management providers, such as Okta, Azure Active Directory, PingFederate, Microsoft AD FS, Onelogin and so on. If you want to use one of these providers as your IDP, make sure you read the SAML configuration steps described in the Identity provider’s documentation site.
To determine if ThoughtSpot supports your preferred IDP, contact ThoughtSpot Support.
Complete your configuration of the IDP using the IDP’s SAML documentation. Upload or copy the contents of the spring_saml_metadata.xml
to your IDP server. If you did not download the spring_saml_metadata.xml
file, navigate to https://<your_ThoughtSpot_hostname-or-IP>/callosum/v1/saml/metadata
. The file automatically downloads.
Refer to Configure SAML 2.0 for details on correct field mapping.
After you configure the IDP, open a web browser and go to the ThoughtSpot login page. It should now show the Single Sign On option.
Configure SAML 2.0
When configuring SAML 2.0, ensure that you map the SAML user attributes and subjects to appropriate fields. This allows the ThoughtSpot system to automatically pick up certain attributes and subjects, such as a user’s email address, display name, and username.
For example,
- Onelogin
-
You must map the SAML user’s username to the NameId attribute.
- Okta
-
You must map the
username
touserPrincipalName
.
You must also map the email
address of the user to the mail
attribute.
Optionally, map the display name you would like to use to the displayName
subject.
Attributes and subjects appear in separate sections of your SAML assertion.
Starting in ThoughtSpot version 6.3.1, the mail field is mandatory, and cannot be empty. If your organization cannot meet this requirement, contact ThoughtSpot Support for help. |
If your IDP does not allow you to import the IDP metadata XML file, you must map these values manually.
SAML group mapping
You can map your SAML groups from your IDP to your ThoughtSpot groups. This means that you do not have to manually recreate your groups in ThoughtSpot, if they are already present in your IDP. Refer to Configure SAML group mapping.
Use SSO login by default
After you configure SAML authentication, a new option appears on the login page that allows users to log in using SSO, while still allowing local users to log in.
To only allow SSO login by default, contact ThoughtSpot Support. Note that if you change the default login experience to SSO, local users cannot authenticate.
Show content