Merge pull request #273 from thoughtspot/10.6.0.cl

Merge 10.6.0.cl docs to main

Author: ShashiSubramanya

modules/ROOT/pages/abac-user-parameters.adoc

@@ -8,22 +8,47 @@
 
 In Attribute-Based Access Control (ABAC) implementation, security entitlements are sent in as lists of attributes at session creation time via the authentication service.
 
-// Unlike xref:abac-user-parameters-beta.adoc[the beta version of ABAC implementation], 
-
-The ABAC via tokens feature in ThoughtSpot 10.4.0.cl and later versions involves generating a token with filter rules and parameter values using the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">auth/token/custom</a>+++ API endpoint. 
-
-// This article describes the steps required to implement ABAC for row-level security (RLS) using the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">Custom access token </a>+++ REST API endpoint. 
+This article provides a detailed overview of the ABAC implementation via tokens for row-level security (RLS), and lists configuration recommendations, and best practices.
 
 [IMPORTANT]
 ====
+To enable the ABAC via tokens feature on your instance, contact ThoughtSpot Support.
+====
+
+
 // * The `user_parameters` property in `auth/token/full` and `auth/token/object` APIs used for the beta implementation of ABAC is deprecated in 10.4.0.cl. 
 // * Starting with 10.4.0.cl, security attributes for ABAC will not be stored in the `user` > `user_parameters` object. All ABAC-related security rules and filters applied via token generated using the `/api/rest/2.0/auth/token/custom` API endpoint are stored in the `user` > `access_control_properties` object.
-* To update your implementation from the xref:abac-user-parameters-beta.adoc[beta version of ABAC with the V2.0 Get token APIs] (`auth/token/full` or `auth/token/object`) to `/api/rest/2.0/auth/token/custom`, refer to the instructions in the xref:jwt-migration.adoc[migration guide].
+// * The  +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">Custom access token </a>+++ REST API endpoint.
+
+
+== Configuration recommendations and best practices
+
+Before you begin, note the following recommendations and feature limitations:
+
+* *API for token generation*  +
+The ABAC via tokens feature in ThoughtSpot 10.4.0.cl and later versions involves generating a token with filter rules and parameter values using the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">auth/token/custom</a>+++ API endpoint. To update your implementation from the xref:abac-user-parameters-beta.adoc[beta version of ABAC with the V2.0 Get token APIs] (`auth/token/full` or `auth/token/object`) to `/api/rest/2.0/auth/token/custom`, refer to the instructions in the xref:jwt-migration.adoc[migration guide].
+
+* *Mandatory token filters* +
+The most common *best practice* is to define *filter rules* within the token and place the `is_mandatory_token_filter: true` property on every column in a Worksheet or Model where a filter rule is expected. __This will deny any access to data if a user has not been assigned values for the expected set of fields__.
++
+[NOTE]
+====
+On instances running 10.5.0.cl and 10.4.0.cl versions, if a column is set as hidden (`is_hidden: true`), the `is_mandatory_token_filter: true` setting will not be applied to the column. Due to this, the user may see no data. To work around this issue, we recommend upgrading to 10.6.0.cl or set `is_hidden` to `false` on the column and then apply filter rules.
 ====
 
-== ABAC attributes
+[#column-name-warning]
+* *Column names in Worksheet/ Model* +
+The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name the values will not bind to any column. You must coordinate between the team that maintains the Worksheets or Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model or Worksheet. +
+For the same reasons, the end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens. +
+When column names change, ensure that the `is_mandatory_token_filter: true` property is set on every column where a filter rule is expected.
 
-The most common *best practice* is to define *filter rules* within the token and place the `is_mandatory_token_filter: true` property on every column in a Worksheet or Model where a filter rule is expected. This will deny any access to data if a user has not been assigned values for the expected set of fields.
+* *Indexing* +
+Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in Explore mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token.
+ +
+You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS, or also include an RLS Rule on fields that must also be filtered for the Indexing system.
+
+
+== ABAC attributes
 
 Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups:
 
@@ -33,14 +58,6 @@ Can filter multiple values of any data type. Binds to any Column in any Model or
 * xref:runtime-parameters.adoc[Parameter values] +
 Binds a single value to any Parameter in any Worksheet or Model by Parameter Name and Type match. Parameters can be used in *Worksheet formulas* and then as *Worksheet filters*.
 
-[IMPORTANT]
-====
-[#column-name-warning]
-The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name the values will not bind to any column. You must coordinate between the team that maintains the Worksheets and Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] if any changes will be made to a Model or Worksheet.
-For the same reasons, the end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens.
-When column names change, ensure that the `is_mandatory_token_filter: true` property is set on every column where a filter rule is expected.
-====
-
 The request for a token with ABAC details can xref:abac-user-parameters.adoc#persistForUser[persist] the set of filters and Parameter values to user sessions within ThoughtSpot, after which all sessions and scheduled reports will use the persisted values until they are changed by another token generation request.
 
 == Token request
@@ -90,6 +107,11 @@ An example of setting both `filter_rules` and `parameter_values` without any per
  ]
 ----
 
+[NOTE]
+====
+Passing an empty array in a filter column clears all filter rules and doesn't apply the filters on the column.
+====
+
 === Apply to specific objects
 By default, any specified filter or parameter will bind to any content with an exact match for the column or Parameter name.
 
@@ -152,8 +174,11 @@ a|All persisted rules and attributes of the user object are replaced with the se
 
 [NOTE]
 ====
-In 10.4.0.cl, the `REPLACE` behavior can be achieved by making a `RESET` request followed by an `APPEND` request, then passing only the `APPEND` request token to the browser.
+* By default, the `RESET` option resets all attributes. In 10.6.0.cl and later versions, you can specify the attributes  to reset in the `reset_option` attribute. The `reset_option` allows resetting only filter rules, Parameters, or group properties in the token API request.
+* In 10.4.0.cl, the `REPLACE` behavior can be achieved by making a `RESET` request followed by an `APPEND` request, then passing only the `APPEND` request token to the browser.
 ====
+
+
 |=====
 
 Filters and parameters must be *persisted* for them to apply to user sessions when using xref:trusted-authentication.adoc#cookie[cookie-based trusted authentication] or scheduled reports.

modules/ROOT/pages/api-auth-session.adoc

@@ -15,6 +15,13 @@ When using the REST API through a web browser, ThoughtSpot recommends that you u
 include::{path}/log-in-api.adoc[]
 
 A successful login returns a session cookie that can be used in your subsequent API calls. For more information, see xref:api-auth-session.adoc#sessionCookies[Session cookies for subsequent API calls].
+[NOTE]
+====
+* If MFA [beta betaBackground]^Beta^ is enabled on your ThoughtSpot instance then basic authentication with only `username` and `password` will return an error.
+Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance.
+* Embedded users authenticating to ThoughtSpot with basic authentication are recommended to switch to `AuthType.TrustedAuthTokenCookieless`.
+* MFA can be enabled on your instance only if Identity and Access Management (IAMv2) is already enabled.
+====
 
 == Trusted authentication
 

modules/ROOT/pages/api-changelog.adoc

@@ -20,11 +20,9 @@ Allows adding `name` and `description` text strings. When these parameters are d
 * `HostEvent.Pin` +
 Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal.
 
-////
 For more information, see xref:embed-events.adoc#hostEventParameterization[Host Events] documentation.
-////
 
-|[tag greenBackground]#NEW FEATURE# a| Customization settings for Spotter embed
+|[tag greenBackground]#NEW FEATURE# a|
 
 New configuration attributes::
 
@@ -65,11 +63,9 @@ The following new CSS variables are available for Spotter interface customizatio
 * `--ts-var-spotter-input-background`
 * `--ts-var-spotter-prompt-background`
 
-////
 For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles].
-////
+|[tag greenBackground]#NEW FEATURE# a|
 
-|[tag greenBackground]#NEW FEATURE# a| Liveboard embed enhancements
 
 Configurations attributes::
 
@@ -85,9 +81,6 @@ Use the following action IDs in the `disabledActions`, `visibleActions`, or `hid
 * `Action.DisableChipReorder` +
 ID for the action that disables filter chip reordering.
 * `ChangeFilterVisibilityInTab` +
-ID for the action that allows you to modify filter visibility in a Liveboard tab.
-|====
-
 
 == Version 1.35.0, December 2024
 

modules/ROOT/pages/authentication.adoc

@@ -20,10 +20,28 @@ In this method, a REST client sends the `username` and `password` to authenticat
 xref:authentication.adoc#trusted-auth-v2[Trusted authentication];;
 In this method, the REST client must send the `username` and `secret_key` in the API request to obtain an authentication token. The `secret_key` is generated if **Trusted authentication** is enabled on your ThoughtSpot instance.
 
+Multifactor authentication (MFA):: [beta betaBackground]^Beta^
++
+ThoughtSpot now supports multifactor authentication (MFA) for environments using local authentication with Identity and Access Management (IAMv2). If MFA  is enabled on your ThoughtSpot instance,
+
+*  The REST API calls to the API endpoints authenticating to ThoughtSpot with only `username` and `password` will return an error. You will now have an additional authentication factor.
++
+Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance.
+* Embedded users authenticating to ThoughtSpot with basic authentication are recommended to switch to `AuthType.TrustedAuthTokenCookieless`.
+* Non-embedded users calling REST APIs authenticating to ThoughtSpot with only `username` and `password` will return an error. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance.
+
+For more information, see https://docs.thoughtspot.com/cloud/latest/authentication-local-mfa[Multifactor authentication for customers using local authentication, window=_blank].
+
 [#loginTS]
 == Cookie-based authentication
 For cookie-based authentication, make an API call to the `/api/rest/2.0/auth/session/login` endpoint with the `username`, `password`, and other attributes in the request body.
 
+[NOTE]
+====
+* If MFA is enabled on your ThoughtSpot instance then authentication with only `username` and `password` will return an error. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance.
+* MFA can be enabled on your instance only if Identity and Access Management (IAMv2) is already enabled.
+====
+
 === Request parameters
 [width="100%" cols="1,4"]
 [options='header']
@@ -130,6 +148,12 @@ By default, the token obtained from ThoughtSpot is valid for 5 minutes (300 seco
 
 You can obtain a token that grants read-only access to a ThoughtSpot metadata object via a `POST` request to the `/api/rest/2.0/auth/token/object` endpoint, or get a token that grants full access to  ThoughtSpot via `/api/rest/2.0/auth/token/full`.
 
+[NOTE]
+====
+* If MFA is enabled on your ThoughtSpot instance then authentication with only `username` and `password` will return an error. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance.
+* MFA can be enabled on your instance only if Identity and Access Management (IAMv2) is already enabled.
+====
+
 ==== Get a token for full access
 
 To get an access token that grants full access to ThoughtSpot, send a `POST` request with `username`, `password`, and other attributes to the `/api/rest/2.0/auth/token/full` endpoint:
@@ -539,7 +563,8 @@ If your current implementation is using the beta version of the ABAC and you wan
 |`username`
 |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, a new user account will be created and added to ThoughtSpot.
 |`password`
-a|__String__. Password of the user account. If using `secret_key` to generate the token, do not specify the `Password`.
+a|__String__. Password of the user account. If using `secret_key` to generate the token, do not specify the `Password`. +
+If MFA is enabled on your ThoughtSpot instance then API call with only `username` and `password` will return an error.
 |`secret_key`
 |__String__. The secret key string provided by the ThoughtSpot server. ThoughtSpot generates this secret key xref:trusted-authentication.adoc#trusted-auth-enable[when trusted authentication is enabled].
 |`validity_time_in_sec` +
@@ -549,16 +574,28 @@ __Optional__|__Integer__. If the Orgs feature is enabled on your instance, speci
 |`persist_option` a| Indicates if the filter rules and Parameter attributes defined in the API request should persist for user sessions initiated with the token obtained from this API call. The following options are available:
 
 * `APPEND` +
-Adds the attributes defined in the API request to the user’s user properties. These properties will be applied to user sessions and for scheduled jobs if any.
+Adds the attributes defined in the API request to the user properties. These properties will be applied to user sessions and for scheduled jobs if any.
 
 * `NONE` +
-The security entitlements assigned via attributes will be used only for the user session initiated with the token generated from this API call.
+
+Does not update the existing user properties. The attributes defined in the API request will be applied to the token, but do not persist when the token expires.
 
 * `REPLACE` +
-Available from 10.5.0.cl. Replaces existing user properties of the user with the attributes defined in this API request.
+Available from 10.5.0.cl. Replaces existing user properties of the user with the new attributes assigned to the token in the API request.
 
 * `RESET` +
-Resets the user properties assigned to a user upon token generation.
+Resets the existing user properties upon token generation and adds the new attributes defined in the request. By default, `"persist_option": "RESET"` resets all attributes, unless a specific `reset_option` is defined.
+
+|`reset_option` a|__Array of strings__. Allows you to define the type of attributes to reset upon token generation. The following options are available:
+
+* `FILTER_RULES` +
+Resets filter attributes.
+
+* `PARAMETERS`
+Resets only Parameters.
+
+* `GROUPS`
+Resets group assignments
 
 |`filter_rules`  a|__Array of filter rules__. An array of runtime filter conditions to pass via token. Each rule in the array must include the following information:
 

modules/ROOT/pages/common/nav.adoc

@@ -22,7 +22,7 @@
 ** link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction[REST API v2 Playground]
 ** link:{{navprefix}}/graphql-play-ground[GraphQL Playground]
 ** +++<a href="{{previewPrefix}}/api/rest/playgroundV1" target="_blank">REST API v1 Playground</a>+++
-** link:{{navprefix}}/theme-builder[Theme Builder ^[Beta\]^]
+** link:{{navprefix}}/theme-builder[Theme Builder ^Beta^]
 ** link:{{navprefix}}/spotdev-portal[How to use]
 *** link:{{navprefix}}/dev-playground[Visual Embed Playground]
 *** link:{{navprefix}}/graphql-playground[GraphQL Playground]
@@ -63,7 +63,7 @@
 *** link:{{navprefix}}/full-embed[Embed full application]
 *** link:{{navprefix}}/search-embed[Embed search page]
 *** link:{{navprefix}}/embed-nls[Embed Natural Language Search]
-*** link:{{navprefix}}/embed-spotter[Embed Spotter ^BETA^]
+*** link:{{navprefix}}/embed-spotter[Embed Spotter]
 *** link:{{navprefix}}/embed-searchbar[Embed search bar]
 *** link:{{navprefix}}/react-app-embed[Embed with React components]
 
@@ -74,6 +74,7 @@
 ***** link:{{navprefix}}/css-variables-reference[CSS variables reference]
 ***** link:{{navprefix}}/customize-icons[Customize icons]
 ***** link:{{navprefix}}/customize-text[Customize text strings]
+**** link:{{navprefix}}/theme-builder-doc[Theme builder ^Beta^]
 
 *** link:{{navprefix}}/filters-overview[Filters overview]
 **** link:{{navprefix}}/runtime-overrides[Runtime overrides]