auth improvements

modules/ROOT/pages/configure-oidc.adoc

@@ -198,13 +198,13 @@ 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.
 
+Client Secret::
+Enter the Client Secret associated with the Client ID for secure communication.
+
 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.
@@ -245,7 +245,7 @@ ThoughtSpot email associated with the email of the user in the IdP.
 Display name:: _Optional._
 The display name for the user.
 
-roles:: _Optional._
+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 link:https://docs.thoughtspot.com/cloud/latest/oidc-iamv2#_enable_oidc_authentication[Enable OIDC authentication, window=_blank].
@@ -308,3 +308,94 @@ If a group is deleted from the OpenID provider server, the corresponding group i
 * link:https://developer.okta.com/docs/concepts/oauth-openid/[Okta documentation]
 * link:https://openid.net/connect/faq/[OpenID Connect documentation]
 
+== #Troubleshoot OIDC authentication#
+
+=== Users see a blank screen or are stuck on redirect after IdP login
+
+The most common cause is a mismatch between the registered *Callback URI* and the URI sent in the authorization request. Verify the following:
+
+. The Callback URI registered in your IdP exactly matches the ThoughtSpot redirect URI:
++
+----
+https://<ThoughtSpot-Host>/callosum/v1/oidc/callback
+----
+. No trailing slash, uppercase difference, or HTTP vs HTTPS mismatch exists.
+. The callback URI is registered for the correct application (client) in your IdP — not a different app or environment.
+
+=== `invalid_client` error from the token endpoint
+
+This means ThoughtSpot is presenting credentials that the IdP does not recognize. Check:
+
+* The *Client ID* and *Client Secret* values configured in ThoughtSpot match what your IdP issued after registering ThoughtSpot as a relying party.
+* ThoughtSpot uses `client_secret_post` as its client authentication method — confirm your IdP application is configured to accept this method. ThoughtSpot does not support `client_secret_basic`.
+
+=== `invalid_scope` error during authorization
+
+ThoughtSpot requires `openid`, `profile`, and `email` scopes. If your IdP returns `invalid_scope`, one of these scopes is not enabled for the registered application. Enable all three scopes in your IdP application settings.
+
+=== Users are provisioned but cannot be found after JIT login
+
+JIT provisioning maps IdP attributes to ThoughtSpot user fields. If the mapped attribute names don't match what the IdP sends in the ID token claims, the user record may be created with missing or incorrect fields.
+
+* In your IdP, inspect the ID token claims returned for a test user (most IdPs offer a token preview or debug tool).
+* Confirm the `preferred_username` claim is present — this maps to the ThoughtSpot `username` field.
+* If the `preferred_username` claim is not sent by your IdP, ask ThoughtSpot Support to remap to an alternative claim (for example, `email` or `sub`).
+// TODO: verify claim remapping support with engineering
+
+=== OIDC works on first login but fails on re-login (session refresh errors)
+
+If ThoughtSpot uses the `iss` + `sub` combination to identify returning users, a change in the IdP's `sub` claim value between sessions causes re-login to fail. This can happen after IdP migration or user account recreation. Contact link:https://www.thoughtspot.com/support[ThoughtSpot Support, window=_blank] to resolve orphaned user mappings.
+
+== #FAQs#
+
+=== What is the difference between OIDC and SAML for ThoughtSpot authentication?
+
+Both SAML and OIDC provide SSO authentication. The key differences are:
+
+[cols="1,2,2"]
+|===
+| | SAML | OIDC
+
+| Protocol
+| XML-based assertion exchange
+| JSON/JWT token exchange (built on OAuth 2.0)
+
+| Primary use case
+| Enterprise SSO, legacy systems
+| Modern apps, mobile, REST API-friendly
+
+| ThoughtSpot IAMv1
+| Supported
+| Supported (requires ThoughtSpot Support)
+
+| ThoughtSpot IAMv2
+| Supported (Admin Console)
+| Supported (Admin Console)
+
+| JIT provisioning
+| Supported
+| Supported
+|===
+
+Choose OIDC if your IdP is a modern provider (Google, Azure AD, Okta) and you prefer JSON-based token flows. Choose SAML if your organization has an existing SAML infrastructure or requires assertion-level attribute mapping.
+
+=== Does ThoughtSpot support PKCE for OIDC?
+
+ThoughtSpot currently uses the Authorization Code flow with `client_secret_post`. PKCE (Proof Key for Code Exchange) is not supported at this time.
+
+
+=== Can I configure multiple OIDC IdPs on one ThoughtSpot instance?
+
+Yes. Multiple OIDC IdPs can be configured on IAMv2 clusters from the Admin Console (*Admin* > *Authentication* > *Identity Providers*). To configure multiple OIDC IdPs on IAMv1, contact link:https://www.thoughtspot.com/support[ThoughtSpot Support, window=_blank].
+
+=== What happens to existing user sessions when OIDC is enabled?
+
+Enabling OIDC does not immediately terminate existing sessions. Users with active sessions remain authenticated until their session expires. New logins use OIDC once it is enabled and set as the default authentication method.
+
+=== Can I use OIDC with ThoughtSpot embedded in an iFrame?
+
+Yes, using `AuthType.OIDCRedirect` in the Visual Embed SDK `init()` call. The flow redirects the full browser window (not just the iFrame) to the IdP, completes authentication, and returns to the embedding application. See xref:configure-oidc.adoc#embedConfig[Enable OIDC authentication in the Visual Embed SDK].
+
+=== Is refresh token support available?
+
+ThoughtSpot does not currently use refresh tokens in its OIDC implementation. When the user's session expires, a new authorization code flow is initiated.

modules/ROOT/pages/configure-saml.adoc

@@ -339,4 +339,68 @@ Do NOT include the protocol in the SAML redirect domain name string to avoid con
 +
 . Click *Save changes*.
 
+== #Troubleshoot SAML SSO#
 
+=== Users are redirected to the IdP login page but return to an error screen
+
+Check the following in the browser *Network* tab:
+
+. Inspect the SAML response posted to the ACS URL (`/callosum/v1/saml/SSO`). A `400 Bad Request` from ThoughtSpot usually means one of the following:
++
+[cols="1,2"]
+|===
+| Symptom | Fix
+
+| `InResponseTo` mismatch
+| The IdP is sending an IdP-initiated response when ThoughtSpot expects SP-initiated. Check whether your IdP is configured for SP-initiated SSO.
+
+| Assertion expired
+| The SAML assertion `NotOnOrAfter` value has passed. Synchronize server clocks between your IdP and ThoughtSpot. If your IdP doesn't support `SessionNotOnOrAfter`, ask ThoughtSpot Support to enable `maxAuthenticationAge`.
+
+| Audience mismatch
+| The `Audience` element in the SAML assertion does not match the Entity ID configured on ThoughtSpot. Confirm the Entity ID value in *Admin* > *SAML* and ensure it matches exactly in your IdP.
+
+| Signature validation failed
+| The IdP certificate used to sign the assertion has expired or been rotated. Update the IdP certificate in the ThoughtSpot SAML configuration.
+|===
+
+=== SSO works for some users but not others
+
+* Confirm that all affected users exist in ThoughtSpot with usernames that exactly match the `NameID` value sent by the IdP. SAML username matching is case-sensitive.
+* If using Orgs, confirm that the SAML assertion includes a valid `Orgs` attribute for each user. Users not mapped to any Org will be denied access.
+* Verify that the failing users are assigned to the correct application in the IdP.
+
+=== `AuthType.SAMLRedirect` causes infinite redirect loop
+
+This usually means the SAML redirect domain has not been added to the allowed list in ThoughtSpot. Go to *Develop* > *Customizations* > *Security settings* and add your embedding application domain to the SAML redirect allowlist. See xref:configure-saml.adoc#saml-redirect[Add SAML redirect domain to the allowed list].
+
+=== Automatic SAML redirect breaks non-embedded users
+
+When automatic SAML redirect is enabled, it applies to all users — including those accessing ThoughtSpot directly. To temporarily bypass it for testing or admin access, append `?disableSAMLAutoRedirect=true` to the ThoughtSpot URL.
+
+== #FAQs#
+
+=== Can I configure more than one SAML IdP?
+
+Yes. ThoughtSpot supports up to 5 SAML IdP configurations. However, when a user logs in from the ThoughtSpot login page, only the default IdP is used. Users on non-default IdPs must initiate login from those IdPs' own login pages. To configure multiple IdPs, contact ThoughtSpot support.
+
+=== Do I need to reconfigure my IdP if I rotate the ThoughtSpot SAML certificate?
+
+Yes. The SP metadata XML exported from ThoughtSpot contains the signing certificate. After rotating the certificate, re-export the SP metadata and update it in your IdP application. Until the IdP is updated, signature validation will fail for SP-initiated SSO requests.
+
+=== Can SAML and local authentication be active at the same time?
+
+Yes. By default, local authentication remains active after you configure SAML. You can disable local authentication from *Admin* > *Authentication* > *Local* (IAMv2) once SAML is working and verified. See xref:authentication-local.adoc[Managing local authentication].
+
+=== Does SAML support just-in-time user provisioning?
+
+Yes. ThoughtSpot can create user accounts automatically on first SAML login if the SAML assertion includes the required attributes (`username`, `email`). Contact link:https://www.thoughtspot.com/support[ThoughtSpot Support, window=_blank] to enable JIT provisioning on your instance.
+
+=== What SAML bindings does ThoughtSpot support?
+
+ThoughtSpot supports HTTP POST binding for both SP-initiated and IdP-initiated SAML flows. HTTP Redirect binding is not supported for responses.
+// TODO: verify binding support details with engineering
+
+=== Can I use SAML SSO in an embedded ThoughtSpot deployment?
+
+Yes, using `AuthType.SAMLRedirect` in the Visual Embed SDK `init()` call. The browser is redirected to the IdP outside of the iFrame and returned to the embedding application page after authentication. See xref:configure-saml.adoc#auth-config-sdk[Enable SSO authentication in Visual Embed SDK].

modules/ROOT/pages/trusted-auth-sdk.adoc

@@ -110,7 +110,7 @@ init({
     autoLogin: true
 });
 
-function async getAuthToken {
+async function getAuthToken() {
     const tokenURL = tokenServiceURL + "/gettoken/";
     console.log("calling token server at " + tokenURL);
 
@@ -131,13 +131,13 @@ function async getAuthToken {
             },
             credentials: 'include'
         })
-    )
+    );
 
     // Token request service returns plain-text string of the token
     // set the global tsToken variable for using the token for separate REST API requests
-    tsToken = response.text();
-    // Must return for the Promise to be completed
-    return response.text()
+    tsToken = await response.text();
+    // Must return a value for the Promise to resolve correctly
+    return tsToken;
 }
 ----
 

modules/ROOT/pages/trusted-auth-troubleshoot.adoc

@@ -38,4 +38,58 @@ With cookie-less trusted authentication, you will see that every request to the
 `authorization: Bearer YnJ5YW50Lmhvd2VsbDpKSE5vYVhKdk1TUlRTRUV0TWpVMkpEVXdNREF3TUNRNWRGcDZVREY2VUcxMmIyVXZUalEyT1ZaMWIxaEJQVDBrYTFSeVRIRmtZV1k0UjJWUldHTndPVVZIWTJsb1RVVTFVR1lyWWsxU1NtMTVVSEo1TTJkS2Ftc3laejA=`
 ----
 
+== #Token expiry errors#
 
+If users are repeatedly redirected to the login page or see `401 Unauthorized` errors shortly after signing in, the login token may be expiring before the SDK can complete the sign-in sequence.
+
+By default, login tokens are valid for a short window. Check the following:
+
+* Verify that the clock on your token request service server is synchronized with NTP. Token validation uses `exp` claims — a skewed server clock causes tokens to appear expired immediately.
+* Confirm that the token lifetime configured on your ThoughtSpot instance is long enough for your `getAuthToken` callback to return a token before it is used.
+* If using `AuthType.TrustedAuthTokenCookieless`, verify that your application refreshes the token before it expires. The SDK calls `getAuthToken` again on expiry, but only if the previous token was successfully used at least once.
+
+== #CORS and CSP errors#
+
+Authentication will fail silently if CORS or CSP headers are not correctly configured. In the browser console, look for errors of the following types:
+
+* `Access-Control-Allow-Origin` — The ThoughtSpot host is blocking requests from your embedding domain. Add your embedding domain to the CORS allowlist in *Develop* > *Customizations* > *Security settings*.
+* `Content-Security-Policy: frame-ancestors` — The ThoughtSpot host is blocking the iFrame. Add your embedding domain to the CSP allowlist in the same *Security settings* page.
+* `Refused to connect` or `net::ERR_BLOCKED_BY_RESPONSE` — Both CORS and CSP may need updating.
+
+After updating security settings, clear the browser cache and retry. CORS and CSP changes take effect immediately but cached preflight responses may persist for up to 10 minutes.
+
+== #MFA conflicts with trusted authentication#
+
+If multifactor authentication (MFA) is enabled on your ThoughtSpot instance, trusted authentication using `AuthType.TrustedAuthToken` (cookie-based) may fail with a `403` error after the token exchange step.
+
+This occurs because the `/session/login/token` endpoint requires only the login token — it does not support MFA challenge-response flows. Trusted authentication bypasses the ThoughtSpot login UI entirely, so MFA cannot be fulfilled.
+
+To resolve this:
+
+* Use `AuthType.TrustedAuthTokenCookieless` — cookieless authentication uses a bearer token directly on every request and does not go through the session login endpoint, so MFA does not apply.
+* If cookieless authentication is not feasible, contact link:https://www.thoughtspot.com/support[ThoughtSpot Support, window=_blank] to configure MFA exemptions for API-authenticated users.
+
+== #Secret key errors#
+
+[cols="1,2"]
+|===
+| Error | Likely cause and fix
+
+| `Invalid secret key`
+| The secret key has been rotated or regenerated since it was copied. Copy the current key from *Develop* > *Customizations* > *Security settings* and update your token request service.
+
+| `Trusted authentication is not enabled`
+| Trusted authentication has been disabled on the ThoughtSpot instance. Re-enable it from the same *Security settings* page.
+
+| Token request service returns `500`
+| The secret key value is present but corrupted (extra whitespace, newline character, or truncation). Log the raw key value in your token service to confirm it matches the key shown in the UI exactly.
+|===
+
+== #Cookieless authentication checklist#
+
+If `AuthType.TrustedAuthTokenCookieless` is not working, verify the following in sequence:
+
+. The `getAuthToken` callback returns a `Promise<string>` that resolves to a valid token string — not an object or a JSON-wrapped value.
+. The token is a full access token generated by `POST /api/rest/2.0/auth/token/full` using the `secret_key`. Tokens generated by `POST /api/rest/2.0/auth/session/login` are session tokens and cannot be used as bearer tokens.
+. Every outbound request from the embedded iFrame includes the `Authorization: Bearer <token>` header. Use the *Network* tab in browser developer tools and inspect the request headers for ThoughtSpot API calls.
+. The token has not expired. Tokens have a configurable validity window. Implement a token refresh strategy in your `getAuthToken` callback.

modules/ROOT/pages/trusted-authentication.adoc

@@ -63,3 +63,45 @@ The React demo shows how to implement trusted authentication as part of an appli
 * link:https://github.com/thoughtspot/thoughtspot_rest_api_v1_python[Python REST API library, window=_blank] +
 A library implementing the V1 and V2 REST APIs in Python
 
+== #FAQs#
+
+=== What is the difference between trusted authentication and SAML SSO?
+
+SAML SSO delegates authentication entirely to an external Identity Provider (IdP). The user is redirected to the IdP login page, authenticates there, and the IdP asserts their identity to ThoughtSpot via a SAML response.
+
+Trusted authentication does not redirect the user to an IdP. Instead, the embedding web application authenticates the user itself (by whatever mechanism it uses — LDAP, OAuth, internal DB, or SAML), then requests a short-lived login token from ThoughtSpot on behalf of that already-authenticated user. ThoughtSpot trusts the application's assertion of identity.
+
+Use trusted authentication when:
+
+* You want a fully seamless, no-redirect embed experience.
+* Your application already manages its own user sessions.
+* You need to impersonate users in back-end REST API calls.
+
+Use SAML when:
+
+* You want ThoughtSpot's own login page to participate in the IdP flow.
+* You are not embedding ThoughtSpot — users access it directly.
+
+=== Can I use trusted authentication without the Visual Embed SDK?
+
+Yes. The token request and session creation steps can be performed entirely via REST API calls without using the Visual Embed SDK. This is the standard pattern for back-end REST API impersonation use cases. See xref:trusted-authentication.adoc#rest-api[REST API back-end use cases].
+
+=== Does trusted authentication work with multi-tenancy (Orgs)?
+
+Yes. When generating a token for a user in a specific Org, include the `org_id` parameter in the `POST /api/rest/2.0/auth/token/full` or `POST /api/rest/2.0/auth/token/custom` request. Without `org_id`, the token is scoped to the default Org for that user.
+
+=== What happens if the secret key is rotated while users are active?
+
+Existing active sessions (cookie-based) are not affected — the session cookie remains valid until it expires. New token requests using the old secret key will fail immediately. Update the secret key in your token request service as soon as it is rotated. For cookieless authentication, active bearer tokens remain valid until their individual `exp` time; subsequent `getAuthToken` calls will fail until the new key is deployed.
+
+=== How do I provision a user just-in-time (JIT) during trusted authentication?
+
+Your token request service can call the ThoughtSpot REST API to create or update the user before returning the login token. See xref:just-in-time-provisioning.adoc[Just-in-time provisioning] for the full procedure and code examples.
+
+=== Can I use trusted authentication with MFA enabled?
+
+Cookie-based trusted authentication (`AuthType.TrustedAuthToken`) is not compatible with MFA because the token exchange bypasses the ThoughtSpot login UI where MFA challenges are presented. Use `AuthType.TrustedAuthTokenCookieless` instead, or contact ThoughtSpot Support to configure MFA exemptions for API-authenticated users.
+
+=== What is the token validity window and can it be changed?
+
+By default, login tokens are valid for a short window (typically 5 minutes). The validity period is configurable per ThoughtSpot instance. Contact link:https://www.thoughtspot.com/support[ThoughtSpot Support, window=_blank] to adjust the token validity window for your deployment.