diff --git a/modules/ROOT/pages/3rd-party-script.adoc b/modules/ROOT/pages/3rd-party-script.adoc index 680cbfa75..a978ada50 100644 --- a/modules/ROOT/pages/3rd-party-script.adoc +++ b/modules/ROOT/pages/3rd-party-script.adoc @@ -1,4 +1,4 @@ -= Integrate external tools and allow custom scripts += External tools and script integration :toc: true :toclevels: 2 @@ -52,6 +52,11 @@ image::./images/csp-script-domain.png[CSS script-src domain] * The *CSP script-src domains* cannot be enabled and configured at the Org level. When configured, this setting will apply to all the Orgs configured on your instance. ==== +=== Allow Websocket endpoints +If your tool uses WebSockets, add the tool’s `wss://` endpoint to the CSP and CORS allowlists in ThoughtSpot. This enables secure WebSocket connections from an embedded ThoughtSpot page to the tool's WebSocket endpoint without being blocked by the browser’s Content Security Policy. + +Only hosts explicitly listed with `wss://` are permitted. You can add `wss://` URL in the **Develop** > **Security Settings** page. + == Passing variables to the hosted script To pass variables to the customer's hosted script, Visual Embed SDK provides the `customVariablesForThirdPartyTools` parameter. The `customVariablesForThirdPartyTools` is an object containing the variables that you wish to pass to the customer’s hosted JavaScript. These may include private information such as credentials or keys. The hosted JavaScript will access these variables via the `window.tsEmbed` object. diff --git a/modules/ROOT/pages/abac_rls-variables.adoc b/modules/ROOT/pages/abac_rls-variables.adoc index 13155c0cf..7d3cc95f5 100644 --- a/modules/ROOT/pages/abac_rls-variables.adoc +++ b/modules/ROOT/pages/abac_rls-variables.adoc @@ -2,75 +2,58 @@ :toc: true :toclevels: 2 -:page-title: ABAC via tokens +:page-title: ABAC via RLS with variables :page-pageid: abac-via-rls-variables :page-description: Attribute-based access control pattern with variable attributes referenced in Row-Level Security (RLS) rules on a given table. -Attribute-Based Access Control (ABAC) is an access control model in which security entitlements are determined by evaluating a set of attributes included in a token generated for a user. The attributes are passed in a JSON Web Token (JWT) at session creation to dynamically filter data and enable user-specific security policies. +Attribute-Based Access Control (ABAC) is an access control model in which security entitlements are assigned to a ThoughtSpot user directly as a set of attributes with lists of values, rather than relying on a JOINed entitlements table within the data model. + +ThoughtSpot allows assigning attribute values to a user at session creation time by adding the values to the user's access token request. + +RLS rules are defined on table objects, which bind dynamically generated `WHERE` clauses to any generated query. Within RLS rules, attributes are referenced by their variable names using the `ts_var()` function to dynamically filter data and enable user-specific security policies. == Overview -To implement data security for application users, administrators can define RLS rules that use system variables such as `ts_username` or `ts_groups`. If a ThoughtSpot deployment requires granular access control and dynamic assignments beyond what system variables can support, administrators can use formula variables within RLS rules. +RLS rules have a defined set of system variables such as `ts_username` or `ts_groups`. Once ABAC via RLS is enabled, the `ts_var()` formula is available within the RLS rule editor to refer to any defined Formula variable within ThoughtSpot. -Formula variables are custom variables that enable dynamic and context-aware logic in RLS rules. They can be assigned at the Org, user, and data model levels. +Formula variables are custom variables defined within ThoughtSpot that enable dynamic and context-aware logic in RLS rules. They are assigned at the user level during session creation for the ABAC pattern, although they can be set at Org and data model levels as well. +//// In embedded analytics scenarios, where each user may require different data access, administrators can assign security attributes and rules on a per-user basis. For these use cases, administrators can implement a JWT-based ABAC model combined with RLS to enforce data security using dynamic attributes derived from formula variables. In the ABAC via RLS with variables method, administrators add formula variables to RLS rules and pass their values (`variable_values`) as security attributes and entitlements to the user session through a JWT. All derived objects then inherit the data security rules from the underlying Table and are filtered according to the user’s entitlements provided in the token. +//// +=== Implementation steps [NOTE] ==== - -* Formula variables are available on ThoughtSpot starting from 10.15.0.cl. If this feature is not enabled on your instance, contact ThoughtSpot Support. - -* In the legacy JWT ABAC token requests, you could set the `persist_option` parameter to `NONE`, `APPEND`, `REPLACE`, and `RESET`. However, when you use the `variable_values` parameter in the JWT API token request to set up RLS values for a given user, only `APPEND` and `REPLACE` are supported. - -* To reset the formula variable attributes of a user, use the `/api/rest/2.0/template/variables/update-values` API endpoint. - -* The ability to set variable values only for the current session, previously achieved by setting `persist_option: NONE`, is not supported with RLS via ABAC. + -For session-based rules, create dedicated user accounts for your application users and apply persisted rules. This approach ensures that Liveboard schedule attachments enforce security rules and deliver only secured output to your end users. When combined with cookieless authentication, this configuration addresses all use cases that previously relied on session-based JWT. You can simplify user provisioning and programmatically manage user creation and deletion workflows using ThoughtSpot's REST APIs. +Formula variables are available on ThoughtSpot starting from 10.15.0.cl. If this feature is not enabled on your instance, contact ThoughtSpot Support. ==== -=== Indexing -Several features within ThoughtSpot, such as autocompletion in Search on values within columns, use ThoughtSpot indexing. Due to the runtime nature of ABAC tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. This means the indexed columns may expose values in search suggestions or autocompletion that a user should not see, even if ABAC filters would block access to the underlying data. To prevent this, you can do one of the following: - -* Disable indexing for columns and fields that must be restricted by ABAC. You may also want to disable indexing on all sensitive columns. -* Define an RLS rule on those fields, since RLS is enforced at the indexing layer and will secure suggestions and sample values. - -=== Implementation steps The ABAC implementation with formula variables and RLS rules includes the following steps: * xref:abac_rls-variables.adoc#_create_formula_variables[Creating formula variables] + To generate tokens with variable attributes, the variables must be available in ThoughtSpot. To create variables, use the xref:variables.adoc#_create_a_variable[Variable REST API]. -* xref:abac_rls-variables.adoc#_add_rls_rules_with_variable_references[Adding RLS rules with formula variables] + -When defining an RLS rule with variables, use the `ts_var` function. These RLS rules will apply to the Models, Liveboards, and other objects derived from that Table. -* xref:abac_rls-variables.adoc#_define_values_and_scope_for_variables[Creating a token request with variable attributes] + -To generate a JWT token, use the `/api/rest/2.0/auth/token/custom` REST API endpoint. The token generation request must include the variable attributes, which will be used for RLS evaluation to enable per‑user entitlements and data filters across all the objects derived from the Table. +* xref:abac_rls-variables.adoc#_add_or_update_rls_rules_with_variable_references[Adding RLS rules with formula variables] + +When defining an RLS rule with variables, use the `ts_var` function. These RLS rules will apply to the Models, Liveboards, and other objects derived from that Table. *A formula variable must be defined before it can be used in an RLS rule.* +* xref:abac_rls-variables.adoc#_create_an_abac_token_request_with_variable_attributes[Creating a token request with variable attributes] + +Attribute values are assigned to users by requesting a token using the `/api/rest/2.0/auth/token/custom` REST API endpoint. * xref:abac_rls-variables.adoc#_verify_the_entitlements[Verifying entitlements] + -To ensure data security rules are applied, check user entitlements and verify if they are translated accurately during query generation. - -The ABAC via tokens method requires the xref:trusted-authentication.adoc[trusted authentication] setup. - -//// -=== Mandatory token filters +To ensure data security rules are applied, check user entitlements and verify that they are translated accurately during query generation. Variables and their assigned values are visible to administrators using the `/api/rest/2.0/template/variables/search` endpoint with the `response_content` parameter set to `METADATA_AND_VALUES`. -The `is_mandatory_token_filter: true` setting in object TML enforces that a filter rule must be provided for a specific column. When this attribute is set on a column in a Model, ThoughtSpot will deny all data access for users who do not have a corresponding filter rule for that column in their ABAC token. - -When setting filter rules within the token, you must place the `is_mandatory_token_filter: true` property on every column in a Model where a filter rule is expected. This setting 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, use ThoughtSpot indexing. Due to the runtime nature of ABAC tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. This means the indexed columns may expose values in search suggestions or autocompletion that a user should not see, even if ABAC filters would block access to the underlying data. To prevent this, you can do one of the following: -[#column-name-warning] -The filter rules require passing the *exact* column name as defined in the Model. Otherwise, the values will not bind to any column. You must coordinate between the team that maintains the data objects 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 and to ensure column names remain consistent. + -For this reason, end users of an embedded app must not be granted edit access to any Model using ABAC rules via tokens. Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data is returned for users when column names change. +* Disable indexing for columns and fields that must be restricted by ABAC. You may also want to disable indexing on all sensitive columns. +* Define an RLS rule on those fields, since RLS is enforced at the indexing layer and will secure suggestions and sample values. -[NOTE] -==== -If a column is set with both `is_hidden: true` and `is_mandatory_token_filter: true`, and filter conditions for that column are defined in the ABAC token, the filter will be applied as expected. The column will be hidden from the user interface, but the mandatory filter requirement will still be enforced, and data will be shown according to the filter values provided in the token. -==== -//// == Create formula variables +Formula variables must be defined in ThoughtSpot before they can be used in any RLS rule via the `ts_var()` formula. + +To view the variables available on your instance, use the `POST /api/rest/2.0/template/variables/search` API call. -To view the variables available on your instance, use the `POST /api/rest/2.0/template/variables/search` API call. To create a new variable, use the `/api/rest/2.0/template/variables/create` API endpoint. +To create a new variable, use the `/api/rest/2.0/template/variables/create` API endpoint. To configure formula variables for all Orgs on your instance or the Primary Org, cluster administration privileges are required. Org administrators can configure formula variables for their respective Orgs. Users with the `CAN_MANAGE_VARIABLES` (*Can manage variables*) role privilege can also create and manage variables for their Org context. @@ -87,33 +70,46 @@ During variable creation, specify the xref:variables.adoc#data_type[`data_type`] Formula variables for `BOOLEAN` and `TIME` data types are not supported. -[source,cURL] +[source,JSON] ---- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/]api/rest/2.0/template/variables/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ +{ "type": "FORMULA_VARIABLE", "name": "country_var", "is_sensitive": false, "data_type": "VARCHAR" -}' +} ---- -The variable update API allows assigning variable values and setting the scope. In the ABAC implementation, administrators can set the variable values and scope when xref:abac_rls-variables.adoc#_create_an_abac_token_request_with_variable_attributes[generating a JWT] using the `/api/rest/2.0/auth/token/custom` API endpoint. +The variable update API (`/api/rest/2.0/template/variables/{identifier}/update`) allows updating the variable name and other attributes of the variable definition, but not the values assigned to users or other principals. -== Add RLS rules with variable references -To define RLS rules with variables for a Table: +Variable values are set either by xref:abac_rls-variables.adoc#_create_an_abac_token_request_with_variable_attributes[generating a token] using the `/api/rest/2.0/auth/token/custom` API endpoint or via the Update Variable Values REST API. + +== Add or update RLS rules with variable references +RLS rules are defined on Table objects: . Navigate to the Data workspace and click the Table for which to define RLS rules. . Click *Row security* and then click *+ Add row security*. -. In the *Row Security Editor*, define the rules. To reference the formula variable in the rule, use the `ts_var` function. For example, If you want to limit user access to data of a specific region, you can create a region-specific variable, `region = ts_var(region_var)`, and assign values in the token request. +. In the *Row Security Editor*, define the rules. To reference the formula variable in the rule, use the `ts_var(varName)` function, with no quotes around the formula variable name. For example, to limit a column called `region` to the values set in a formula variable called `region_var`, set the RLS rule to: `region = ts_var(region_var)`. + +[NOTE] +==== +Variable values are set through the token request. The RLS rule specifies how the values will be used in the generated RLS WHERE clauses in the SQL. +==== + +=== RLS rule examples +RLS rules must always evaluate logically to SQL boolean `TRUE` or `FALSE`. +If a user has no variable values for a given formula variable, this results in `FALSE`. -=== RLS rule with a single variable reference +There is a special wildcard value `['TS_WILDCARD_ALL']` that a formula variable can be set to represent "Allow all". +In this example, `customer` represents the `customer` column in the table, and `customer_var` represents a variable. If the value of `customer_var` is set to `TS_WILDCARD_ALL`, the user can access all customers in the column. + +---- +customer = ts_var(customer_var) +---- + +==== RLS rule with a single variable reference In this formula example, `country` refers to the "country" column in the data table, and `country_var` is the variable. ---- @@ -124,7 +120,7 @@ If `country_var` is assigned a single value, the user is permitted to view only If `country_var` is assigned multiple values, the formula translates to `country IN ('value1', 'value2', ...)`. The query engine interprets `=` as the `IN` clause in this case and returns rows that match these values; for example, `WHERE country IN ('Australia', 'Germany')`. -=== RLS rules with multiple variables +==== RLS rules with multiple variables The RLS rules support the `AND` operator, which means that you can combine multiple conditions in a single RLS rule, so that a row is accessible only if all the specified conditions are met. The following rule restricts data access to rows if the `country` column in the data table matches the value assigned to `country_var` and the `Department` column matches the value assigned to `department_var` for that user. @@ -139,14 +135,7 @@ The rule in this example restricts data access to rows where the `region` column region = ts_var(region_var) AND product = ts_var(product_var) ---- -=== Allow all rule with a TS_WILDCARD_ALL variable -In this example, `customer` represents the column `customer` in the table and `customer_var` represents variable. If the value of the customer_var variable is set to `TS_WILDCARD_ALL`, the user can access all customers in the column. - ----- -customer = ts_var(customer_var) ----- - -=== Group override rule with variable-based check +==== Group override rule with variable-based check In any security formula you build, you may want a clause that gives access to all data to certain groups. In the rule definition, you can include system variables, such as `ts_groups`, to build your preferred logic: In this example, users can access data if they are in the "data developers" group, or if the `Department` column matches the value assigned to their `department_var` variable. @@ -157,7 +146,7 @@ In this example, users can access data if they are in the "data developers" grou ==== Variables with numeric and Date data types -The following rule enforces a numeric threshold and restricts access to rows where the Revenue value is less than or equal to the value provided by the `revenue_cap_var` variable. +The following rule enforces a numeric threshold and restricts access to rows where the Revenue value is less than or equal to the value provided by the `revenue_cap_var` variable. ---- Revenue <= to_double(ts_var(revenue_cap_var)) @@ -171,9 +160,11 @@ The following rule restricts access to rows where the `date_column` is within th == Create an ABAC token request with variable attributes -To generate a token with variable attributes, use the `POST /api/rest/2.0/auth/token/custom` API call. +To set or update variable values for a user, use the `POST /api/rest/2.0/auth/token/custom` endpoint when logging in the user. -The variable attributes defined in the token request take effect only if they are referenced in an RLS rule. If the variables are not used in any formula or RLS rule, they will have no impact on data access. Before generating the request with variable attributes, ensure that the xref:abac_rls-variables.adoc#_add_rls_rules_with_formula_variables_to_tables[variables are added to the RLS rules] for the Table. +You can also use the `/api/rest/2.0/template/variables/update-values` endpoint for bulk operations or targeted resets. + +The variable attributes defined in the token request take effect only if they are referenced in an RLS rule. If the variables are not used in any formula or RLS rule, they have no impact on data access. Before generating the request with variable attributes, ensure that the xref:abac_rls-variables.adoc#_add_or_update_rls_rules_with_variable_references[variables are added to the RLS rules] for the table. In the token request, include the following properties along with the `username`, xref:trusted-auth-secret-key.adoc[`secret_key`]: @@ -189,7 +180,7 @@ The `variable_values` array requires the following parameters: * `name` + __String__. Name of the formula variable. The formula variable referenced on the token request must be available in ThoughtSpot and included in the RLS rule. * `values` + -__Array of strings or numeric values__. When assigning values, ensure the data format of values matches the data type set of that variable. If you are adding a variable to filter by country with the `VARCHAR` data type, specify the string values as shown in this example: +__Array of strings or numeric values__. When assigning values, ensure the data format of the values matches the data type set for that variable. If you are adding a variable to filter by country with the `VARCHAR` data type, specify string values as shown in this example: [source,JSON] ---- @@ -207,15 +198,19 @@ __Array of strings or numeric values__. When assigning values, ensure the data f All values are passed into the token as *arrays of strings*, even if the column is a numeric or date type in ThoughtSpot and the database. The column data type will be respected in the query issued to the database. -==== Allow all values by default +==== Allow all wildcard value -To allow all values by default, specify `["TS_WILDCARD_ALL"]` as the variable value to grant access to all values in a given column. +To allow all values for a given field, set the formula variable value to an array using the wildcard: `["TS_WILDCARD_ALL"]`. -In this example, the user is allowed all access for one variable, while for the others, specific values are set. +In this example, the user is allowed all access for one variable, while for the other, specific values are set. [source,JSON] ---- "variable_values": [ + { + "name": "product_var", + "values": ["TS_WILDCARD_ALL"] + }, { "name": "country_var", "values": [ @@ -223,19 +218,6 @@ In this example, the user is allowed all access for one variable, while for the "Singapore", "Australia" ] - }, - { - "name": "department_var", - "values": [ - "Sales", - "Marketing" - ] - }, - { - "name": "product_var", - "values": [ - "TS_WILDCARD_ALL" - ] } ] ---- @@ -243,10 +225,13 @@ In this example, the user is allowed all access for one variable, while for the If `TS_WILDCARD_ALL` is set for variable attributes, ensure that the RLS rules are defined clearly on the Table to avoid unintended data exposure. ==== Deny all by default -For every variable included in the token request, you can assign one or more values. All variables referenced in RLS rules are required. If a variable is not assigned any value, query generation will fail with the following error. +For every variable included in the token request, you can assign one or more values. All variables referenced in RLS rules are required. If a variable is not assigned any value, query generation fails with the following error: -`Error in loading data -No values are assigned to some or all Formula Variables` +[source,text] +---- +Error in loading data +No values are assigned to some or all Formula Variables +---- [.bordered] [.widthAuto] @@ -256,25 +241,76 @@ Due to this error, no data is returned, effectively denying all data access for === Persist options and session-based rules -Variable attributes must be *persisted* for them to apply to user sessions when using xref:trusted-authentication.adoc#cookie[cookie-based trusted authentication] or scheduled reports. To specify whether variable attributes and rules should persist for user sessions, you must define the `persist_option` parameter. +Variable attributes must be *persisted* for them to apply. -To append or replace the attributes, use the following options: - -* `APPEND` + -Adds the attributes defined in the API request to the user properties. These properties will be applied to the current and future user sessions and scheduled reports until they are explicitly changed through a token update request. +To append or replace attribute values for a user, use one of the following `persist_option` values in the token request: * `REPLACE` + -Replaces existing variable assignments with the new values. +Replaces the full set of existing variable assignments with the new values from the token request. + +* `APPEND` + +Adds the attribute values defined in the API request to the existing attribute values for the user. + +If you don't want to append or replace any attribute values, do not pass any details about the variable in the token update request. [NOTE] ==== -* The ABAC implementation with RLS and formula variables does not support session-based rules. Therefore, ThoughtSpot does not recommend setting the `persist_option` attribute to `NONE`. -* If you don't want to append or replace any attributes, do not pass any variable values in the token update request. -* Resetting attributes using the`"persist_option": "RESET"` attribute in the token request is not supported. Passing an empty array does not reset the attributes. To reset the formula variable attributes of a user, use the `/api/rest/2.0/template/variables/update-values` API endpoint. +* The ABAC implementation with RLS and formula variables does not support session-based rules. Do not use the legacy `persist_option` value of `NONE`. +* `"persist_option": "RESET"` attribute is also a legacy value and is not supported. ==== +=== Resetting a user or a variable +Passing an empty array along with a formula variable name in the token request *does not reset the attribute values* for that formula variable for that user. + +To change formula variable attributes of a user, especially to set entitlements to an empty set, use the `/api/rest/2.0/template/variables/update-values` API endpoint. + +[WARNING] +==== +The `RESET` operation erases all variable value settings for all users for a variable, regardless of any `variable_value_scope` provided. Use with caution; it is a complete reset. +==== + +A formula variable exists across all Orgs in ThoughtSpot, but the values are recorded on a per Org and per Principal basis. To use the Update Variable Values REST API, you'll need to provide the `org_identifier` as well as the username as `principal_identifier` and set `principal_type` to `USER` as seen below: + +[,json] +---- +{ + "variable_assignment": [ + { + "variable_identifier": "country_var", + "variable_values": [], + "operation": "REPLACE" + } + ], + "variable_value_scope": [ + { + "org_identifier": "Prod", + "principal_type": "USER", + "principal_identifier": "jane.smith@company.com" + } + ] +} +---- +The above command results in `jane.smith@company.com` being denied any access when `country_var` is used in an RLS rule. + + +[NOTE] +==== +Do not use the `/api/rest/2.0/users/{user_identifier}/update` endpoint, as it does not support updating variable values. +==== + +=== Session-based ABAC and one-time users + +The ability to set variable values only for the current session, previously achieved by setting `persist_option: NONE`, is not supported with RLS via ABAC. + +For session-based rules, create dedicated one-time user accounts for your application users and apply persisted rules. Unless specifically stated in your contract, there is no limit to the number of users that can be created and provisioned in ThoughtSpot. + +This approach ensures that Liveboard schedule attachments enforce security rules and deliver only secured output to your end users. When combined with cookieless authentication, this configuration addresses all use cases that previously relied on session-based JWT. + +You can simplify user provisioning and programmatically manage user creation and deletion workflows using ThoughtSpot's REST APIs. + + === Variable scope -To restrict the scope of the variable attributes and rules to a specific Org context and object, define the `org_identifier` and `objects`. +To restrict the scope of variable attributes and rules to a specific Org context and object, define `org_identifier` and `objects`. ==== Apply to specific objects To apply variable entitlements to a specific object, specify the object IDs in the `objects` array as shown in this example: @@ -298,25 +334,11 @@ The API supports only the `LOGICAL_TABLE` object type. If the object ID is not specified in the API request, the variable values will be applied to all formulas and rules that use those variables, across all objects in the Org for that user. -==== Apply to Org context - -The `org_identifier` attribute in the token request specifies the Org context for the user session and entitlements. - -If the `org_identifier` parameter is not defined in the token request, the token is issued for the user's last logged-in Org. For new users, the token will be assigned to the default Org on their instance. - -To apply variable entitlements to a user session, you must ensure that the RLS rules with variables and relevant objects are available in the Org context specified in the token request. - -=== Example request body +The following example shows the request body for generating a token with formula variable attributes scoped to a particular Model object: -The following example shows the request body for generating a token with formula variable attributes: - -[source,cURL] +[source,JSON] ---- - curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ +{ "username": "UserA", "validity_time_in_sec": 300, "persist_option": "APPEND", @@ -324,24 +346,17 @@ The following example shows the request body for generating a token with formula "secret_key": "f8aa445b-5ff1-4a35-a58f-e324133320d5", "variable_values": [ { - "name": "country_var", - "values": [ - "Japan", - "Singapore", - "Australia" - ] - }, - { - "name": "department_var", + "name": "product_var", "values": [ - "Sales", - "Marketing" + "TS_WILDCARD_ALL" ] }, { - "name": "product_var", + "name": "country_var", "values": [ - "TS_WILDCARD_ALL" + "Japan", + "Singapore", + "Australia" ] } ], @@ -351,17 +366,27 @@ The following example shows the request body for generating a token with formula "identifier": "35aa85fe-fbb4-4862-a335-f69679ebb6e0" } ] -}' +} ---- -If the request is successful, ThoughtSpot generates a token and sends the token details in the API response. +==== Apply to Org context + +The `org_identifier` attribute in the token request specifies the Org context for the user session and entitlements. + +If the `org_identifier` parameter is not defined in the token request, the token is issued for the user's last logged-in Org. For new users, the token will be assigned to the default Org on their instance. + +To apply variable entitlements to a user session, you must ensure that the RLS rules with variables and relevant objects are available in the Org context specified in the token request. [NOTE] ==== -ABAC details are sent in a JWT that can be used as a bearer token for cookieless trusted authentication, REST API calls, or as a sign-in token to start a session. JWTs are compressed by default to handle large payloads. It is recommended to keep the compression enabled to ensure all JWT tokens can get properly interpreted by the application regardless of their size, and to obfuscate the values passed in the JWT payload. If you want to disable it, contact ThoughtSpot Support. +ThoughtSpot access tokens are JWTs that are compressed by default to handle large payloads. It is recommended to keep the compression enabled to ensure all tokens can get properly interpreted by the application regardless of their size, and to obfuscate the values passed in the payload. If you want to disable it, contact ThoughtSpot Support. ==== + +//// +--- THIS IS NOT TRUE ANYMORE === Verify the variable assignment + To retrieve user information and object properties, you can use the `POST /api/rest/2.0/users/search` API call. To include variable details in the response, set the `include_variable_values` parameter to `true` in the API request body. This allows you to fetch variable values associated with the user in the specified context. [source,JSON] @@ -393,13 +418,55 @@ To retrieve user information and object properties, you can use the `POST /api/r } } ---- +//// + +== Verify the entitlements You can also use the `POST /api/rest/2.0/template/variables/search` API call to xref:variables.adoc#_get_variables[get the list of variables] assigned to a specific user, Org, and Model. -==== Updating variable values for a user -To update variable values for a user, you can use the `/api/rest/2.0/template/variables/update-values` endpoint, or `/api/rest/2.0/auth/token/custom` endpoint when logging in the user. Do not use the `/api/rest/2.0/users/{user_identifier}/update` endpoint, as it does not support updating variable values. +Set the `response_content` parameter to `METADATA_AND_VALUES` to see the values that have been set for each user per Org: + +[,json] +---- +{ + "record_offset": 0, + "record_size": -1, + "response_content": "METADATA_AND_VALUES" +} +---- + +This results in the following response: + +[,json] +---- +[ + { "id":"d3abc655-b706-4f91-90ea-cc26bc966d46", + "name":"country_var", + "variable_type":"FORMULA_VARIABLE", + "sensitive":false, + "values":[ + { + "value": null, + "value_list": ["CustomerC","CustomerD"], + "org_identifier": "Prod", + "principal_type": "USER", + "principal_identifier": "ron.smith@company.com", + "model_identifier": null, + "priority": null + },{ + "value": null, + "value_list": null, + "org_identifier": "Prod", + "principal_type": "USER", + "principal_identifier": "jane.smith@company.com", + "model_identifier": null, + "priority": null + } + ] + } +] +---- -== Verify the entitlements To verify the entitlements: . Log in to your app with a user account that does not have the *Can administer and bypass RLS* privilege, and initiate the user session with the ABAC token. @@ -412,4 +479,4 @@ To verify the entitlements: == Additional resources * For information about variables and variable APIs, see link:https://docs.thoughtspot.com/cloud/latest/rls-variables-reference[Variables] and xref:variables.adoc[Variable APIs]. -* For information about RLS rules,see xref:rls-rules.adoc[RLS Rules] and link:https://docs.thoughtspot.com/cloud/latest/security-rls[ThoughtSpot Product Documentation, window=_blank]. +* For information about RLS rules, see xref:rls-rules.adoc[RLS rules] and link:https://docs.thoughtspot.com/cloud/latest/security-rls[ThoughtSpot product documentation, window=_blank]. diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 5840406b4..923c15448 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,13 +8,67 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 1.46.x, March 2026 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#DEPRECATED# a| **dataPanelV2** + +The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. + +|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. + +Chat history sidebar customization:: + +//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. +* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. +* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: +** `Action.DataModelInstructions` for the data model instructions icon. +** `Action.SpotterSidebarHeader` for the chat history sidebar header +** `Action.SpotterSidebarFooter` for the chat history sidebar footer +** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. +** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. +** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. +** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. +** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. +** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. +//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. + +Events:: +* `HostEvent.DataModelInstructions` + +Opens the Data Model instructions modal. +* `EmbedEvent.DataModelInstructions` + +Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. +* `EmbedEvent.SpotterConversationRenamed` + +Is emitted when a user renames a saved chat. +* `EmbedEvent.SpotterConversationDeleted` + +Is emitted when a saved chat is deleted. +* `EmbedEvent.SpotterConversationSelected` + +Is emitted when a saved chat is selected in the chat history sidebar. + +|[tag greenBackground]#NEW FEATURE# a| **Page context settings for host events** +The Visual Embed SDK includes the `getCurrentContext()` function to fetch the current context and route host events to a specific xref:ContextType.adoc[context type] in the embedded view. +For more information, see xref:events-context-aware-routing.adoc[Host events in multi-modal contexts]. + + +|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + + +Use this enhanced configuration to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. +* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +|==== + == Version 1.45.0, February 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|**Spotter enhancements ** +|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** -You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, Chat history, and a new chat prompt interface. +You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. * To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. * To use Auto mode, set the `worksheetId` to `auto_mode`. @@ -37,7 +91,7 @@ On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coa Styling and grouping:: -* The `isLiveboardStylingAndGrouping` attribute, used for enabling the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated attribute, `isLiveboardStylingAndGrouping` continues to work, we recommend switching to the new configuration setting. +* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. * The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: ** `Action.MoveToGroup` for the **Move to Group** menu action. ** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. @@ -51,21 +105,21 @@ For more information, see link:https://docs.thoughtspot.com/cloud/latest/securit + The `showMaskedFilterChip` setting is also available in full application embedding. -|[tag greenBackground]#NEW FEATURE# a|**Publishing objects** +|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** The following action IDs are available for the data publishing menu actions in the *Data workspace* page: * `Action.Publish` for *Publish* -* `Action.ManagePublishing` for *Manange publishing* -* `Action.Unpublish` foe *Unpublish* +* `Action.ManagePublishing` for *Manage publishing* +* `Action.Unpublish` for *Unpublish* * `Action.Parameterize` for *Parameterize* |[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** To handle errors in the embedding workflows, the SDK includes the following features: -* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, `NETWORK` error. -* `EmbedErrorCodes` enum with specific error codes for programmatic error handling -* `EmbedErrorDetailsEvent` interface for structured error event handling +* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. +* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. +* `EmbedErrorDetailsEvent` interface for structured error event handling. For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. |==== @@ -75,7 +129,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Enumerati [width="100%" cols="1,4"] |==== -|[tag redBackground]#DEPRECATED# | ** Use `minimumHeight` instead of `defaultHeight` ** + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. @@ -90,7 +144,7 @@ Allows configuring which API calls to intercept. * `interceptTimeout` + Sets the timeout duration for handling interception. * `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables the use of `EmbedEvent.OnBeforeGetVizDataIntercept` event to emit and intercept search execution calls initiated by the users and implement custom logic or workflow to allow or restrict search execution. +When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. * `EmbedEvent.ApiIntercept` + Emits when an API call matching the conditions defined in `interceptUrls` is detected. diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index e8301160f..bcd2485f5 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -61,6 +61,7 @@ ** link:{{navprefix}}/tsembed[Embed ThoughtSpot in Web app] *** Embed analytics **** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +**** link:{{navprefix}}/embed-liveboard-copy[Embed a Liveboard NEW] **** link:{{navprefix}}/embed-a-viz[Embed a visualization] *** link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] **** link:{{navprefix}}/embed-spotter[Embed Spotter experience] @@ -99,7 +100,8 @@ *** link:{{navprefix}}/action-config[Customize menus] **** link:{{navprefix}}/actions[Action IDs in the SDK] *** link:{{navprefix}}/events-app-integration[Events and app interactions] -**** link:{{navprefix}}/api-search-intercept[Intercept API and data fetch requests] +**** link:{{navprefix}}/context-aware-event-routing[HostEvents in multi‑modal contexts] +**** link:{{navprefix}}/api-search-intercept[API intercept and data fetch requests] *** link:{{navprefix}}/custom-action-intro[Custom actions] **** link:{{navprefix}}/customize-actions[Custom actions through the UI] ***** link:{{navprefix}}/custom-action-url[URL actions] @@ -212,14 +214,16 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] ** link:{{navprefix}}/graphql-guide[GraphQL API ^Beta^] ** link:{{navprefix}}/webhooks[Webhooks] -*** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] *** link:{{navprefix}}/webhooks-lb-schedule[Webhook for Liveboard schedule events ^Beta^] +*** link:{{navprefix}}/webhooks-s3-integration[AWS S3 storage integration for Webhook delivery ^Beta^] +*** link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] * MCP Servers and Tools ** link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] *** link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode] *** link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide] -** link:{{navprefix}}/mcp-integration[ThoughtSpot MCP server] +** link:{{navprefix}}/mcp-integration[Using ThoughtSpot MCP server] +*** link:{{navprefix}}/connect-mcp-server-to-clients[Connecting clients to MCP Server] * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc index f2f06e780..f16d7232d 100644 --- a/modules/ROOT/pages/customize-css-styles.adoc +++ b/modules/ROOT/pages/customize-css-styles.adoc @@ -189,7 +189,7 @@ Use the following variables to customize the Liveboard visualization groups and [NOTE] ==== -To enable this feature contact ThoughtSpot support and set `isLiveboardStylingAndGroupingEnabled` to `true` in the SDK . +To enable this feature contact ThoughtSpot support and set `isLiveboardMasterpiecesEnabled` to `true` in the SDK . ==== [width="100%" cols="7,7"] diff --git a/modules/ROOT/pages/customize-links.adoc b/modules/ROOT/pages/customize-links.adoc index 384a48ac9..c4b185f00 100644 --- a/modules/ROOT/pages/customize-links.adoc +++ b/modules/ROOT/pages/customize-links.adoc @@ -211,10 +211,15 @@ The default link format is `\https://{ThoughtSpot-Host}/#/\{path}`. If your host https://www.mysite.com/{path} ---- -+ -You must also set the `linkOverride` to `true` in the Visual Embed SDK to override the link format of your embedded application pages and navigation links: +. Click *Save changes*. + +== Override ThoughtSpot URLs + +Link override settings allow embedded users to redirect native ThoughtSpot URLs to links within their host application. ThoughtSpot supports two Visual Embed SDK configurations for overriding links generated by ThoughtSpot. These settings work the same for multi-tenant ThoughtSpot embedded instances too. + +You can set the `linkOverride` to `true` in the Visual Embed SDK to override the link format of your embedded application pages and navigation links. Once enabled, all links opened in a new tab via the right-click menu will show host application URLs. + -+ [source,JavaScript] ---- const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { @@ -229,9 +234,21 @@ const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { appEmbed.render(); ---- -+ -. Click *Save changes*. +Set `enableLinkOverridesV2` to `true` in the Visual Embed SDK. Once enabled, all links will display host application URLs when hovered over or opened in a new tab. ThoughtSpot recommends using this enhanced configuration for you link override settings. +[source,JavaScript] +---- +const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + pageId: Page.Home, + showPrimaryNavbar: true, + enableLinkOverridesV2: true, +}); +appEmbed.render(); +---- == Verify system-generated links diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index b66347f3f..e7012e98b 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -40,7 +40,6 @@ a| ** A hamburger icon for the sliding navigation overlay ** Object search bar ** Help and profile icons + -The user profile includes *Admin settings* option, which is visible to users with administration privileges. ** Org switcher * Left navigation ** A sliding left navigation panel controlled via the hamburger icon @@ -70,14 +69,13 @@ To show or hide the application switcher. | [tag greenBackground tick]#✓# Supported + In V2 experience, hides the app selector in the top navigation bar. | [tag greenBackground tick]#✓# Supported + -In the V3 experience, hides the app selection icons on the left navigation panel and the *Admin settings* option in the Profile menu. +In the V3 experience, hides the app selection icons on the left navigation panel. | `disableProfileAndHelp` + To show or hide the help and user profile icons in top navigation bar. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported + Also hides or shows *Help* menu on the left navigation panel of the home page. | [tag greenBackground tick]#✓# Supported + -Also hides the *Admin settings* menu in the profile dropdown. | `hideOrgSwitcher` + To show or hide the Org switcher. @@ -263,7 +261,7 @@ If you want to include the help menu and link:https://docs.thoughtspot.com/cloud By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set `enablePendoHelp` to `false`. -To add custom links to the help menu, use the customization settings available on the **Admin settings** > **Help customization** page. For more information, refer to the link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation]. +To add custom links to the help menu, use the customization options in the **Admin settings** > **Help customization** page. For more information, refer to the link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation]. [source,JavaScript] ---- diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index b64e3d751..68581fbfb 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -14,6 +14,7 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an [options='header'] |===== |Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product +a|xref:deprecated-features.adoc#SagePrivilegeDeprecation[`PREVIEW_THOUGHTSPOT_SAGE` privilege deprecation] a|ThoughtSpot Cloud 26.3.0.cl and later | March 2026 | September 2026 a|xref:deprecated-features.adoc#_answer_data_panel_classic_experience_deprecation[Answer Data panel classic experience] |ThoughtSpot Cloud 26.4.0.cl and later | April 2026 | August 2026 a|xref:deprecated-features.adoc#_worksheet_deprecation_and_removal[Worksheets] a| ThoughtSpot Cloud 10.4.0.cl and later |November 2024 | September 2025 @@ -80,6 +81,18 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |||| |===== +[#SagePrivilegeDeprecation] +== `PREVIEW_THOUGHTSPOT_SAGE` privilege deprecation +The `PREVIEW_THOUGHTSPOT_SAGE` privilege is renamed to `CAN_USE_SPOTTER` with the ThoughtSpot 26.3.0.cl release version. + +Impact on your instance:: +* Both privileges remain supported until the ThoughtSpot 26.9.0.cl release, at which point `PREVIEW_THOUGHTSPOT_SAGE` will be removed. +* For existing ThoughtSpot instances which have enabled RBAC before the 26.3.0.cl release, there will be no automatic changes to the roles created using the `PREVIEW_THOUGHTSPOT_SAGE` privilege. However, the underlying privilege associated with such roles will be renamed to `CAN_USE_SPOTTER`. + +Recommended action:: +For ThoughtSpot instances which have enabled RBAC before the 26.3.0.cl release, the admins will have to create a role in accordance with the newer privilege name. + + == Answer Data panel classic experience deprecation The classic Data panel experience in Search and Answer pages will be deprecated in ThoughtSpot 26.4.0.cl release version. The new data panel experience, which provides a more intuitive layout with improved organization of data elements and features such as query sets and custom groups, will be the default data panel experience on all ThoughtSpot Embedded instances using Visual Embed SDK v1.41.1 or later. diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc index c2abb742c..2d44838fd 100644 --- a/modules/ROOT/pages/embed-ai-analytics.adoc +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -47,7 +47,7 @@ __Available when the Spotter 2 experience is enabled on the instance__. **When to use**: + Use this version if you want to include agentic analytics and richer insights in your ThoughtSpot embedded app. -|Spotter Classic a| An early version of Spotter. +|Spotter Classic a| The early version of Spotter. **Key features and user experience**: + diff --git a/modules/ROOT/pages/embed-pinboard-copy.adoc b/modules/ROOT/pages/embed-pinboard-copy.adoc new file mode 100644 index 000000000..79b279a24 --- /dev/null +++ b/modules/ROOT/pages/embed-pinboard-copy.adoc @@ -0,0 +1,570 @@ += Embed a Liveboard +:toc: true +:toclevels: 2 + +:page-title: Embed Liveboards +:page-pageid: embed-liveboard-copy +:page-description: You can use the LiveboardEmbed SDK library to embed a ThoughtSpot Liveboard in your app and use it for live insights + +This page explains how to embed a ThoughtSpot Liveboard in your Web page, portal, or application. + +A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user. + +== Before you begin + +To embed a Liveboard, you need the following access and setup: + +* Access to a ThoughtSpot instance. +* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. +* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. + + +== Import the SDK package + +Import the `LiveboardEmbed` SDK library to your application environment: + +**npm** +[source,JavaScript] +---- +import { + LiveboardEmbed, + AuthType, + init, + prefetch, + EmbedEvent +} +from '@thoughtspot/visual-embed-sdk'; +---- + +**ES6** +[source,JavaScript] +---- +