Security settings

Table of Contents

Overview
- Third-party cookies
Configure security settings
Retrieve security settings

ThoughtSpot allows administrators and developers to configure allowlists for Content Security Policy (CSP) and Cross-origin Resource Sharing (CORS), authentication attributes, and access control settings. These settings can be done via the Security Settings page in the ThoughtSpot UI, or through REST APIs v2, by sending a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint.

Overview🔗

Most web browsers block cross-site scripting, cross-domain requests, and third-party cookies by default. Web browsers also have built-in security mechanisms such as same-origin and content security policies. These policies restrict how applications and scripts from one origin (domain) can interact with the resources hosted on another origin (domain). To ensure data security and a seamless user experience in embedding applications, configure the settings described in this section.

When ThoughtSpot is embedded in another application, it is considered a third-party application in the host application context. As a result, cookies from ThoughtSpot are blocked by Web browsers.

Third-party cookies🔗

To avoid this issue, ThoughtSpot recommends the following:

Developers can use either AuthType.EmbeddedSSO or AuthType.TrustedAuthTokenCookieless based on their embedding setup.
If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see Custom domain configuration.
If you are using authentication methods that rely on cookies, enable partition cookies.

Configure security settings🔗

Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Note that the following settings on the Security Settings page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license:

Security settings for Orgs🔗

On ThoughtSpot instances with Orgs, security settings can be managed at two levels:

Global settings for all Orgs (cluster level)
Cluster administrators can configure security settings globally for all Orgs. On ThoughtSpot instances with Orgs, the Develop page opens in the Primary Org context, unless you are accessing the Develop tab from a specific Org context. To configure settings for all Orgs, you must switch to All Orgs context.
Org-level settings
Cluster and Org administrators can configure security settings for the current logged-in Org. Configuration modifications at the Org level do not affect other Orgs or the default settings applied at the All Orgs level.

The following table shows the settings available at the All Orgs and per-Org levels:

		All Orgs level (cluster level)	Per-Org level
CSP allowlists	CSP visual embed hosts	Yes	No
CSP connect-src domains	Yes	No
CSP font-src domains	Yes	No
CSP img-src domains	Yes	No
CSP style-src domains	Yes	No
Permitted iFrame domains	Yes	No
CORS allowlist	CORS whitelisted domains	Yes	Yes
Embed access	Block non-embed full app access	Yes	Yes
Partitioned cookies	Enable partitioned cookies	Yes	No
SAML SSO	SAML redirect domains	Yes	No
Token-based authentication	Trusted authentication	Yes Can be used to authenticate users in any Org on the ThoughSpot instance.	Yes Each Org can have a separate secret key, which can be used to authenticate users in that Org.

All Orgs level (cluster level)

Per-Org level

CSP allowlists

CSP visual embed hosts

Yes

CSP connect-src domains

Yes

CSP font-src domains

Yes

CSP img-src domains

Yes

CSP style-src domains

Yes

Permitted iFrame domains

Yes

CORS allowlist

CORS whitelisted domains

Yes

Embed access

Block non-embed full app access

Yes

Partitioned cookies

Enable partitioned cookies

Yes

SAML SSO

SAML redirect domains

Yes

Token-based authentication

Trusted authentication

Yes
Can be used to authenticate users in any Org on the ThoughSpot instance.

Yes
Each Org can have a separate secret key, which can be used to authenticate users in that Org.

Note

When security settings are defined at both levels, the Org-level settings take precedence over cluster-level settings within that Org.
If the configuration settings are available at both levels and are configured only at the All Orgs level, the Orgs on the instance will inherit these settings.
If the settings are not defined either at the All Orgs level or per Org, the system defaults will be applied.

CSP allowlists🔗

To allow another application to embed ThoughtSpot, you must add your host application domain as a CSP Visual Embed host.

To allow loading script interfaces and JavaScript events for custom actions, or to enable importing resources from other sites, add the source domain URLs as trusted hosts in the respective CSP allowlist.

Note	If your instance has Orgs configured, note that the default Org on your instance is Primary Org. ThoughtSpot allows CSP settings only at the cluster level, so you must switch to the All Orgs context to configure CSP allowlists.

Add CSP visual embed hosts🔗

To allow your host domain to set the frame-ancestors CSP policy header and embed a ThoughtSpot object within your application frame, add your application domain as a CSP visual embed host.

On your ThoughtSpot application instance, go to Develop page.
If your instance has Orgs, click the All Orgs tab.
Go to Customizations > Security settings.
Click Edit.
In the CSP visual embed hosts text box, add the domain names. For valid domain name formats, See Domain name format for CSP and CORS configuration.
Click Save changes.

Note	Only users with a valid embed license can add Visual Embed hosts.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter visual_embed_hosts.

curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
     -H 'Authorization: Bearer {access-token}' \
     -H 'Content-Type: application/json' \
     --data-raw '{
       "cluster_preferences": {
         "csp_settings": {
           "visual_embed_hosts": [
             "www.thoughtspot.com",
             "mysite.com:8080",
             "http://localhost:8080"
           ]
         }
       }
     }'

Add URLs to CSP connect-src allowlist🔗

If you plan to use a custom action or webhook to send data to an external endpoint or application, you must add the domains of the target endpoints or applications to the CSP connect-src allowlist.

On your ThoughtSpot application instance, go to Develop page.
If your instance has Orgs, click the All Orgs tab.
Go to Customizations > Security settings.
Click Edit.
In the CSP connect-src domains text box, add the domain names. For valid domain name formats, See Domain name format for CSP and CORS configuration.
Click Save changes.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Add domains of the target endpoints or applications to the connect_src_urls parameter for your ThoughtSpot application instance.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"cluster_preferences": {
    "csp_settings": {
        "connect_src_urls": [
            "localhost:3000",
            "thoughtspot.com"
        ]
    }
}
}'

Add other trusted domains🔗

To import images, fonts, and stylesheets from external sites, or load the content from an external site using an iFrame element, you must add the source URLs as trusted domains in the CSP allowlist. For example, in the Liveboard Note tiles, if you want to insert an image from an external site or embed content from an external site in an iFrame, you must add domain URLs of these sites to the CSP allowList. Similarly, to import fonts and custom styles from an external source, you must add the source URL as a trusted domain in ThoughtSpot.

On your ThoughtSpot application instance, go to Develop page.
If your instance has Orgs, click the All Orgs tab.
Go to Customizations > Security settings and configure the settings:
- CSP img-src domains
  Add the domains from which you want to load images and favicons.
- CSP font-src domains
  Add the domains from which you want to load fonts.
- CSP style-src domains
  Add the domains from which you want to load stylesheets.
- CSP script-src domains Add the domains from which you want host scripts. For more information, see Integrate third-party tools and allow custom scripts.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Add source URLs of sites, where from you can import images, fonts, and stylesheets, as trusted domains to the img_src_urls, font_src_urls, style_src_urls, script_src_urls parameters.

Note	To be able to add allowed urls for custom JavaScript through `script_src_urls`, `enabled` should be set to `true` for script-src customization.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"cluster_preferences": {
    "csp_settings": {
        "font_src_urls": [
            "*.thoughtspot.com"
        ],
        "img_src_urls": [
            "thoughtspot.com/products"
        ],
        "script_src_urls": {
        "enabled": true,
        "urls": [
            "thoughtspot:*"
        ]
    },
        "style_src_urls": [
            "*"
        ]
    }
}
}'

Add permitted iFrame domains🔗

Features such as Liveboard Note tiles and custom charts allow iFrame content. If you are planning to embed content from an external site, make sure the domain URLs of these sites are added to the iFrame domain allowlist:

On your ThoughtSpot application instance, go to Develop page.
If your instance has Orgs, click the All Orgs tab.
Go to Customizations > Security settings.
Click Edit.
In the Permitted iFrame domains text box, add the domain URL of the website or portal that you want to use for iFrame content.
Click Save changes.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Add domain URLs of external sites using iFrame content are added to the iframe_src_urls parameter for your ThoughtSpot application instance.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"cluster_preferences": {
    "csp_settings": {
        "iframe_src_urls": [
            "www.thoughtspot.com"
        ]
    }
}
}'

Enable CORS🔗

To allow your embedding application to call ThoughtSpot, access its resources, and render embedded content, add your host application domain URL as a trusted host for CORS.

The CORS configuration on your instance controls which domains can access and modify your application content. To allow your application to call ThoughtSpot or its REST API endpoints, and request resources, you must add your application domain to the CORS allowlist. For example, if your website is hosted on the example.com domain and the embedded ThoughtSpot content is hosted on the example.thoughtspot.com, you must add the example.com domain to the CORS allowlist for cross-domain communication. You can also add http://localhost:8080 to the CORS allowlist to test your deployments locally. However, we recommend that you disable localhost access in production environments.

If you enable CORS for your application domain, ThoughtSpot adds the Access-Control-Allow-Origin header in its API responses when your host application sends a request to ThoughtSpot.

To add domain names to the CORS allowlist, follow these steps:

On your ThoughtSpot instance, navigate to the Develop page.
If your instance has Orgs, you can configure CORS allowlists for all Orgs globally at the cluster-level or per Org.
- For cluster-wide configuration, click the All Orgs tab.
- To configure settings at the Primary Org level, click the Primary Org tab.
- To configure CORS settings at the Org-level, switch the Org context via Org switcher in the top navigation bar.
On Develop page, go to Customizations > Security settings.
Click Edit.
In the CORS whitelisted domains text box, add the domain names. For valid domain name formats, See Domain name format for CSP and CORS configuration.
Click Save changes.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Add CORS allowlist for cross-domain communication to the parameter cors_whitelisted_urls for the cluster or for the Org.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
  "org_preferences": [
    {
      "cors_whitelisted_urls": [
        "localhost"
      ]
    }
  ],
  "cluster_preferences": {
    "cors_whitelisted_urls": [
      "mysite.com"
    ]
  }
}'

Domain name format for CSP and CORS configuration🔗

Important

You can add multiple domains to the CORS and CSP Visual Embed allowlists on the Develop Customizations > Security Settings page. Ensure that the CORS and CSP allowlists do not exceed 4096 characters.
Protocol in the domain URL:
- CSP hosts — The UI allows adding a domain URL with or without the protocol (http/https). However, to avoid long URLs in the CSP header, you can exclude the protocol in the domain URL strings.
- CORS hosts — The UI allows adding a domain URL with the protocol (http/https). If the domain URLs are using https, you can exclude the protocol in domain URL strings, because ThoughtSpot assigns https to the URLs by default.
- For localhost and non-HTTPS URLs — For non-HTTPs domains or localhost such as localhost:3000, if you add the domain without the protocol, the https protocol will be assigned to the URL by default. Due to this, the localhost domain with http (http://localhost:3000) might result in a CSP or CORS error. Therefore, include the http protocol in the domain name strings for non-HTTPS domains and localhost.
Port: If your domain URL has a non-standard port such as 8080, specify the port number in the domain name string.

The following table shows the valid domain name strings for the CORS and CSP allowlists.

Domain name format CSP Visual Embed host CSP connect-src CORS CSP font-src
CSP style-src
CSP img-src

Domain name format	CSP Visual Embed host	CSP connect-src	CORS	CSP font-src CSP style-src CSP img-src
Domain URL strings without protocol `thoughtspot.com` `www.thoughtspot.com`	✓ Supported	✓ Supported	✓ Supported	✓ Supported
Domain URL strings for localhost `localhost` `localhost:3000` `http://localhost:8080` `http://localhost:3000`	✓ Supported	✓ Supported	✓ Supported	✓ Supported
Domain URL strings without port `thoughtspot.com` `mysite.com` If your domain URL has a non-standard port, for example `mysite.com:8080`, make sure you add the port number in the domain name string.	✓ Supported	✓ Supported	✓ Supported	✓ Supported
Wildcard (``) , (`.`) for domain URL	✓ Supported	✓ Supported	✓ Partial support Supports only (`.`)*	✓ Supported
Wildcard () before the domain name extension `https://.com`	x Not supported	x Not supported	x Not supported	x Not supported
Plain text string without the domain name extension. `thoughtspot`	x Not supported	x Not supported	x Not supported#	x Not supported
Domain name with wildcard () and a leading dot `..thoughtspot.com`	x Not supported	x Not supported	✓ Supported To avoid domain validation errors, make sure you add an escape character `\` after the wildcard in the domain URL string: `.*\.thoughtspot.com`	x Not supported
Wildcard before the domain name `*.thoughtspot.com`	✓ Supported	✓ Supported	x Not supported	✓ Supported
Domain names with space, backslash (\), and wildcard (). `www...thoughtspot.com` `www.thoughtspot.com/` `thoughtspot .com`	x Not supported	x Not supported	x Not supported	x Not supported
URLs with query parameters `http://thoughtspot.com?2rjl6`	x Not supported	x Not supported	x Not supported	x Not supported
URLs with path parameters `thoughtspot.com/products`	✓ Supported	✓ Supported	x Not supported	✓ Supported
URLs with path and query parameters `thoughtspot.com/products?id=1&page=2`	x Not supported	x Not supported	x Not supported	x Not supported
IPv4 addresses `255.255.255.255`	✓ Supported	✓ Supported	✓ Supported	✓ Supported
Semicolons as separators `thoughtspot.com; thoughtspot.com;`	x Not supported	x Not supported	x Not supported	x Not supported
Comma-separated values `thoughtspot.com, thoughtspot.com`	✓ Supported	✓ Supported	✓ Supported	✓ Supported
`mail://xyz.com`	x Not supported	x Not supported	x Not supported	x Not supported
Wildcard () for port `thoughtspot:`	✓ Supported	✓ Supported	✓ Supported	✓ Supported

Domain URL strings without protocol

thoughtspot.com
www.thoughtspot.com

✓ Supported

Domain URL strings for localhost

localhost
localhost:3000
http://localhost:8080
http://localhost:3000

✓ Supported

Domain URL strings without port

thoughtspot.com
mysite.com

If your domain URL has a non-standard port, for example mysite.com:8080, make sure you add the port number in the domain name string.

✓ Supported

Wildcard (*) , (.*) for domain URL

✓ Supported

✓ Partial support

Supports only (.*)

✓ Supported

Wildcard (*) before the domain name extension
https://*.com

x Not supported

Plain text string without the domain name extension.

thoughtspot

x Not supported

x Not supported#

x Not supported

Domain name with wildcard (*) and a leading dot

.*.thoughtspot.com

x Not supported

✓ Supported

To avoid domain validation errors, make sure you add an escape character \ after the wildcard in the domain URL string:
.*\.thoughtspot.com

x Not supported

Wildcard before the domain name

*.thoughtspot.com

✓ Supported

x Not supported

✓ Supported

Domain names with space, backslash (\), and wildcard (*).

www.*.*.thoughtspot.com
www.thoughtspot.com/*
thoughtspot .com

x Not supported

URLs with query parameters
http://thoughtspot.com?2rjl6

x Not supported

URLs with path parameters
thoughtspot.com/products

✓ Supported

x Not supported

✓ Supported

URLs with path and query parameters
thoughtspot.com/products?id=1&page=2

x Not supported

IPv4 addresses
255.255.255.255

✓ Supported

Semicolons as separators
thoughtspot.com; thoughtspot.com;

x Not supported

Comma-separated values
thoughtspot.com, thoughtspot.com

✓ Supported

mail://xyz.com

x Not supported

Wildcard (*) for port

thoughtspot:*

✓ Supported

Block access to non-embedded ThoughtSpot pages🔗

If you have embedded ThoughtSpot content in your app, you may want your users to access only the ThoughtSpot pages embedded within the context of your host app. ThoughtSpot allows administrators to restrict user access to non-embedded application pages from the embedding application context or selectively grant access to specific user groups. For information, see Control User Access.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Set block_full_app_access to true to restrict user access to non-embedded application pages from the embedding application context. Enter values for groups_identifiers_with_access to selectively grant access to specific user groups.

Note	To be able to gives access through `groups_identifiers_with_access`, the selective user access feature must be turned on in the Admin settings.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"cluster_preferences": {
    "non_embed_access": {
        "block_full_app_access": false
    }
},
"org_preferences": [
    {
    "non_embed_access": {
        "block_full_app_access": true,
            "groups_identifiers_with_access": [
            "group1"
        ]
    }
    }
    ]
}'

Enable partitioned cookies🔗

Many web browsers do not allow third-party cookies. If you are using authentication methods that rely on cookies, users will not be able to access the embedded content when browsers block third-party cookies. Therefore, ThoughtSpot recommends using cookieless authentication in production environments.

However, if your implementation uses cookie-based authentication or AuthType.None, ensure that you enable partitioned cookies:

On your ThoughtSpot application instance, go to Develop page.
If your instance has Orgs, click the All Orgs tab.
Go to Customizations > Security settings.
Click Edit.
Turn on the Enable partitioned cookies toggle switch.
Click Save changes.

With partitioned cookies enabled, when a user logs in to ThoughtSpot and accesses embedded content on a host application, a cookie is set with the partitioned attribute. On browsers supporting partitioned cookies, the partitioned cookie will persist in the app after a successful login.

Important

Safari blocks all third-party cookies and does not support partitioned cookies. You can switch to a different browser that supports partitioned cookies, or use cookieless authentication in your embedding implementation.

Through the REST API v2

Send a POST request to POST /api/rest/2.0/system/security-settings/configure API endpoint. Set enable_partitioned_cookies to true to ensure a cookie is set with the partitioned attribute for applications using cookie-based authentication .

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"cluster_preferences": {
    "enable_partitioned_cookies": true
}
}'

Trusted authentication🔗

See Trusted authentication and Secret key management.

Note	Trusted authentication is not supported through the REST APIs v2.

Retrieve security settings🔗

You can retrieve the security settings for your ThoughtSpot instance by sending a POST request to POST /api/rest/2.0/system/security-settings/search API endpoint. You can define the scope to get the cluster-level settings (scope as CLUSTER), or the Org-level settings for the current Org (scope as ORG). If the scope is not specified, the API returns both cluster and Org settings based on user privileges.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/search' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
  "scope": "CLUSTER"
}'