# OpenID Connect authentication

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

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

# OpenID Connect authentication

OpenID Connect (OIDC) is an authentication protocol that adds an identity layer to the OAuth 2.0 protocol. OIDC allows clients to verify a user’s identity based on the authentication performed by an authorization server. Using the OIDC authentication framework, end users can access multiple applications, websites using their single sign-on credentials.

To get familiar with the common OIDC terminologies, see the following page [OIDC concepts and terms](https://docs.thoughtspot.com/cloud/latest/oidc-configure).

## OIDC authentication workflow

The following figure illustrates the OIDC authentication workflow for an embedded ThoughtSpot instance:

![OIDC authentication](/docs/doc-images/images/oidc-auth-flow.png)

The OIDC authentication workflow involves the following steps:

1.  A user logs into the host application and requests access to the embedded ThoughtSpot content.
    
2.  The SDK checks for an existing user session in the browser.
    
3.  If there is no session, it sends a `GET` request to the OpenID authorization endpoint configured on ThoughtSpot to obtain an authorization code.
    
4.  The OpenID authorization server returns an authorization code.
    
5.  The SDK sends the authorization code with the ThoughtSpot client credentials in a `POST` request to the OpenID token endpoint.
    
6.  The token endpoint returns an ID and access token in exchange for the authorization code.
    
7.  The SDK validates the ID token and authenticates the user.
    
8.  If the authentication is successful, the web browser redirects the user to the requested page.
    

## OIDC configuration steps

ThoughtSpot supports the `Authorization code flow` in which an authorization server at the OpenID provider’s end verifies the identity of a ThoughtSpot user and grants authorization code and tokens. This method of authentication and authorization requires ThoughtSpot to obtain authorization code, ID and access tokens, and validate these tokens before granting access to its resource.

The OIDC configuration procedure includes the following steps:

-   [Register your ThoughtSpot instance and the redirect URI in the OpenID provider]({{navprefix}}/{{configure-oidc}}#clientRegistration)
    
-   [Enable OIDC authentication support on ThoughtSpot with IAMv1]({{navprefix}}/{{configure-oidc}}#configureTS) (Requires assistance from ThoughtSpot Support)
    
-   [Enable OIDC authentication support on ThoughtSpot with IAMv2]({{navprefix}}/{{configure-oidc}}#IAMv2) (Requires assistance from ThoughtSpot Support)
    
-   [Enable OIDC authentication in the Visual Embed SDK]({{navprefix}}/{{configure-oidc}}#embedConfig) (For embedded ThoughtSpot instances only)
    

#### Register ThoughtSpot and set the redirect URI

To register the ThoughtSpot as a client in the OpenID provider server, see the following page [Register ThoughtSpot and set the redirect URI](https://docs.thoughtspot.com/cloud/latest/oidc-configure#clientRegistration).

After you register ThoughtSpot as a relying party and set the redirect URI, the OpenID provider provides the following information:

Client ID

The `client_id` string.

Client secret

The `client_secret` string.

Issuer

The OpenID provider URL from which ThoughtSpot can discover the OpenID provider metadata, such as the authorization, token, user information, and public-keys endpoints, and supported scope and claims.

Redirect URI

The registered redirect URI to which the authorization response will be sent.

### Enable OIDC authentication support on ThoughtSpot with IAMv1

> **NOTE:** You must contact ThoughtSpot Support to enable OIDC authentication support on ThoughtSpot.

To configure ThoughtSpot for OpenID Connect authentication, the following attributes and metadata are required.

Client ID and client secret

The OpenID provider generates a `client_id` and `client_secret` after you successfully register ThoughtSpot as a relying party. The `client_id` and `client_secret` are required parameters in the `GET` and `POST` requests sent by ThoughtSpot to the authorization and token endpoints.

Authorization, token, and user information endpoints

For the user authentication process, ThoughtSpot will require the URIs of the authorization, token, and user information endpoints. ThoughtSpot can retrieve this information dynamically from the issuer URL using the `/.well-known/openid-configuration` endpoint. You can obtain the issuer URL after registering ThoughtSpot as a client in the OpenID provider system.

https://<issuer-url>/.well-known/openid-configuration

-   Supported scopes
    
    You can obtain the scope that your OpenID provider supports from the OpenID provider metadata.
    
    The following scopes are mandatory for OIDC configuration on ThoughtSpot. ThoughtSpot sends the `scope` attributes in the `GET` request to the OpenID authorization endpoint.
    
    -   `openid`
        
        All OpenID Connect requests must contain the `openid` scope value.
        
    -   `profile`
        
        If the `profile` scope value is present, the ID token will include the user’s default profile claims.
        
    -   `email`
        
        If the `email` scope value is present, the ID token includes `email` and `email_verified` claims.
        
    
-   Supported claims
    
    Claims that your OpenID provider uses. During ID token validation, ThoughtSpot verifies the tokens for the following claims:
    
    -   `iss`
        
        The issuer ID of the OpenID provider.
        
    -   `aud`
        
        Audience or the intended recipient. This claim must contain the client ID issued for ThoughtSpot by the OpenID provider.
        
    -   `exp`
        
        The expiration time for validating the token.
        
    
    To update the user profile on the ThoughtSpot cluster, the ID token claims must include the following properties:
    
-   `preferred_username`
    
    Preferred username of the user. It maps to the `username` attribute in the user profile on ThoughtSpot. To include this claim in the ID token, the `scope` attribute must be set to `profile` in the authentication request sent to the authorization endpoint.
    
-   `displayName`
    
    The display name of the user. It maps to the `displayName` attribute in the user profile on ThoughtSpot. The default value is derived from the `name` claim.
    
-   `email`
    
    Email address of the user. It maps to the `mail` attribute in the user profile on ThoughtSpot. To include this claim in the ID token, the `scope` attribute must be set to `email` in the authentication request sent to the authorization endpoint.
    
-   `sub`
    

The unique ID issued for the user at the OpenID provider. Maps to `oktauserid` attribute on ThoughtSpot.

For detailed information on enabling OIDC authentication on your ThoughtSpot instance with IAMv1, see the page [Enable OIDC authentication](https://docs.thoughtspot.com/cloud/latest/oidc-configure#configure-ts).

### Enable OIDC authentication support on ThoughtSpot with IAMv2

> **NOTE:** You need admin privileges to enable OIDC authentication with IAMv2 on ThoughtSpot.

With OIDC, users can authenticate to the identity provider (IdP) to access the ThoughtSpot application, or the embedded ThoughtSpot content in an external web application. With [IAMv2](https://docs.thoughtspot.com/cloud/latest/okta-iam), ThoughtSpot powers its internal authentication with Okta. IAMv2 involves several external improvements to authentication, including security enhancements.

To enable OIDC authentication on ThoughtSpot using IAMv2, navigate to the **Authentication** section in the **Admin** panel, and click **Single Sign On**. Select the **OIDC IDP** and enter the following IdP details:

Connection name

Provide a name for the configuration of the connection to your identity provider, helping to distinguish and manage multiple connections. This appears as the connection name on the Admin Console.

Client Secret

Enter the Client Secret associated with the Client ID for secure communication.

Client Id

A public identifier for the client, is used by the authorization server to recognize and validate the client. Enter the Client ID provided by the OIDC IdP when you registered your application.

Scopes

The specific permissions or access levels granted by the user during the authentication process. This defines the extent of data and actions the client can perform. You can obtain the scope that your OpenID provider supports from the OpenID provider metadata.

The following scopes are mandatory for OIDC configuration on ThoughtSpot. ThoughtSpot sends the `scope` attributes in the `GET` request to the OpenID authorization endpoint.

-   `openid` All OpenID Connect requests must contain the openid scope value.
    
-   `profile` If the profile scope value is present, the ID token will include the user’s default profile claims.
    
-   `email` If the email scope value is present, the ID token includes email and email-verified claims.
    

Authorization Endpoint

URL where the OpenID provider initiates the authorization process by redirecting the user’s browser to this endpoint for authentication.

Token Endpoint

URL where the OpenID provider endpoint returns an ID and access token in exchange for an authorization code. ThoughtSpot sends the authorization code obtained from the authorization server to the token endpoint to obtain an ID and access token.

Issuer

Typically represented as a URL which represents the unique identifier for the OpenID Connect provider serving as a trusted endpoint for authentication.

User Info Endpoint

_Optional._ URL for retrieving additional user information after authentication, providing user details.

Jwks (JSON Web Key Set) Endpoint

URL for obtaining a JSON Web Key Set, used to verify the authenticity of tokens issued by the IdP.

Auto create user (JIT)

This toggle allows you to specify whether user accounts should be created automatically upon their first authentication if they don’t already exist. When enabled, it streamlines the user creation process.

The IdP details will have to be mapped with these ThoughtSpot attributes:

Username

ThoughtSpot username corresponding to the username from the IdP.

Email

ThoughtSpot email associated with the email of the user in the IdP.

Display name

_Optional._ The display name for the user.

roles

_Optional._ Roles associated with the user. This mapping is crucial for assigning the correct roles and permissions to users based on their authentication through OIDC.

For detailed information on enabling OIDC authentication on your ThoughtSpot instance using IAMv2, and attributes, see [Enable OIDC authentication](https://docs.thoughtspot.com/cloud/latest/oidc-iamv2#_enable_oidc_authentication).

### Enable OIDC authentication in the Visual Embed SDK

To enable OIDC authentication support on an embedded ThoughtSpot instance, make sure you set the `AuthType` parameter to `OIDCRedirect` in the SDK when calling the `init` function from your application.

```JavaScript
init({
    thoughtSpotHost: "https://<hostname>:<port>",
    authType: AuthType.OIDCRedirect,
});
```

## Org mapping with OIDC assertion

> **NOTE:** To enable Orgs mapping for OIDC authentication on ThoughtSpot, contact ThoughtSpot Support. In 9.12.0.cl, Org mapping with OIDC authentication is supported only with IAMv1.

With Org mapping, the IdP will have the ability to authenticate and log in OIDC users in ThoughtSpot. IdP will have to send a list of the Org names and the user will be assigned to these Orgs. By default, the Org mapping is disabled on the ThoughtSpot instance. To enable it in the **Admin** panel of the ThoughSpot instance, follow these steps:

1.  Ensure Orgs are enabled for your ThoughtSpot cluster.
    
2.  [Create an OIDC connection](https://docs.thoughtspot.com/cloud/latest/oidc-configure#configure-ts).
    
3.  Enable JIT user creation to automatically create user accounts if they don’t exist in ThoughtSpot during authentication.
    
4.  Configure the OIDC assertion on IdP side. This assertion will be sent as a part of the ID Token.The following screenshot shows a sample configuration on Okta.
    
    ![Org mapping on OIDC IAMv1](/docs/doc-images/images/oidc_iamv1.png)
    
5.  Ensure the mapping attributes are configured on your ThoughtSpot instance.
    

## Group synchronization

The group synchronization feature reads the Group claim from the ID token provided by the OpenID provider and creates groups in ThoughtSpot. To enable group synchronization on ThoughtSpot, contact ThoughtSpot Support.

> **NOTE:** If a group is deleted from the OpenID provider server, the corresponding group in ThoughtSpot will not be deleted during group synchronization. You must manually delete it in ThoughtSpot.

## Additional resources

-   [Okta documentation](https://developer.okta.com/docs/concepts/oauth-openid/)
    
-   [OpenID Connect documentation](https://openid.net/connect/faq/)