# Trusted authentication

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/trusted-auth

# Trusted authentication

Trusted authentication allows a web application to authenticate a user to a ThoughtSpot instance using **login tokens** requested from a ThoughtSpot instance.

It is the most seamless method of single sign-on (SSO) available to embed ThoughtSpot, but the actual **authentication** of the user is performed only by the **web application**, which then securely passes the user details to a **token request service** that must be developed and added to the web application.

Trusted authentication can also be used for back-end REST API processes that need to **impersonate** an individual user to retrieve a filtered data response. In those scenarios, you implement the token retrieval and sign-in calls directly without the browser portion.

![Trusted Authentication Workflow](/docs/doc-images/images/trusted-auth-new-1.png)

## Overview of implementation

The trusted authentication implementation method includes the following steps:

1.  [Enable Trusted authentication on ThoughtSpot]({{navprefix}}/{{trusted-auth-secret-key}}) in the **Develop** > **Customizations** > **Security Settings** page. Copy the `secret_key` and place where the **token request service** can [securely access it]({{navprefix}}/{{trusted-auth-secret-key}}).
    
2.  Create the **[token request service]({{navprefix}}/{{trusted-auth-token-request-service}})**, typically a REST API endpoint in the embedding application. This service returns a login token for the user signed in by the web application. The token request service may also [run other ThoughtSpot REST APIs for just-in-time provisioning]({{navprefix}}/{{just-in-time-provisioning}}).
    
3.  Include the [Visual Embed SDK]({{navprefix}}/{{trusted-auth-sdk}}) into the embedding web application. The authentication type is defined in the `init` function. You can configure cookie-based (`AuthType.TrustedAuthToken`) or cookieless authentication (`AuthType.TrustedAuthTokenCookieless`) as per your deployment needs.
    
4.  When `init()` is called, the SDK checks if there is an existing ThoughtSpot session for the instance in the browser. If not, it will request a **login token** from either the `authEndpoint` URL specified in the SDK or the `getAuthToken` callback function. For `authEndPoint`, specify the authentication endpoint URL from which you want to obtain the authentication token. If using `getAuthToken`, call the `getAuthToken` function to invoke your login endpoint. The login endpoint then returns a `Promise` string that resolves to an authentication token.
    

## Cookie-based vs cookieless authentication

The trusted authentication method supports cookie-based and cookieless authentication.

In cookie-based authentication, the login token is only necessary during the login process, after which any request to ThoughtSpot will include session cookies that identify the signed-in user.

In cookieless authentication, the bearer token issued by the authentication server is used to authenticate API requests to ThoughtSpot.

If you are embedding ThoughtSpot content in an app that is not in the same domain as your ThoughtSpot instance, and your web browser blocks third-party cookies, use cookieless authentication.

See the [Visual Embed SDK documentation]({{navprefix}}/{{trusted-auth-sdk}}) for the exact details of implementing either form of trusted authentication.

## How to turn off trusted authentication

[Disabling trusted authentication]({{navprefix}}/{{trusted-auth-secret-key}}#_disable_trusted_authentication) also invalidates the previous `secret_key`.

## Troubleshoot trusted authentication

Please see the [troubleshooting steps]({{navprefix}}/{{trusted-auth-troubleshoot}}) if you encounter issues with the browser-side aspects of the trusted authentication implementation.

## Trusted authentication code samples

Code examples for implementations of a `token request service` [are available here]({{navprefix}}/{{trusted-auth-token-request-service}}#code-examples).

Examples of front-end JavaScript for trusted authentication using the Visual Embed SDK are [documented here]({{navprefix}}/{{trusted-auth-sdk}}#code-examples).

The sample code of an application frontend authenticating via trusted authentication is available on the [GitHub repository](https://github.com/thoughtspot/big-react-demo) and [the React components code sandbox](https://github.com/thoughtspot/big-react-demo).

## REST API back-end use cases

With access to the `[secret_key]({{navprefix}}/{{trusted-auth-secret-key}})`, back-end REST API processes can request a token for any user, and then use the returned token as:

-   a login token using `session/login` to create a long-lived session as that user
    
-   a [bearer token]({{navprefix}}/{{rest-api-v2-getstarted}}#_log_in_to_thoughtspot) for all subsequent REST API calls
    

This is useful for [data]({{navprefix}}/{{rest-api-v2-reference}}#_data) and [reports]({{navprefix}}/{{rest-api-v2-reference}}#_reports) endpoints that have row-level security or other filtering applied based on the user account itself.

## Additional resources

-   [Big React Demo](https://codesandbox.io/s/big-tse-react-demo-i4g9xi)  
    The React demo shows how to implement trusted authentication as part of an application integrated with various ThoughtSpot components
    
-   [Python REST API library](https://github.com/thoughtspot/thoughtspot_rest_api_v1_python)  
    A library implementing the V1 and V2 REST APIs in Python