diff --git a/modules/ROOT/pages/abac-user-parameters-beta.adoc b/modules/ROOT/pages/abac-user-parameters-beta.adoc new file mode 100644 index 000000000..3a9b45770 --- /dev/null +++ b/modules/ROOT/pages/abac-user-parameters-beta.adoc @@ -0,0 +1,473 @@ += ABAC via tokens (pre-10.4.0.cl) +:toc: true +:toclevels: 3 + +:page-title: Beta ABAC via token (pre-10.4) +:page-pageid: abac-user-parameters-beta +:page-description: Attribute-based access control pattern can be achieved via user parameters sent in the login token + +Row-level security (RLS) using Attribute-Based Access Control (ABAC) via tokens in versions 10.3.0.cl and earlier is a __Beta__ implementation. + +This article describes the best practices to implement ABAC via tokens in a pre-10.4.0.cl environment. + +If your ThoughtSpot instance is on 10.4.0.cl or later, please refer to the xref:abac-user-parameters.adoc[GA documentation]. If you have implemented the beta version of the ABAC and your ThoughtSpot instance is running 10.4.0.cl or later, refer to the instructions in the xref:jwt-migration[migration guide] and update your implementation to use the `auth/token/custom` API endpoint for ABAC token generation. + +[IMPORTANT] +==== +[#beta-warning] +As this feature directly impacts data security in your environment, ThoughtSpot does not support its use in a Production environment until it becomes Generally Available. ThoughtSpot is working on improvements in the upcoming releases that will change some of the best practices recommended in this article and result in the needed re-work of your deployment's security architecture. To understand the RLS best practices for your use case and deployment timelines, and to get these features enabled on your ThoughtSpot instances, contact ThoughtSpot Support. +==== + +== Overview + +In ABAC implementation, security entitlements are sent in as lists of attributes with the token at session creation time via the authentication service. + +Administrators can set the following attributes for a user via the authentication token, along with the existing capability to assign ThoughtSpot groups: + +* xref:runtime-filters.adoc[Runtime filters] + +Can filter multiple values of any data type. Binds to any Column in any Data Source with a matching Column Name (ThoughtSpot property, not underlying database table column name). + +* xref:runtime-parameters.adoc[Parameters] + +Binds a single value to any Parameter in any Worksheet by Parameter Name and Type match. Parameters can be used in *worksheet formulas* and then as *worksheet filters*. + +* xref:runtime-sort.adoc[Runtime sorts] + +Overrides to sort order within columns. + + +[IMPORTANT] +==== +[#column-name-warning] +The runtime filters require passing the *exact* ThoughtSpot Worksheet or Model column name or will not apply to the data set. You must coordinate between the team that maintains the worksheets and the team that builds the token request service if any changes will be made to a worksheet, or the filters will no longer be applied. + +For the same reasons, end users of an embedded app cannot have *edit* access to any worksheet using ABAC RLS via tokens. +==== + +The request for a token with ABAC details can xref:abac-user-parameters-beta.adoc#persistForUser[persist] the set of filters and Parameter values to the user's `user_parameters` property, after which all sessions and scheduled reports will use the persisted values. + +== Token request +The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format, using the existing ThoughtSpot V2.0 REST API access tokens, which are OAuth JWT tokens. + +The token can be used as a bearer token for cookieless Trusted Auth or REST API access, or as a sign-in token to create a ThoughtSpot session, in which case the ABAC user parameters should be *persisted*. + +[NOTE] +==== +ThoughtSpot compresses the size of JWT token by default to ensure that larger payloads, for instance, more complex filtering conditions can be passed via JWT. ThoughtSpot recommends leaving that compression on 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. However, if you want to decode the JWT token and decode the values of the token (at the expense of compression), contact ThoughtSpot Support. +==== + +=== Request format + +The ABAC request is sent using the `user_parameters` key of the +++V2.0 Full Access Token request+++. + +There are three potential keys within `user_parameters`, each taking an array of objects: +[code,javascript] +---- +... +"user_parameters": { + "runtime_filters": [], + "parameters" : [], + "runtime_sorts": [] +} +---- + +The format for the objects in each section follows the equivalent formats in the Visual Embed SDK for xref:runtime-filters.adoc[runtime filters], xref:runtime-parameters.adoc[runtime parameters], or xref:runtime-sort.adoc[runtime sorts]. + +There is a `xref:abac-user-parameters-beta.adoc#persistForUser[persist]` key to be added on each object that takes a boolean `true` or `false`. This determines if the values are persisted at the user level beyond just the token itself, for features such as alerts and subscriptions that run outside a user's session. + +The following is a `user_parameters` section that would be part of the JSON request of the +++V2.0 Full Access Token request+++: + +[source,JavaScript] +---- +"user_parameters": { + "runtime_filters": [ + { + "column_name": "Region", + "operator": "IN", + "values": ["West", "Southwest"], + "persist": false + }, + { + "column_name": "Product Type", + "operator": "IN", + "values": ["Shirts", "Swimwear"], + "persist": true + } + ], + "parameters": [ + { + "name": "Secured", + "values": ["rxzricmwfe87q7bh7jyg"], + "persist": true + } + ] + } +---- + +=== 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. + +You can choose the filter or parameter to apply only to specific ThoughtSpot objects by including an `objects` section with the following format: + +[source,JavaScript] +---- +"runtime_filters": [ + { + "column_name": "Region", + "operator": "IN", + "values": ["West", "Southwest"], + "persist": false + "objects": [ + { + // example of the format + "type": "{OBJECT_TYPE}", + "identifier": "{id or name of the object}" + }, + { + "type":"LIVEBOARD", + "identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125" + + } + ] +] +---- + +[#persistForUser] +=== Token-based override vs. persisting values +When `persist: false` is chosen for an ABAC attribute, it only acts as an *override*, with the values tied only to the specific token. + +You can treat the REST API *token request* with any values where `persist: true` as "update user_parameters" API endpoint, even if you don't use the token in the response. + +Filters and parameters must be *persisted* for them to apply when using xref:trusted-authentication.adoc#cookie[cookie-based trusted authentication] or scheduled reports. + +[cols="1,1,2"] +|===== +|persist|authentication type|behavior + +|`false` +|Cookieless Trusted Auth +|Token values override user's values, without updating user_parameters + +|`true` +|Cookieless Trusted Auth +|Token values override, but user_parameters is also updated by token request + +|`true` +|Cookie-based Trusted Auth +|Token request updates user_parameters, token is used by SDK to start a session + +|`true` +|Discard token after request +|Token request updates user_parameters + +|===== + +Remember, the successful *request* for a token updates the stored `user_parameters` property of the user, rather than the first use of the token. + +Persisting values opens up use cases for ABAC outside of the cookieless Trusted Authentication pattern: even if users authenticate via SAML, OIDC, or go directly into ThoughtSpot via username and password, an administrator can make a token request with `persist: true` to set their stored `user_parameters`. + +=== Remove persisted values +The syntax to fully remove persisted elements in a user's `user_parameters` property is to pass an *empty array* for the category. + +A request with an empty array affects persisted values despite there being no `persist` key within the request. + +The following would clear *all* persisted values of any type: +[code,javascript] +---- +"user_parameters": { + "runtime_filters": [], + "parameters" : [], + "runtime_sorts": [] +} +---- + +== Implement RLS with ABAC via tokens +The ABAC via tokens pattern allows for setting arbitrary filters and overriding the values of existing worksheet parameters. These two capabilities can be combined in a number of ways to create secure and unbreakable RLS. + +The current standard best practice pattern for RLS using ABAC via tokens is: + +1. Use parameters for any single-value items, with formulas and filters at the worksheet layer to create the desired filtering clauses on every query +2. Use runtime filters to define any *multi-value* filter conditions on columns (parameters are single-valued) +3. If using runtime filters, pass a *shared secret* to the worksheet as a 'check parameter'. This parameter will be used in a formula/filter combination at the Worksheet level to block unrestricted data access when no filters are set via the token +4. Edit the Worksheet TML, then add `is_hidden: true` to any parameter that will be set via token + +The ability to set the parameter to `is_hidden: true` allows the flexibility to use as many parameters as desired for any type of formula to be used as a worksheet filter. + +=== Show all +The way to set a runtime filter to *show all values* is to not send in any runtime filter at all for that column. + +Without additional information, it's impossible to know if the lack of a runtime filter is intentional to indicate a *show all values* condition or if something went wrong—a malformed ABAC token or the user entered into ThoughtSpot without a token at all. + +=== Check parameter and shared key +To make sure that no data shows when a properly-built token is not used to start the user session, you need to send a *"check parameter"* when using runtime filters. + +The *shared secret* is a string value used in both the *token request service* to generate each token, and within the *Worksheet formula* to evaluate the parameter. + +If the "check parameter" value from the token does not match the value defined in the Worksheet formula (the *shared secret*), the formula and filter combination blocks any data from showing for the user. + +=== Build the ABAC token request +The xref:trusted-auth-token-request-service.adoc[token request service] must have the following to build a token request for ABAC: + +1. The *shared secret* to go into the "check parameter" +2. Runtime filters for defining multi-value conditions on columns +3. Any additional parameters + +The runtime filters must be built by: + +1. Retrieving user data entitlements +2. Translating entitlements into ThoughSpot runtime filters + +==== Retrieve entitlements +The value of the ABAC pattern is that you can send different combinations of filters for different types of users. + +You can retrieve the attribute names and values from any source: the embedding application's session details, an entitlement REST API, a query to a different database, etc. + +==== Translate entitlements into runtime filters + +Runtime filters *match on the name property of a column* as defined in ThoughtSpot, not the column's name in the underlying database table. + +The xref:trusted-auth-token-request-service.adoc[token request service] *MUST* know the ThoughtSpot column names that will be used for each of the attributes, so you'll need to coordinate between ThoughtSpot Worksheet designers and the xref:trusted-auth-token-request-service.adoc[token request service] to make sure the matching column names and values are being sent. + +[IMPORTANT] +==== +[#dev-deploy-warning] +End users of an embedded app cannot have *edit* access to any worksheet using ABAC RLS via tokens. + +You must follow xref:development-and-deployment.adoc[proper development and deployment practices] for all your customer-facing production environments as well as the production token request service. +==== + +As mentioned in the preceding section, the format for runtime filters within the token match with xref:runtime-filters.adoc[runtime filters] in the Visual Embed SDK. In general, RLS entitlements are lists of values using the `IN` operator, but you can pass in filters on numeric and time columns using the full set of operators. + +All values are passed into the token as *arrays of strings*, even if the column is a numeric, boolean, or date type in ThoughtSpot and the database. The column data type will be respected in the query issued to the database. + +For example, let's assume three attributes that are needed to filter down a user on a multi-tenanted database: `Customer ID`, `Region`, and `Product Type`. + +The following is what the token request would look like if restricting on all three attributes: + +[source,JavaScript] +---- +"runtime_filters": [ + { + "column_name" : "Customer ID", + "operator": "EQ", + "values": ["492810"], + "persist" : true + }, + { + "column_name": "Region", + "operator": "IN", + "values": ["West", "Southwest"], + "persist": true + }, + { + "column_name": "Product Type", + "operator": "IN", + "values": ["Shirts", "Swimwear"], + "persist": true + } + ] +---- + +A user might be entitled to *all access* on any given column (you might drop some levels of a hierarchy if you include more granular columns to filter on for that user). + +[IMPORTANT] +==== +The process for translating the entitlements request into ThoughtSpot runtime filters must *drop* the filter definition entirely to represent *all access*. +==== + +The following is a request where a different user can see all `Region`, but still has restrictions on `Customer ID` and `Product Type`: +[code,javascript] +---- +"runtime_filters": [ + { + "column_name" : "Customer ID", + "operator": "EQ", + "values": ["492810"], + "persist" : true + }, + { + "column_name": "Product Type", + "operator": "IN", + "values": ["Shirts", "Swimwear"], + "persist": true + } + ] +---- + +Because the `runtime_filters` section is entirely within the control of the *token request service*, you have full flexibility to generate any set of filters for any type of user within the token. + +==== Set the 'check parameter' to the shared secret +The *shared secret* is just a long string value that cannot be easily guessed or determined programmatically. You can generate these values randomly and the end user will never see it, only the Worksheet editor if they look at the formula. + +Information about how to set up the appropriate set of Worksheet parameters, formulas, and filters for the 'check parameter' to provide security is provided in the following sections. + +All that is required within the token request service is that the same *shared secret* defined within the Worksheet formula is being sent with the appropriate 'check parameter' name. + +If the parameter is named `Secured` and the *shared secret* value is `rxzricmwfe87q7bh7jyg`, then the `parameters` section of the token request will look like the following snippet: + +[source,JavaScript] +---- +"parameters": [ + { + "name": "Secured", + "values": ["rxzricmwfe87q7bh7jyg"], + "persist": true + } +] +---- + +=== Use Parameters to filter a Worksheet +The basic pattern for using a Parameter to filter a Worksheet includes these steps: + +. Create link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Parameters, target=_blank] in Worksheet +. Make link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, target=_blank] that evaluates the Parameter's default value and the expected values from the token +. Make link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filter, target=_blank] based on the formula, set to *true*. + +link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Parameters, target=_blank] are defined at the Worksheet level within ThoughtSpot. Parameters have a data type and a default value set by the Worksheet author. + +To use a Parameter, you'll make a link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, target=_blank] on the Worksheet. + +link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filters, target=_blank] can reference Worksheet formulas once they have been created, which creates the security layer out of the result of the formula. + +All of these Worksheet-level features are set by clicking *Edit* on the Worksheet, then expanding the menu on the left sidebar: + +[.widthAuto] +image::./images/worksheet_edit_sidebar.png[Worksheet Edit Sidebar] + +==== Define the check parameter +The simplest 'check parameter' pattern is a shared key string that is stored in both the xref:trusted-auth-token-request-service.adoc[token request service] and the Worksheet formula used for the Worksheet filter. + +Parameters are always visible in the UI, even though a parameter set via a token can never be overridden by any action in the UI or using the Visual Embed SDK. + +Thus the 'check parameter' and its default value should be named something that looks pleasant to end users. For example, if the parameter name is "Secured", you can set the default value to "✔️" or "true" or "yes" (any Unicode value is allowed, including emojis): + +[.bordered] +[.widthAuto] +image::./images/check_parameter_definition.png[Check Parameter with Default Value for Display] + +This will display on Liveboards and Answers as shown here: + +[.bordered] +[.widthAuto] +image::./images/parameter_with_default.png[Parameter with Default Value on Answer] + +==== Create the Worksheet security formula +A Parameter doesn't do anything on its own. You need a formula to evaluate the Parameter's value. + +Any security formula to be used on a worksheet should result in a *boolean* true or false, and then the worksheet filter will be set to only return data when the formula returns true. + +===== Logic for groups to see all data +In any security formula you build, you may want a clause that gives access to all data to certain groups. + +You can chain together any number of `if...then...else` clauses within a formula, including using the `ts_groups` or `ts_username` values, to build out your preferred logic: + +`if ( 'data developers' in ts_groups ) then true else if ( parameter_name = field_name ) then true else false` + +===== Check parameter formulas +The simplest formula for a 'check parameter' with shared key looks as follows: + +`if ( check_parameter_name = 'shared-key-value') then true else false` + +For example, if the 'check parameter' is called `Secured`, and the secret key value is a long-encoded string like `rxzricmwfe87q7bh7jyg`, the Worksheet formula will be as shown in the following figure. Note that the Parameter name is always lower-cased in formulas: + +[.bordered] +[.widthAuto] +image::./images/worksheet_formula.png[Security Formula in Worksheet] + +===== Formulas comparing a parameter to a column +Parameters can be used in a formula to directly match a value in a column, or any other type of function you'd like to use: + +`if ( parameter_name = field_name ) then true else false` + +===== Use Parameters with pass-through functions +link:https://docs.thoughtspot.com/cloud/latest/formula-reference#passthrough-functions[ThoughtSpot SQL Pass-through functions, target=_blank] allow you to send arbitrary SQL to the data source, while passing in values to substitute from ThoughtSpot. + +The basic form of the SQL Pass-through function is: + +`sql_passthrough_function("", , ,...)` + +The list of variables after are substituted into the SQL statement using curly braces in the order listed, starting at 0: + +`sql_bool_op ( "tableName.columnName IN ({0}, {1})" , parameterName0, parameterName1)` + +If you are referencing a field NOT in ThoughtSpot, perhaps a column that is not part of the JOINed data model or of a complex data type ThoughtSpot does not natively recognize, you need to qualify the column with `tableName.columnName` syntax in your query, so that the SQL is not ambiguous if a similar column name exists on multiple tables. + +If you do not get all your data types correct, the ThoughtSpot-generated query will cause errors at the data warehouse level, which you will see in ThoughtSpot. + +==== Set a Worksheet filter on the Worksheet security formula +The last step is to set a *Worksheet filter* on the *formula* you just created to evaluate the 'check parameter'. + +The last step is to set a *Worksheet filter* on the *formula* you just created to evaluate the 'check parameter'. + +. Click the Add new icon (+) next to *Filters*. + +. Click the formula you created (at the end of the list) in the *Filter* dialog. ++ + +[.bordered] +image:./images/new_worksheet_filter_step_1.png[Create New Filter on Worksheet, width=449, height=589] ++ +. Click *Add values in bulk*. ++ +[.bordered] +image:./images/new_worksheet_filter_step_2.png[Choose add values in bulk, width=449, height=589] + +. Type in the value *true* in the bulk dialog box, and then click *Done*. ++ +[.bordered] +image:./images/new_worksheet_filter_step_3.png[Type in true in bulk values box, width=457, height=301] + +. Click **Done** on the Filter dialog. + +You should see it listed on the *Edit Worksheet* page: ++ +[.bordered] +image:./images/new_worksheet_filter_step_4.png[Completed Worksheet filter] + +Now the 'check parameter' will be evaluated all the time, blocking all data unless the appropriate value is passed in via ABAC token. + + +The last step is to set a *Worksheet filter* on the *formula* you just created to evaluate the 'check parameter'. + +. Click the Add new icon (+) next to *Filters*. + +. Click the formula you created (at the end of the list) in the *Filter* dialog. ++ + +[.bordered] +image:./images/new_worksheet_filter_step_1.png[Create New Filter on Worksheet, width=449, height=589] ++ +. Click *Add values in bulk*. ++ +[.bordered] +image:./images/new_worksheet_filter_step_2.png[Choose add values in bulk, width=449, height=589] + +. Type in the value *true* in the bulk dialog box, and then click *Done*. ++ +[.bordered] +image:./images/new_worksheet_filter_step_3.png[Type in true in bulk values box, width=457, height=301] + +. Click **Done** on the Filter dialog. + +You should see it listed on the *Edit Worksheet* page: ++ + +[.bordered] +image:./images/new_worksheet_filter_step_4.png[Completed Worksheet filter] + + + +== Indexing +Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in Explore, 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. + +== Known limitations + +* Schedules created with JWT using ABAC will not follow the same security rules as schedules created with standard RLS set up in ThoughtSpot. + +Schedules created by users in a session secured via RLS using ABAC currently do not follow any data security rules, that is, all data will be shown in schedules. ThoughtSpot recommends removing the ability to create schedules for your end users. The improvements in the upcoming versions include: +.. The security rules applied to the schedule will be those of the schedule creator +.. Using `persist:true` in the JWT for security rules will ensure that the schedule is run using the filter rules persisted on the user. +* Runtime filter conditions must match the column names in your worksheet to avoid data leakage. + ++ +The `runtime_filters` must include the exact ThoughtSpot worksheet column name, or they will not apply to the data set. If a worksheet is changed, you must coordinate between the team that maintains it and the team that builds the token request service, or the filters will no longer be applied. For the same reasons, the end users of an embedded app cannot have edit access to any worksheet using ABAC RLS via tokens. + ++ +Currently, the ABAC via tokens method requires using trusted authentication and using Worksheets as data sources for Liveboards and Answers, rather than individual Table objects. +You can pass in runtime filters and Parameters for a user via their login token. Both features work like the runtime filters and Parameters available within the Visual Embed SDK, but values set via token cannot be overridden by any user action within the ThoughtSpot UI. diff --git a/modules/ROOT/pages/abac-user-parameters.adoc b/modules/ROOT/pages/abac-user-parameters.adoc index 5b45cf355..bda1f1c2b 100644 --- a/modules/ROOT/pages/abac-user-parameters.adoc +++ b/modules/ROOT/pages/abac-user-parameters.adoc @@ -1,238 +1,238 @@ -= ABAC via tokens [beta betaBackground]^Beta^ += ABAC via tokens :toc: true :toclevels: 3 -:page-title: ABAC via token +:page-title: ABAC via tokens :page-pageid: abac-user-parameters :page-description: Attribute-based access control pattern can be achieved via user parameters sent in the login token -Attribute-Based Access Control (ABAC) is a pattern where security entitlements are sent in as lists of attributes at session creation time via the authentication service. +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 +++auth/token/custom+++ API endpoint. + +// This article describes the steps required to implement ABAC for row-level security (RLS) using the +++Custom access token +++ REST API endpoint. [IMPORTANT] ==== -[#beta-warning] -* RLS using ABAC via tokens is in __Beta__. As this feature directly impacts data security in your environment, ThoughtSpot does not support its use in a Production environment until it becomes Generally Available. ThoughtSpot is working on improvements in the upcoming releases that will change some of the best practices recommended in this article and result in the needed re-work of your deployment's security architecture. To understand the RLS best practices for your use case and deployment timelines, and to get these features enabled on your ThoughtSpot instances, contact ThoughtSpot Support. -* The ABAC via tokens method requires using link:https://docs.thoughtspot.com/cloud/latest/worksheet-create[Worksheets, target=_blank] or link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] as data sources for Liveboards and Answers, rather than individual table objects. - -* The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated in 10.4.0.cl. If your ThoughtSpot instance is on 10.4.0.cl or a later version, we recommend using the +++/api/rest/2.0/auth/token/custom+++ API endpoint to xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[generate JWT tokens with custom rules and user properties]. + -The examples in this page show `user_properties` available in the beta version of the ABAC implementation, which uses the `/api/rest/2.0/auth/token/full` API endpoint for token generation. If your instance is on 10.4.0.cl or a later version, you can start using the `/api/rest/2.0/auth/token/custom` API endpoint to xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[generate JWT tokens with custom rules and persist options]. + -To migrate your implementation from V2.0 Get token APIs (`/api/rest/2.0/auth/token/full` or `/api/rest/2.0/auth/token/object`) to `/api/rest/2.0/auth/token/custom` API workflow, 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]. ==== -== Overview +== ABAC attributes -The following attributes can be set for a user via the login token, along with the existing capability to assign ThoughtSpot groups: +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. -* xref:runtime-filters.adoc[Runtime filters] + -Can filter multiple values of any data type. Binds to any Column in any Data Source with a matching Column Name (ThoughtSpot property, not underlying database table column name). +Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups: -* xref:runtime-parameters.adoc[Parameters] + -Binds a single value to any Parameter in any Worksheet by Parameter Name and Type match. Parameters can be used in *worksheet formulas* and then as *worksheet filters*. -* xref:runtime-sort.adoc[Runtime sorts] (Applicable to 10.3.0.cl and earlier versions) + -Overrides to sort order within columns. +* xref:runtime-filters.adoc[Filter rules] + +Can filter multiple values of any data type. Binds to any Column in any Model or Worksheet with a matching column name in ThoughtSpot (and not the underlying database table column name). +* 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 runtime filters require passing the *exact* ThoughtSpot Worksheet or Model column name or will not apply to the data set. You must coordinate between the team that maintains the worksheets and the team that builds the token request service if any changes will be made to a worksheet, or the filters will no longer be applied. +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, end users of an embedded app cannot have *edit* access to any worksheet using ABAC RLS via tokens. +For the same reasons, end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens. ==== -The request for a token with ABAC details can xref:abac-user-parameters.adoc#persistForUser[persist] the set of filters and Parameter values to the user's `user_parameters` property, after which all sessions and scheduled reports will use the persisted values. +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 -The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format, using the existing ThoughtSpot V2.0 REST API access tokens, which are OAuth JWT tokens. - -The token can be used as a bearer token for cookieless Trusted Auth or REST API access, or as a sign-in token to create a ThoughtSpot session, in which case the ABAC user parameters should be *persisted*. +The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format. The token can be used as a bearer token for cookieless trusted authentication or REST API access, or as a sign-in token to create a ThoughtSpot session, in which case the ABAC user properties should be *persisted*. [NOTE] ==== -ThoughtSpot compresses the size of JWT token by default to ensure that larger payloads, for instance, more complex filtering conditions can be passed via JWT. ThoughtSpot recommends leaving that compression on 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. However, if you want to decode the JWT token and decode the values of the token (at the expense of compression), contact ThoughtSpot Support. +ThoughtSpot compresses the size of the JWT token by default to ensure that larger payloads, for instance, more complex filtering conditions can be passed via JWT. ThoughtSpot recommends leaving that compression on 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. However, if you want to decode the JWT token and decode the values of the token (at the expense of compression), contact ThoughtSpot Support. ==== === Request format +// UPDATE THIS TO REFLECT THE CUSTOM ENDPOINT -The ABAC request is sent using the `user_parameters` key of the link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-full-access-token[V2.0 Full Access Token request, target=_blank]. +The +++Custom access token +++ API provides the fields to define the various ABAC attributes within an access token request. -There are three potential keys within `user_parameters`, each taking an array of objects: -[code,javascript] ----- -... -"user_parameters": { - "runtime_filters": [], - "parameters" : [], - "runtime_sorts": [] -} ----- +The following properties of the Custom Access Token request are used for ABAC: -The format for the objects in each section follows the equivalent formats in the Visual Embed SDK for xref:runtime-filters.adoc[runtime filters], xref:runtime-parameters.adoc[runtime parameters], or xref:runtime-sort.adoc[runtime sorts]. +* `persist_option` +* `filter_rules` +* `parameter_values` +* `objects` -There is a `xref:abac-user-parameters.adoc#persistForUser[persist]` key to be added on each object that takes a boolean `true` or `false`. This determines if the values are persisted at the user level beyond just the token itself, for features such as alerts and subscriptions that run outside a user's session. +The format for the objects in each section follows the equivalent formats in the Visual Embed SDK for xref:runtime-filters.adoc[runtime filters] and xref:runtime-parameters.adoc[runtime Parameters]. -The following is a `user_parameters` section that would be part of the JSON request of the link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-full-access-token[V2.0 Full Access Token request, target=_blank]: +An example of setting both `filter_rules` and `parameter_values` without any persistence: [source,JavaScript] ---- -"user_parameters": { - "runtime_filters": [ - { - "column_name": "Region", - "operator": "IN", - "values": ["West", "Southwest"], - "persist": false - }, - { - "column_name": "Product Type", - "operator": "IN", - "values": ["Shirts", "Swimwear"], - "persist": true - } - ], - "parameters": [ - { - "name": "Secured", - "values": ["rxzricmwfe87q7bh7jyg"], - "persist": true - } - ] - } +"persist_option": "NONE", +"filter_rules": [ + { + "column_name": "Region", + "operator": "IN", + "values": ["West", "Southwest"] + }, + { + "column_name": "Product Type", + "operator": "IN", + "values": ["Shirts", "Swimwear"] + } + ], + "parameter_values": [ + { + "name": "Secured", + "values": ["rxzricmwfe87q7bh7jyg"] + } + ] ---- === 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. +By default, any specified filter or parameter will bind to *any content* with an exact match for the column or Parameter name. -You can choose the filter or parameter to apply only to specific ThoughtSpot objects by including an `objects` section with the following format: +You can choose the filter or Parameter to apply only to specific ThoughtSpot objects by including an `objects` array in the following format: [source,JavaScript] ---- -"runtime_filters": [ +"objects": [ { - "column_name": "Region", - "operator": "IN", - "values": ["West", "Southwest"], - "persist": false - "objects": [ - { - // example of the format - "type": "{OBJECT_TYPE}", - "identifier": "{id or name of the object}" - }, - { - "type":"LIVEBOARD", - "identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125" - - } - ] + // example of the format + "type": "{OBJECT_TYPE}", + "identifier": "{id or name of the object}" + }, + { + "type":"LIVEBOARD", + "identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125" + + } ] ---- [#persistForUser] -=== Token-based override vs. persisting values -When `persist: false` is chosen for an ABAC attribute, it only acts as an *override*, with the values tied only to the specific token. +=== Token-based override versus persisting values +When using a `persist_option` other than `NONE`, the *filter_rules* and *parameter_values* defined in the token request using the `auth/token/custom` API endpoint are stored in the `user` > `access_control_properties` object. -You can treat the REST API *token request* with any values where `persist: true` as "update user_parameters" API endpoint, even if you don't use the token in the response. +Persisted values for a user are used by ThoughtSpot for any scheduled reports, as well as when no other token is provided. -Filters and parameters must be *persisted* for them to apply when using xref:trusted-authentication.adoc#cookie[cookie-based trusted authentication] or scheduled reports. +The `persist_option` has the following possible values : [cols="1,1,2"] +[options='header'] |===== -|persist|authentication type|behavior +|value|available version|behavior -|`false` -|Cookieless Trusted Auth -|Token values override user's values, without updating user_parameters +|`NONE` +|10.4.0.cl and later +|User properties are not updated by the token request. -|`true` -|Cookieless Trusted Auth -|Token values override, but user_parameters is also updated by token request +|`APPEND` +|10.4.0.cl and later +|New attributes in the token request are added to existing properties of the user object. -|`true` -|Cookie-based Trusted Auth -|Token request updates user_parameters, token is used by SDK to start a session +|`RESET` +|10.4.0.cl and later +|All persisted attributes on the user object are cleared. New attributes defined in the API request are still encoded in the token. -|`true` -|Discard token after request -|Token request updates user_parameters +|`REPLACE` +|10.5.0.cl and later +a|All persisted rules and attributes of the user object are replaced with the set specified in the token request. +[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. +==== |===== -Remember, the successful *request* for a token updates the stored `user_parameters` property of the user, rather than the first use of the token. +When `persist_option` is set to `NONE`, it only acts as an *override*, with the values tied only to the specific token. The REST API token request with any values where `persist_option` is not `NONE` acts as an "update the user object" API endpoint, even if you don't use the token generated from the API request. -Persisting values opens up use cases for ABAC outside of the cookieless Trusted Authentication pattern: even if users authenticate via SAML, OIDC, or go directly into ThoughtSpot via username and password, an administrator can make a token request with `persist: true` to set their stored `user_parameters`. +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. -=== Remove persisted values -The syntax to fully remove persisted elements in a user's `user_parameters` property is to pass an *empty array* for the category. +[cols="1,1,2"] +|===== +|persist|authentication type|behavior -A request with an empty array affects persisted values despite there being no `persist` key within the request. +|`NONE` +|Cookieless Trusted Authentication +|Attributes assigned to the token override the user's access control properties, without updating the user object. -The following would clear *all* persisted values of any type: -[code,javascript] ----- -"user_parameters": { - "runtime_filters": [], - "parameters" : [], - "runtime_sorts": [] -} ----- +|`APPEND` or `REPLACE` +|Cookieless Trusted Authentication +|Attributes assigned to the token override the user's access control properties, but the user object is also updated -== Implement RLS with ABAC via tokens -The ABAC via tokens pattern allows for setting arbitrary filters and overriding the values of existing worksheet parameters. These two capabilities can be combined in a number of ways to create secure and unbreakable RLS. +|`APPEND` or `REPLACE` +|Cookie-based Trusted Authentication +|Token request updates the user's access control properties and the token is used by the Visual Embed SDK to start a session. -The current standard best practice pattern for RLS using ABAC via tokens is: +|`APPEND` or `REPLACE` +|Discard token after request +|Token request updates the user object. +|===== + +Note that the successful *request* for a token updates the stored property of the user, rather than the first use of the token. + +Persisting values opens up use cases for ABAC outside of the cookieless Trusted Authentication pattern: even if users authenticate via SAML, OIDC, or go directly into ThoughtSpot via username and password, an administrator can make a token request with a `persist_option` to write `filter_rules` and `parameter_values` to the user object. + +=== Reset persisted values +To fully remove all persisted `filter_rules` or `parameter_values` from a user object, set `"persist_option" : "RESET"` in the token request. + +The requested token can still be used for ABAC if you included `filter_rules` or `parameter_values` in the request. -1. Use parameters for any single-value items, with formulas and filters at the worksheet layer to create the desired filtering clauses on every query -2. Use runtime filters to define any *multi-value* filter conditions on columns (parameters are single-valued) -3. If using runtime filters, pass a *shared secret* to the worksheet as a 'check parameter'. This parameter will be used in a formula/filter combination at the Worksheet level to block unrestricted data access when no filters are set via the token -4. Edit the Worksheet TML, then add `is_hidden: true` to any parameter that will be set via token +=== Token request test page +A downloadable, customizable web page for testing all of the ABAC and trusted authentication capabilities is link:https://github.com/thoughtspot/ts_everywhere_resources/tree/master/examples/abac_with_token_auth[available on GitHub^]. -The ability to set the parameter to `is_hidden: true` allows the flexibility to use as many parameters as desired for any type of formula to be used as a worksheet filter. +The username specified in the test page must have Administrator privilege or you can supply the *secret_key* for the ThoughtSpot instance to request a token for any user along with setting their ABAC properties. -=== Show all -The way to set a runtime filter to *show all values* is to not send in any runtime filter at all for that column. +See the xref:trusted-authentication.adoc[trusted authentication] documentation for full details on proper setup to allow trusted authentication. -Without additional information, it's impossible to know if the lack of a runtime filter is intentional to indicate a *show all values* condition or if something went wrong—a malformed ABAC token or the user entered into ThoughtSpot without a token at all. +== Filter rules for multi-value RLS +The ABAC via tokens pattern allows for setting arbitrary filters and overriding the values of existing Worksheet parameters. These two capabilities can be combined in various ways to create secure and unbreakable RLS. -=== Check parameter and shared key -To make sure that no data shows when a properly-built token is not used to start the user session, you need to send a *"check parameter"* when using runtime filters. +=== Deny all by default +Starting in ThoughtSpot 10.4.0.cl, you can add `is_mandatory_token_filter: true` to the TML definition of any column in a Worksheet or Model. -The *shared secret* is a string value used in both the *token request service* to generate each token, and within the *Worksheet formula* to evaluate the parameter. +ThoughtSpot checks to see if the logged-in user has any `filter_rules` defined for a column marked with `is_mandatory_filter: true`, and denies access to any data if a filter rule for the matching column is not found. -If the "check parameter" value from the token does not match the value defined in the Worksheet formula (the *shared secret*), the formula and filter combination blocks any data from showing for the user. +=== Show All +The way to show all values for a column protected by `is_mandatory_token_filter: true` is to pass the special keyword `["TS_WILDCARD_ALL"]` as the value for the column in the `filter_rules`. + +Columns without `is_mandatory_token_filter: true` will show all values if there is no `filter_rule` for that column. === Build the ABAC token request The xref:trusted-auth-token-request-service.adoc[token request service] must have the following to build a token request for ABAC: -1. The *shared secret* to go into the "check parameter" -2. Runtime filters for defining multi-value conditions on columns -3. Any additional parameters +1. Filter rules for defining multi-value conditions on columns +2. Parameter values for use in Worksheet or Model formulas -The runtime filters must be built by: +The filter rules must be built by: 1. Retrieving user data entitlements -2. Translating entitlements into ThoughSpot runtime filters +2. Translating entitlements into ThoughSpot `filter_rules` ==== Retrieve entitlements The value of the ABAC pattern is that you can send different combinations of filters for different types of users. You can retrieve the attribute names and values from any source: the embedding application's session details, an entitlement REST API, a query to a different database, etc. -==== Translate entitlements into runtime filters +==== Translate entitlements into filter rules -Runtime filters *match on the name property of a column* as defined in ThoughtSpot, not the column's name in the underlying database table. +Filter rules *match on the name property of a column* as defined in ThoughtSpot, not the column's name in the underlying database table. The xref:trusted-auth-token-request-service.adoc[token request service] *MUST* know the ThoughtSpot column names that will be used for each of the attributes, so you'll need to coordinate between ThoughtSpot Worksheet designers and the xref:trusted-auth-token-request-service.adoc[token request service] to make sure the matching column names and values are being sent. [IMPORTANT] ==== [#dev-deploy-warning] -End users of an embedded app cannot have *edit* access to any worksheet using ABAC RLS via tokens. +End users of an embedded app cannot have *edit* access to any Worksheet using ABAC RLS via tokens. You must follow xref:development-and-deployment.adoc[proper development and deployment practices] for all your customer-facing production environments as well as the production token request service. ==== -As mentioned in the preceding section, the format for runtime filters within the token match with xref:runtime-filters.adoc[runtime filters] in the Visual Embed SDK. In general, RLS entitlements are lists of values using the `IN` operator, but you can pass in filters on numeric and time columns using the full set of operators. +As mentioned in the preceding section, the format for filter rules within the token matches with xref:runtime-filters.adoc[runtime filters] in the Visual Embed SDK. In general, RLS entitlements are lists of values using the `IN` operator, but you can pass in filters on numeric and time columns using the full set of operators. All values are passed into the token as *arrays of strings*, even if the column is a numeric, boolean, or date type in ThoughtSpot and the database. The column data type will be respected in the query issued to the database. @@ -242,115 +242,75 @@ The following is what the token request would look like if restricting on all th [source,JavaScript] ---- -"runtime_filters": [ +"filter_rules": [ { "column_name" : "Customer ID", "operator": "EQ", - "values": ["492810"], - "persist" : true + "values": ["492810"] }, { "column_name": "Region", "operator": "IN", - "values": ["West", "Southwest"], - "persist": true + "values": ["West", "Southwest"] }, { "column_name": "Product Type", "operator": "IN", - "values": ["Shirts", "Swimwear"], - "persist": true + "values": ["Shirts", "Swimwear"] } ] ---- A user might be entitled to *all access* on any given column (you might drop some levels of a hierarchy if you include more granular columns to filter on for that user). -[IMPORTANT] -==== -The process for translating the entitlements request into ThoughtSpot runtime filters must *drop* the filter definition entirely to represent *all access*. -==== +The following is a request where a different user can see all `Region`, but still has restrictions on `Customer ID` and `Product Type`, using the `TS_WILDCARD_ALL` value to allow data even when the column expects a filter from the token: -The following is a request where a different user can see all `Region`, but still has restrictions on `Customer ID` and `Product Type`: -[code,javascript] +[source,javascript] ---- -"runtime_filters": [ +"filter_rules": [ + { + "column_name" : "Customer ID", + "operator": "EQ", + "values": ["TS_WILDCARD_ALL"] + }, { "column_name" : "Customer ID", "operator": "EQ", "values": ["492810"], - "persist" : true }, { "column_name": "Product Type", "operator": "IN", "values": ["Shirts", "Swimwear"], - "persist": true } ] ---- -Because the `runtime_filters` section is entirely within the control of the *token request service*, you have full flexibility to generate any set of filters for any type of user within the token. - -==== Set the 'check parameter' to the shared secret -The *shared secret* is just a long string value that cannot be easily guessed or determined programmatically. You can generate these values randomly and the end user will never see it, only the Worksheet editor if they look at the formula. - -Information about how to set up the appropriate set of Worksheet parameters, formulas, and filters for the 'check parameter' to provide security is provided in the following sections. - -All that is required within the token request service is that the same *shared secret* defined within the Worksheet formula is being sent with the appropriate 'check parameter' name. - -If the parameter is named `Secured` and the *shared secret* value is `rxzricmwfe87q7bh7jyg`, then the `parameters` section of the token request will look like the following snippet: - -[source,JavaScript] ----- -"parameters": [ - { - "name": "Secured", - "values": ["rxzricmwfe87q7bh7jyg"], - "persist": true - } -] ----- +Because the `filter_rules` section is entirely within the control of the *token request service*, you have full flexibility to generate any set of filters for any type of user within the token. -=== Use Parameters to filter a Worksheet -The basic pattern for using a Parameter to filter a Worksheet includes these steps: +== Parameters to filter via formulas +The basic pattern for using a Parameter to filter a Worksheet or Model includes these steps: -. Create link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Parameters, target=_blank] in Worksheet -. Make link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, target=_blank] that evaluates the Parameter's default value and the expected values from the token -. Make link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filter, target=_blank] based on the formula, set to *true*. +. Create link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Parameters, window=_blank] in Worksheet +. Make link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, window=_blank] that evaluates the Parameter's default value and the expected values from the token +. Make link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filter, window=_blank] based on the formula, set to `true`. link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Parameters, target=_blank] are defined at the Worksheet level within ThoughtSpot. Parameters have a data type and a default value set by the Worksheet author. -To use a Parameter, you'll make a link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, target=_blank] on the Worksheet. +You can also add `is_hidden: true` to a Parameter definition using TML, which allows the flexibility to use as many parameters as desired for any type of formula to be used as a Worksheet filter, without cluttering the visible UI. -link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filters, target=_blank] can reference Worksheet formulas once they have been created, which creates the security layer out of the result of the formula. +To use a Parameter, you'll create a link:https://docs.thoughtspot.com/cloud/latest/formulas[formula, window=_blank] on the Worksheet or Model. link:https://docs.thoughtspot.com/cloud/latest/filters#_worksheet_filters[Worksheet filters, window=_blank] can reference Worksheet formulas once they have been created, which creates the security layer out of the result derived from the formula. All of these Worksheet-level features are set by clicking *Edit* on the Worksheet, then expanding the menu on the left sidebar: -[.widthAuto] -image::./images/worksheet_edit_sidebar.png[Worksheet Edit Sidebar] - -==== Define the check parameter -The simplest 'check parameter' pattern is a shared key string that is stored in both the xref:trusted-auth-token-request-service.adoc[token request service] and the Worksheet formula used for the Worksheet filter. - -Parameters are always visible in the UI, even though a parameter set via a token can never be overridden by any action in the UI or using the Visual Embed SDK. - -Thus the 'check parameter' and its default value should be named something that looks pleasant to end users. For example, if the parameter name is "Secured", you can set the default value to "✔️" or "true" or "yes" (any Unicode value is allowed, including emojis): - [.bordered] [.widthAuto] -image::./images/check_parameter_definition.png[Check Parameter with Default Value for Display] - -This will display on Liveboards and Answers as shown here: - -[.bordered] -[.widthAuto] -image::./images/parameter_with_default.png[Parameter with Default Value on Answer] +image:./images/worksheet_edit_sidebar.png[Worksheet Edit Sidebar] ==== Create the Worksheet security formula A Parameter doesn't do anything on its own. You need a formula to evaluate the Parameter's value. -Any security formula to be used on a worksheet should result in a *boolean* true or false, and then the worksheet filter will be set to only return data when the formula returns true. +Any security formula to be used on a Worksheet should result in a *boolean* true or false, and then the Worksheet filter will be set to only return data when the formula returns true. ===== Logic for groups to see all data In any security formula you build, you may want a clause that gives access to all data to certain groups. @@ -359,24 +319,13 @@ You can chain together any number of `if...then...else` clauses within a formula `if ( 'data developers' in ts_groups ) then true else if ( parameter_name = field_name ) then true else false` -===== Check parameter formulas -The simplest formula for a 'check parameter' with shared key looks as follows: - -`if ( check_parameter_name = 'shared-key-value') then true else false` - -For example, if the 'check parameter' is called `Secured`, and the secret key value is a long-encoded string like `rxzricmwfe87q7bh7jyg`, the Worksheet formula will be as shown in the following figure. Note that the Parameter name is always lower-cased in formulas: - -[.bordered] -[.widthAuto] -image::./images/worksheet_formula.png[Security Formula in Worksheet] - ===== Formulas comparing a parameter to a column Parameters can be used in a formula to directly match a value in a column, or any other type of function you'd like to use: `if ( parameter_name = field_name ) then true else false` ===== Use Parameters with pass-through functions -link:https://docs.thoughtspot.com/cloud/latest/formula-reference#passthrough-functions[ThoughtSpot SQL Pass-through functions, target=_blank] allow you to send arbitrary SQL to the data source, while passing in values to substitute from ThoughtSpot. +link:https://docs.thoughtspot.com/cloud/latest/formula-reference#passthrough-functions[ThoughtSpot SQL Pass-through functions, window=_blank] allow you to send arbitrary SQL to the data source, while passing in values to substitute from ThoughtSpot. The basic form of the SQL Pass-through function is: @@ -393,48 +342,46 @@ If you do not get all your data types correct, the ThoughtSpot-generated query w ==== Set a Worksheet filter on the Worksheet security formula The last step is to set a *Worksheet filter* on the *formula* you just created to evaluate the 'check parameter'. -Click the Add new icon (+) next to Filters, and choose the formula you created (at the end of the list): +. Click the Add new icon (+) next to *Filters*. + +. Click the formula you created (at the end of the list) in the *Filter* dialog. ++ [.bordered] -[.widthAuto] -image::./images/new_worksheet_filter_step_1.png[Create New Filter on Worksheet] - -At the bottom of the filter dialog that appears, choose "Add values in bulk": +image:./images/new_worksheet_filter_step_1.png[Create New Filter on Worksheet, width=449, height=589] ++ +. Click *Add values in bulk*. ++ [.bordered] -[.widthAuto] -image::./images/new_worksheet_filter_step_2.png[Choose add values in bulk] - -Type in the value *true* in the bulk dialog box, then press "Done": +image:./images/new_worksheet_filter_step_2.png[Choose add values in bulk, width=449, height=589] +. Type in the value *true* in the bulk dialog box, and then click *Done*. ++ [.bordered] -[.widthAuto] -image::./images/new_worksheet_filter_step_3.png[Type in true in bulk values box] +image:./images/new_worksheet_filter_step_3.png[Type in true in bulk values box, width=457, height=301] -Once you click **Done** on the filter dialog, you should see it listed on the Edit Worksheet page: +. Click **Done** on the Filter dialog. + +You should see it listed on the *Edit Worksheet* page: ++ [.bordered] -[.widthAuto] -image::./images/new_worksheet_filter_step_4.png[Completed Worksheet filter] +image:./images/new_worksheet_filter_step_4.png[Completed Worksheet filter] -Now the 'check parameter' will be evaluated all the time, blocking all data unless the appropriate value is passed in via ABAC token. - -== Indexing -Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in Explore, use ThoughtSpot indexing. +== Known limitations +* The ABAC via tokens method requires using trusted authentication and using Worksheets or Models as data sources for Liveboards and Answers, rather than individual Table objects. -Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. +* 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. -You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS. -== Known limitations +// * Schedules created with JWT using ABAC will not follow the same security rules as schedules created with standard RLS set up in ThoughtSpot. + +// Schedules created by users in a session secured via RLS using ABAC currently do not follow any data security rules, that is, all data will be shown in schedules. ThoughtSpot recommends removing the ability to create schedules for your end users. The improvements in the upcoming versions include: +// .. The security rules applied to the schedule will be those of the schedule creator +// .. Using `persist:true` in the JWT for security rules will ensure that the schedule is run using the filter rules persisted on the user. +//* Runtime filter conditions must match the column names in your worksheet to avoid data leakage. -* Schedules created with JWT using ABAC will not follow the same security rules as schedules created with standard RLS set up in ThoughtSpot. + -Schedules created by users in a session secured via RLS using ABAC currently do not follow any data security rules, that is, all data will be shown in schedules. ThoughtSpot recommends removing the ability to create schedules for your end users. The improvements in the upcoming versions include: -.. The security rules applied to the schedule will be those of the schedule creator -.. Using `persist:true` in the JWT for security rules will ensure that the schedule is run using the filter rules persisted on the user. -* Runtime filter conditions must match the column names in your worksheet to avoid data leakage. +//+ +//The `runtime_filters` must include the exact ThoughtSpot worksheet column name, or they will not apply to the data set. If a worksheet is changed, you must coordinate between the team that maintains it and the team that builds the token request service, or the filters will no longer be applied. For the same reasons, the end users of an embedded app cannot have edit access to any worksheet using ABAC RLS via tokens. + +// + -+ -The `runtime_filters` must include the exact ThoughtSpot worksheet column name, or they will not apply to the data set. If a worksheet is changed, you must coordinate between the team that maintains it and the team that builds the token request service, or the filters will no longer be applied. For the same reasons, the end users of an embedded app cannot have edit access to any worksheet using ABAC RLS via tokens. + -+ -Currently, the ABAC via tokens method requires using trusted authentication and using Worksheets as data sources for Liveboards and Answers, rather than individual Table objects. -You can pass in runtime filters and Parameters for a user via their login token. Both features work like the runtime filters and Parameters available within the Visual Embed SDK, but values set via token cannot be overridden by any user action within the ThoughtSpot UI. +// You can pass in runtime filters and Parameters for a user via their login token. Both features work like the runtime filters and Parameters available within the Visual Embed SDK, but values set via token cannot be overridden by any user action within the ThoughtSpot UI. diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 67e77180a..e712eae5e 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,21 @@ 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.35.0, December 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: + +* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface +* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. + +For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|==== + == Version 1.34.0, November 2024 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 364aef4e7..609497a59 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -446,7 +446,7 @@ Invalid parameter === Just-in-time provisioning -If the `username` does not exist in the ThoughtSpot system, you can provision a new user and assign privileges using `auto_create` and `group_identifiers` attributes. For just-in-time provisioning, include the following attributes along with `username` and `secret_key` in the `POST` request body: +If the `username` does not exist in the ThoughtSpot system, you can provision a new user and assign privileges using `auto_create` and `group_identifiers` attributes. For xref:just-in-time-provisioning.adoc[Just-in-time provisioning], include the following attributes along with `username` and `secret_key` in the `POST` request body: [width="100%" cols="1,4"] [options='header'] @@ -514,19 +514,24 @@ curl -X POST \ }' ---- -For more information, see xref:just-in-time-provisioning.adoc[Just-in-time provisioning]. - -=== Get tokens with custom rules and filter conditions +[NOTE] +==== +The `auth/token/custom` API endpoint also allows you to automatically create a user during token generation. For more information, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get a token with custom rules and filter conditions for ABAC implementation]. +==== -To get tokens encoded in JSON Web Token (JWT) format with security entitlements for a user, send a `POST` request with the user details, filter rules, and parameter values to the `/api/rest/2.0/auth/token/custom` API endpoint. This API allows administrators to generate a token with a specific set of rules and column filtering conditions that are applied when a user session is initiated. +[#_get_tokens_with_custom_rules_and_filter_conditions] +=== Get a token with custom rules and filter conditions for ABAC implementation -You can also use this API with the Visual Embed SDK to implement Attribute-Based Access Control (ABAC) for your embedding application users. +To get a token with security entitlements encoded in JSON Web Token (JWT) format for a user, send a `POST` request with the user details, filter rules, and parameter values to the `/api/rest/2.0/auth/token/custom` API endpoint. This API allows administrators to generate a token with a specific set of rules and column filtering conditions that are applied when a user session is created. [NOTE] ==== -If your ThoughtSpot instance is on 10.4.0.cl or later, ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` to generate Attribute-Based Access (ABAC) Control tokens. The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated in 10.4.0.cl and is not recommended for ABAC token generation. +If your application instance is upgraded 10.4.0.cl or a later version, ThoughtSpot recommends using the +++/api/rest/2.0/auth/token/custom+++ API endpoint to generate a JWT token with custom security rules for Attribute-Based Access Control (ABAC) implementation. + +The `user_parameters` property used for generating an ABAC token via `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints in the beta implementation is deprecated in 10.4.0.cl. + +If your current implementation is using the beta version of the ABAC and you want to migrate your beta ABAC implementation to `/api/rest/2.0/auth/token/custom`, refer to the instructions in xref:jwt-migration.adoc[ABAC migration guide]. ==== + [width="100%" cols="1,4"] [options='header'] |===== @@ -540,20 +545,20 @@ a|__String__. Password of the user account. If using `secret_key` to generate th |`validity_time_in_sec` + __Optional__| __Integer__. Token expiry duration in seconds. The default duration is 300 seconds. |`org_id` + -__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If Org ID is not specified, the token is generated for the Primary Org (Org 0). +__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If an Org ID is not specified, the token is generated for the Primary Org (Org 0). |`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’s 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. * `REPLACE` + -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 attributes defined in this API request. * `RESET` + -Resets `user_properties` assigned to a user upon token generation. +Resets the user properties assigned to a user upon token generation. |`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: @@ -614,8 +619,8 @@ __Optional__ |__String__. Email address of the user. Use this parameter to add t |`display_name` + __Optional__ |__String__. Display name of the user. Use this parameter if `auto_create` is set to `true. |`auto_create` + -__Optional__|__Boolean__. Creates a user if the specified username is not already available in ThoughtSpot. The default value is `true`. -|`group_identifiers` + +__Optional__|__Boolean__. Available from 10.5.0.cl. Creates a user if the specified username is not already available in ThoughtSpot. The default value is `true`. +|`groups` + __Optional__|__Array of Strings__. GUIDs or names of the groups to assign the user to. This attribute can be used in conjunction with `auto_create` to dynamically assign groups and privileges to a user. |===== @@ -669,7 +674,7 @@ curl -X POST \ "identifier": "a71d5d1f-6e02-4ee1-a6e9-e158af844367" } ], - "org_identifier": "2", + "org_identifier": "0", "secret_key": "4c55ff63-d03e-497a-8ec6-1be083f160ee" }' ---- @@ -677,6 +682,23 @@ curl -X POST \ ==== API response If API request is successful, the API returns a token with the security rules and attributes applied. +[source,JSON] +---- +{ + "id": "3eefc15a-cad0-4de0-a85c-de6407a14fca", + "token": "{AUTH_TOKEN}", + "org": { + "id": 0, + "name": "Primary" + }, + "user": { + "id": "46228fb2-8db9-4b84-b015-82ea2f3b220d", + "name": "UserA" + }, + "creation_time_in_millis": 1733323274948, + "expiration_time_in_millis": 1733323574708 +} +---- ===== Response codes diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index e396eaee0..93b89a2c9 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -126,7 +126,9 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/access-control-sharing[Access control and sharing] *** link:{{navprefix}}/privileges-and-roles[Privileges and Roles] *** link:{{navprefix}}/data-security[Data security] -**** link:{{navprefix}}/abac-user-parameters[ABAC via tokens ^BETA^] +**** link:{{navprefix}}/abac-user-parameters[ABAC via tokens] +**** link:{{navprefix}}/abac-migration-guide[Migrate ABAC ^BETA^ implementation to custom token API] +**** link:{{navprefix}}/abac-user-parameters-beta[ABAC via tokens (pre-10.4.0.cl)] **** link:{{navprefix}}/rls-rules[RLS Rules] *** link:{{navprefix}}/selective-user-access[User access] ** link:{{navprefix}}/best-practices[Optimize app performance] diff --git a/modules/ROOT/pages/customize-links.adoc b/modules/ROOT/pages/customize-links.adoc index 5cdd981f0..384a48ac9 100644 --- a/modules/ROOT/pages/customize-links.adoc +++ b/modules/ROOT/pages/customize-links.adoc @@ -23,6 +23,7 @@ An Answer link is generated when a user shares an Answer with another user and i SpotIQ analyses links:: ThoughtSpot generates this link when a user runs the SpotIQ analysis on the data generated from a search query, saved Answer, or a visualization pinned to a Liveboard. This link points users to the *SpotIQ Analyses* page and is also sent in email notifications. + Links to unsubscribe from notifications:: + The *Unsubscribe* link is included in system-generated emails to allow users to turn off email notifications. @@ -80,6 +81,8 @@ For example, when a user subscribes to receive threshold-based alerts for a KPI ==== * Make sure the {object-id} and {sub-object-id} variables are used only for ThoughtSpot objects. If the link format has two {object-id} variables, your application users may not receive the correct links. For example, if the link format is `\https://www.mysite.com/?myobject-id={object-id}/liveboard-id={object-id}`, ThoughtSpot may replace both these variables with the Liveboard GUID when it generates the Liveboard link. + * ThoughtSpot query parameters that substitute the `{ts-query-params}` variable are prefixed with `ts-`. +* If xref:orgs.adoc[per Org custom embed URL feature] is enabled on your ThoughtSpot instance, the Org ID is also passed as a query parameter in the `{ts-query-params}`. +* The developers are advised to update their implementation to accommodate the Org ID in the `{ts-query-params}` while setting up the custom links for their application users, and avoid any workflow disruption. ==== == Customize link format @@ -175,6 +178,8 @@ https://www.mysite.com/insight/{object-id} ---- https://www.mysite.com/?insights={object-id} ---- + + Unsubscribe link:: This URL provides a link to the *Profile* settings page in ThoughtSpot. @@ -238,7 +243,20 @@ To verify if the links are generated in the format you configured, share a Liveb For example, if you customized the hostname in the URL as `www.mysite.com`, ThoughtSpot generates links with the `www.mysite.com` hostname. * If you are using a non-embedded ThoughtSpot instance and the Liveboard or Answer sharing URL format is customized, ThoughtSpot displays the *Embedded link format* checkbox. To copy the URL in the customized format, click *Embedded link format*. ++ +[NOTE] +==== +If the per Org custom embed URL feature is enabled on your ThoughtSpot instance, this URL in the *Embedded link format* will also show the Org ID. +For example if you have defined the custom link as, + +`\https://www.mysite.com/liveboard/{object-id}/?{ts-query-params}` +The *Embedded link format* will be, + +`\https://www.mysite.com/liveboard/22946f4b-b4ce-4643-be50-66afcd5177/orgId=0` + +The Org ID will passed in the URL depending on the placement of `{ts-query-params}` in the custom link settings. +==== + [.bordered] [.widthAuto] @@ -253,7 +271,10 @@ image::./images/embed-link-liveboardSchedule.png[Embed link format] * Verify the `Unsubscribe` links in email notifications. + + //// == Limitations Currently, ThoughtSpot does not support customizing the **View Liveboard** URL in Liveboard schedule notifications. +//// diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index f109819ae..4969c82a3 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -198,6 +198,11 @@ In the `POST` request body, specify the GUID or name of the Liveboard as `metada The default `file_format` is CSV. For PDF and PNG file format, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. For PNG file format, you can include cover page and filters. +[NOTE] +==== +The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +==== + .**Example** [source,cURL] ---- @@ -276,6 +281,12 @@ curl -X POST \ }' ---- +[NOTE] +==== +* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +* HTML rendering is not supported for PDF exports of Answers with tables. +==== + == Pagination settings for Data and Report APIs When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: diff --git a/modules/ROOT/pages/embed-authentication.adoc b/modules/ROOT/pages/embed-authentication.adoc index 54b29d61e..cf9f4de3b 100644 --- a/modules/ROOT/pages/embed-authentication.adoc +++ b/modules/ROOT/pages/embed-authentication.adoc @@ -14,27 +14,24 @@ This section describes the authentication methods supported in the SDK and when The following figure shows the authentication methods best suited for production use cases: -image:./images/auth-type-embed.svg[Embed authentication types] +[.widthAuto] +image:./images/auth-type-embed.png[Embed authentication types] The following table lists the general recommendations for choosing an authentication method to authenticate embedded application users. [width="100%" cols="4,4,6,6"] [options='header'] |===== -|Authentication type|AuthType in SDK|When to use|Not recommended -|xref:embed-authentication.adoc#embedSSO[Embedded SSO authentication] (Recommended) |`AuthType.EmbeddedSSO` a| Use this method: + +|Authentication type|AuthType in SDK|When to use|Not recommended scenarios -* If your application is already using a SAML IdP or OpenID provider that allows iframe redirects. -* If your ThoughtSpot instance has SAML or OIDC authentication support configured. -* To seamlessly redirect your users to their IdP within the embedded iframe for authentication. - -a|ThoughtSpot does not recommend using Embedded SSO authentication in the following scenarios: + +.2+|xref:embed-authentication.adoc#trusted-auth-embed[Trusted authentication] -* If you are using multiple IdPs for user authentication. + -* If you cannot configure your IdP to allow iframe redirect. + +|`AuthType.TrustedAuthTokenCookieless` +(Recommended) a| Use this authentication type to implement cookieless authentication if your Web browsers block third-party cookies. +a|Do not use this method if you don’t have an app backend component to host the authentication server needed for trusted authentication. -.2+|xref:embed-authentication.adoc#trusted-auth-embed[Trusted authentication]|`AuthType.TrustedAuthToken` a|Use this method: + +|`AuthType.TrustedAuthToken` a|Use this method: + * If your IdP setup does not support Embedded SSO authentication. * If you want your users that do not exist in your IdP to authenticate to ThoughtSpot. @@ -42,13 +39,18 @@ a|ThoughtSpot does not recommend using Embedded SSO authentication in the follow a|ThoughtSpot does not recommend using trusted authentication in the following scenarios: + -* If you want to and can implement a simple solution with Embedded SSO authentication. -* If you don’t have an app backend component to host the authentication server needed for trusted authentication. +If you don’t have an app backend component to host the authentication server needed for trusted authentication. +|xref:embed-authentication.adoc#embedSSO[Embedded SSO authentication] |`AuthType.EmbeddedSSO` a| Use this method: + -|`AuthType.TrustedAuthTokenCookieless` a| Use this authentication type to implement cookieless authentication if your Web browsers block third-party cookies. +* If your application is already using a SAML IdP or OpenID provider that allows iframe redirects. +* If your ThoughtSpot instance has SAML or OIDC authentication support configured. +* To seamlessly redirect your users to their IdP within the embedded iframe for authentication. -a|Do not use this method if you don’t have an app backend component to host the authentication server needed for trusted authentication. +a|ThoughtSpot does not recommend using Embedded SSO authentication in the following scenarios: + + +* If you are using multiple IdPs for user authentication. + +* If you cannot configure your IdP to allow iframe redirect. + |xref:embed-authentication.adoc#saml-sso-embed[SAMLRedirect authentication]|`AuthType.SAMLRedirect` a|Use this method if your application uses a SAML IdP that does not natively support embedding. a|Do not use this method if you don't want the SDK to redirect your entire app to the IdP for user authentication when the embedded content loads. For example, you may want to seamlessly authenticate users without multiple redirects to the IdP. @@ -74,6 +76,13 @@ For some situations, shared *customer-level* or *role-level* accounts may be mor *Public access* can be achieved by creating a dedicated *public user account* with tightly defined access control. Any of the authentication methods can be used for the public user account. +[#trusted-auth-embed] +== Trusted authentication + +In the trusted authentication method, a security token is required to authenticate users who request access to the embedded ThoughtSpot content. For trusted authentication, you will require a token request service, which can securely authenticate your application users. + +For more information, see xref:trusted-authentication.adoc[Trusted authentication]. + [#embedSSO] == Embedded SSO authentication @@ -87,14 +96,6 @@ init({ }); ---- -[#trusted-auth-embed] -== Trusted authentication - -In the trusted authentication method, a security token is required to authenticate users who request access to the embedded ThoughtSpot content. For trusted authentication, you will require a token request service, which can securely authenticate your application users. - -For more information, see xref:trusted-authentication.adoc[Trusted authentication]. - - [#saml-sso-embed] == SAMLRedirect authentication If your IdP supports SAML SSO to authenticate and does not support iFrame redirects, you can configure the `SAMLRedirect` auth type to authenticate your embedded application users. If this authentication method is enabled, the SDK redirects your app to the IdP login page for user authentication when the embedded content loads. @@ -162,10 +163,9 @@ Optionally, you can configure a `redirectPath` string to redirect embed users to redirectPath: "/dashboard" ---- - [#none] == No authentication (pass-through) method -If your application already uses an IdP to authenticate users and allows iframe embedding, and your ThoughtSpot instance has SAML or OIDC configured, you can set the `authType` attribute to `None`. The `None` authentication method can leverage user authentication taking place outside of the embedded application context. The SDK won't do additional authentication and acts as a pass-through. +If your application already uses an IdP to authenticate users and allows iframe embedding, and your ThoughtSpot instance has SAML or OIDC configured, you can set the `authType` attribute to `None`. The `None` authentication method can leverage user authentication taking place outside the embedded application context. The SDK won't do additional authentication and acts as a pass-through. [source,javascript] ---- @@ -175,6 +175,12 @@ init({ }); ---- +[NOTE] +==== +* This `AuthType.None` authentication method is not recommended for Production use cases. +* Many web browsers do not support third-party cookies. Due to this, cookies will no longer be shared across the embed and the host application, or other tabs in the browser. Developers using this authentication method in development or test environments must xref:security-settings.adoc#_enable_partitioned_cookies[enable partitioned cookies] on the *Develop* > *Security settings* page. On browsers supporting partitioned cookies, the login cookie will persist in the app after a successful login. Therefore, the `AuthType.None` authentication method requires logging into the embedded application through Basic Authentication. +==== + [#basic-auth-embed] == Basic authentication @@ -202,7 +208,6 @@ init({ ThoughtSpot does not recommend this authentication method for production environments. ==== - == Authentication errors and event handling The user authentication may fail due to an incomplete SSO login process, expired user session, SDK initialization error, or if the browser has blocked third-party cookies. diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 4d4b89ace..1905da439 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -156,7 +156,7 @@ When customizing icons, ensure that the hosting server is added to to the *CSP c ==== Customize menu elements -You can show or hide menu elements such as the *Pin*, *Save* buttons on the Spotter page using xref:embed-actions.adoc[`disabledActions`, `visibleActions`, or `hiddenActions`] array as shown in this example: +You can show or hide menu elements such as the *Pin*, *Save*, and *Download* buttons, and chart switcher icon on the Spotter page using xref:embed-actions.adoc[`disabledActions`, `visibleActions`, or `hiddenActions`] array as shown in this example: [source,JavaScript] ---- @@ -166,7 +166,7 @@ You can show or hide menu elements such as the *Pin*, *Save* buttons on the Spot [NOTE] ==== -In ThoughtSpot 10.4.0.cl release, you can hide or disable only *Pin* and *Save* menu actions on the Spotter page. +Action enumerators to show, disable, or hide menu elements such as *Preview data*, *Reset*, feedback widget, and the edit and delete icons on the Spotter page are not available in Visual Embed SDK for ThoughtSpot 10.5.0.cl release. ==== === Register, handle, and trigger events diff --git a/modules/ROOT/pages/embed-ts-react-app.adoc b/modules/ROOT/pages/embed-ts-react-app.adoc index 4ff67a86b..5d4c8eee6 100644 --- a/modules/ROOT/pages/embed-ts-react-app.adoc +++ b/modules/ROOT/pages/embed-ts-react-app.adoc @@ -87,253 +87,6 @@ You will require GUIDs of the following objects to embed ThoughtSpot components. You can find the GUIDs of these objects in the UI, the developer Playground on your ThoughtSpot instance, or through the xref:metadata-api.adoc#metadata-list[metadata/list] and xref:metadata-api#object-header[metadata/listobjectheaders] REST API endpoints. -== Embed ThoughtSpot search - -To embed ThoughtSpot Search page, complete the following steps: - -=== Create a Search component - -In your React app project, go to the **Components ** folder in your app directory and add a page for the embedded search object; for example, `Search.tsx`. - -. Import the `SearchEmbed` component and event libraries -+ -[source,TypeScript] ----- -import React from 'react' -import { Action, AuthType, init, EmbedEvent, HostEvent } from '@thoughtspot/visual-embed-sdk'; -import { SearchEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/react'; ----- -+ -If you are using Webpack 4, which is the default when using `create-react-app v4`, import the React components as shown in this example: - -+ -[source,TypeScript] ----- -import { SearchEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/lib/src/react'; ----- -. Initialize the SDK and specify the xref:embed-authentication.adoc[authentication method]. -. Add constructor options as props -. Add event listeners: -.. For Embed events, use the `on` convention. -.. For Host events, use the `trigger(HostEvent.)` method. -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -. Render the app. -+ ----- -ts-data-app> npm start ----- - -=== Code sample -The following code sample shows additional attributes and properties: - -* A `Search` function with a data source ID. -* The `searchOptions` property to construct a query string with `[quantity purchased] [region]` keywords and execute the search query. -* Event handlers for `init` and Load` events. - -+ -[source,TypeScript] ----- -import { init } from "@thoughtspot/visual-embed-sdk"; -import { SearchEmbed } from "@thoughtspot/visual-embed-sdk/react"; - -// If you are using Webpack 4 (which is the default when using create-react-app v4), import -// the React components using the below: -// import { SearchEmbed } from "@thoughtspot/visual-embed-sdk/lib/src/react"; - -init({ - thoughtSpotHost: "<%=tshost%>", - authType: AuthType.None, -}); -const Search = () => { - //To construct a search query and execute the search, define a search token string - const searchOptions = { - searchTokenString: "[quantity purchased] [region]", - executeSearch: true, - }; - //add event handlers - const onInit = () => { - console.log(EmbedEvent.Init, {}); - }; - const onLoad = () => { - console.log(EmbedEvent.Load, {}); - }; - return ( - - ); -}; ----- - -For more information about `SearchEmbed` objects and attributes, see the following pages: - -* xref:SearchEmbed.adoc[SearchEmbed] -* xref:SearchViewConfig.adoc[SearchViewConfig] -* xref:Action.adoc[Actions] - -//// -+ -If you want to programmatically change the search query string, you can add a custom function; for example, `changeSearch`. You can assign this function to a button to programmatically update a search query. + -The following example defines the `changeSearch` function and adds an event handler to trigger a host app event when the query changes to `[sales] by [item type]`. - -+ -[source,TypeScript] ----- -const Search = () => { - const embedRef = useEmbedRef(); - // define a search token string to construct a search query - const searchOptions = { - searchTokenString: "[quantity purchased] [region]", - executeSearch: true, - }; - //Add a custom function to update the search query string and trigger an event when the query is changed - const changeSearch = () => { - embedRef.current.trigger(HostEvent.Search, { - searchQuery: "[sales] by [item type]", - dataSource: ["cd252e5c-b552-49a8-821d-3eadaa049cca"], - }); - }; - //add event handlers - const onQueryChanged = () => { - console.log(EmbedEvent.QueryChanged, {}); - }; - return ( -
- - -
- ); -}; ----- -//// - - -=== Test your app - -* Load your application. -* Check if the ThoughtSpot search bar is rendered with the search tokens you specified. -+ -[.bordered] -image::./images/embed-search-react.png[] - -//// -* Change the search query and check if the search tokens are replaced. -+ -[.bordered] -image::./images/search-query-changed.png[] - -* Check the console log to verify if the registered events are emitted. -//// - -== Embed a Natural Language Search -To embed ThoughtSpot Natural Language Search interface, complete the steps listed in the following sections. - -=== Create a Natural Language Search component - -In your React app project, go to the **Components ** folder in your app directory and add a page for the embedded search object; for example, `Sage.tsx`. - -. Import the `SageEmbed` component and event libraries -+ -[source,TypeScript] ----- -import { Action, EmbedEvent, HostEvent } -from "@thoughtspot/visual-embed-sdk"; -import {SageEmbed,useEmbedRef} -from "@thoughtspot/visual-embed-sdk/lib/src/react"; ----- - -. Initialize the SDK and specify the xref:embed-authentication.adoc[authentication method]. -. Add constructor options as props and register event handlers. -. Render the app. -+ ----- -ts-data-app> npm start ----- - - -=== Code sample -The following code sample shows additional attributes and properties: - -* A `Sage` function with a data source ID. -* The `searchOptions` property to pass a search query `number of jackets sold today` and execute the query. -* Event handlers for `init` and Load events. - -+ -[source,TypeScript] ----- -import { init } from "@thoughtspot/visual-embed-sdk"; -import { SageEmbed } from "@thoughtspot/visual-embed-sdk/react"; - -// If you are using Webpack 4 (which is the default when using create-react-app v4), you would need to import -// the React components using the below: -// import { SageEmbed } from "@thoughtspot/visual-embed-sdk/lib/src/react"; - -// Initialize ThoughtSpot -init({ - thoughtSpotHost: "<%=tshost%>", - authType: AuthType.None, -}); -const Sage = () => { - // Define search options - const searchOptions = { - searchQuery: "number of jackets sold today", // Search query to execute - executeSearch: true, // Execute search immediately - }, - dataSource: "c8684f7f-d8a4-4bc9-b87d-115433c5e458", // Replace with your actual data source - }; - // Add Event handlers - const onInit = () => { - console.log(EmbedEvent.Init, {}); - }; - - const onLoad = () => { - console.log(EmbedEvent.Load, {}); - }; - - return ( - - ); -}; ----- - -For more information about `SageEmbed` objects and attributes, see the following pages: - -* xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig.adoc[SageViewConfig] -* xref:HostEvent.adoc[HostEvent] -* xref:EmbedEvent.adoc[EmbedEvent] -* xref:Action.adoc[Actions] - -=== Test your app - -* Load your application. -* Check if the ThoughtSpot natural language search bar is rendered with the search query you specified. -+ -[.bordered] -image::./images/sage-embed.png[] - == Embed a Liveboard To embed a ThoughtSpot Liveboard, complete the following steps: @@ -429,7 +182,6 @@ const Liveboard = ({liveboardId}) => { }; ---- - For more information about `LiveboardEmbed` object and properties, see the following pages: * xref:LiveboardEmbed.adoc[LiveboardEmbed] @@ -744,6 +496,374 @@ const FullApp = () => { ---- //// +== Embed Spotter for conversation analytics +To embed ThoughtSpot Spotter conversation interface [beta betaBackground]^Beta^ with or without a pre-defined search query string, use the `ConversationEmbed` component. + +=== Create a conversation component + +In your React app project: + +. Go to the **Components ** folder in your app directory and add a page for the embedded search object; for example, `conversation.tsx`. +. Import the `ConversationEmbed` component. ++ +[source,TypeScript] +---- +import { AuthType, init, Action } from "@thoughtspot/visual-embed-sdk"; + +import { + ConversationEmbed, + useEmbedRef +} from "@thoughtspot/visual-embed-sdk/react'"; +---- ++ +If you are using Webpack 4, import the React components as shown in this example: + ++ +[source,TypeScript] +---- +import { ConversationEmbed, + useEmbedRef } from '@thoughtspot/visual-embed-sdk/lib/src/react'; +---- + +. Initialize the SDK and specify the xref:embed-authentication.adoc[authentication method]. +. Add constructor options as props. +.. For Embed events, use the `on` convention. +.. For Host events, use the `trigger(HostEvent.)` method. + +. Render the app. ++ +---- +ts-data-app> npm start +---- + +=== Code sample +The following code sample shows additional attributes and properties: + +* A `ConversationEmbed` function with a Worksheet ID passed as data source. +* The `searchOptions` property to pass a search query string. +* Event handlers for `init` and `Load` Embed events. + ++ +[source,TypeScript] +---- +import { AuthType, init, Action } from "@thoughtspot/visual-embed-sdk"; +import { ConversationEmbed, useEmbedRef } from "@thoughtspot/visual-embed-sdk/react"; + +// If you are using Webpack 4 (which is the default when using create-react-app v4), you would need to import +// the React components using the below: +// import { ConversationEmbed } from "@thoughtspot/visual-embed-sdk/lib/src/react"; + +// Initialize ThoughtSpot +init({ + thoughtSpotHost: "<%=tshost%>", + authType: AuthType.None, +}); +const ConversationEmbed = () => { + // Define search options + const searchOptions = { + searchQuery: "sales by region" // Search query to execute + }; + const dataSource = "c8684f7f-d8a4-4bc9-b87d-115433c5e458"; // Replace with your actual data source + + // Add Event handlers + const onInit = () => { + console.log(EmbedEvent.Init, {}); + }; + + const onLoad = () => { + console.log(EmbedEvent.Load, {}); + }; + + return ( + + ); +}; +---- + +For more information, see the following pages: + +* xref:ConversationEmbed.adoc[SageEmbed] +* xref:EmbedEvent.adoc[EmbedEvent] +* xref:Action.adoc[Actions] + +=== Test your app + +* Load your application. +* Check if the Spotter component is rendered with the search query you specified. ++ +[.widthAuto] +[.bordered] +image::./images/converseEmbed-with-query.png[Conversation embed] + +== Embed a Natural Language Search +To embed ThoughtSpot Natural Language Search interface, complete the steps listed in the following sections. + +=== Create a Natural Language Search component + +In your React app project: + +. Go to the **Components ** folder in your app directory and add a page for the embedded search object; for example, `Sage.tsx`. +. Import the `SageEmbed` component and event libraries. ++ +[source,TypeScript] +---- +import { AuthType, init, EmbedEvent, HostEvent } from "@thoughtspot/visual-embed-sdk"; + +import { + SageEmbed, + useEmbedRef +} from "@thoughtspot/visual-embed-sdk/react'"; +---- ++ +If you are using Webpack 4, import the React components as shown in this example: ++ +[source,TypeScript] +---- +import { SageEmbed, + useEmbedRef } from '@thoughtspot/visual-embed-sdk/lib/src/react'; +---- + +. Initialize the SDK and specify the xref:embed-authentication.adoc[authentication method]. +. Add constructor options as props. +.. For Embed events, use the `on` convention. +.. For Host events, use the `trigger(HostEvent.)` method. + +. Render the app. ++ +---- +ts-data-app> npm start +---- + +=== Code sample +The following code sample shows additional attributes and properties: + +* A `Sage` function with a data source ID. +* The `searchOptions` property to pass a search query `number of jackets sold today` and execute the query. +* Event handlers for `init` and `Load` embed events. + ++ +[source,TypeScript] +---- +import { init, EmbedEvent, HostEvent } from "@thoughtspot/visual-embed-sdk"; +import { SageEmbed } from "@thoughtspot/visual-embed-sdk/react"; + +// If you are using Webpack 4 (which is the default when using create-react-app v4), you would need to import +// the React components using the below: +// import { SageEmbed } from "@thoughtspot/visual-embed-sdk/lib/src/react"; + +// Initialize ThoughtSpot +init({ + thoughtSpotHost: "<%=tshost%>", + authType: AuthType.None, +}); +const Sage = () => { + // Define search options + const searchOptions = { + searchQuery: "number of jackets sold today", // Search query to execute + executeSearch: true, // Execute search immediately + }, + dataSource: "c8684f7f-d8a4-4bc9-b87d-115433c5e458", // Replace with your actual data source + }; + // Add Event handlers + const onInit = () => { + console.log(EmbedEvent.Init, {}); + }; + + const onLoad = () => { + console.log(EmbedEvent.Load, {}); + }; + + return ( + + ); +}; +---- + +For more information about `SageEmbed` objects and attributes, see the following pages: + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig.adoc[SageViewConfig] +* xref:HostEvent.adoc[HostEvent] +* xref:EmbedEvent.adoc[EmbedEvent] +* xref:Action.adoc[Actions] + +=== Test your app + +* Load your application. +* Check if the ThoughtSpot natural language search bar is rendered with the search query you specified. ++ +[.bordered] +image::./images/sage-embed.png[] + + +== Embed token-based Search + +To embed ThoughtSpot Search page, complete the following steps: + +=== Create a Search component + +In your React app project, go to the **Components ** folder in your app directory and add a page for the embedded search object; for example, `Search.tsx`. + +. Import the `SearchEmbed` component and event libraries ++ +[source,TypeScript] +---- +import React from 'react' +import { Action, AuthType, init, EmbedEvent, HostEvent } from '@thoughtspot/visual-embed-sdk'; +import { SearchEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/react'; +---- ++ +If you are using Webpack 4, which is the default when using `create-react-app v4`, import the React components as shown in this example: + ++ +[source,TypeScript] +---- +import { SearchEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/lib/src/react'; +---- +. Initialize the SDK and specify the xref:embed-authentication.adoc[authentication method]. +. Add constructor options as props +. Add event listeners: +.. For Embed events, use the `on` convention. +.. For Host events, use the `trigger(HostEvent.)` method. ++ +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +. Render the app. ++ +---- +ts-data-app> npm start +---- + +=== Code sample +The following code sample shows additional attributes and properties: + +* A `Search` function with a data source ID. +* The `searchOptions` property to construct a query string with `[quantity purchased] [region]` keywords and execute the search query. +* Event handlers for `init` and Load` events. + ++ +[source,TypeScript] +---- +import { init } from "@thoughtspot/visual-embed-sdk"; +import { SearchEmbed } from "@thoughtspot/visual-embed-sdk/react"; + +// If you are using Webpack 4 (which is the default when using create-react-app v4), import +// the React components using the below: +// import { SearchEmbed } from "@thoughtspot/visual-embed-sdk/lib/src/react"; + +init({ + thoughtSpotHost: "<%=tshost%>", + authType: AuthType.None, +}); +const Search = () => { + //To construct a search query and execute the search, define a search token string + const searchOptions = { + searchTokenString: "[quantity purchased] [region]", + executeSearch: true, + }; + //add event handlers + const onInit = () => { + console.log(EmbedEvent.Init, {}); + }; + const onLoad = () => { + console.log(EmbedEvent.Load, {}); + }; + return ( + + ); +}; +---- + +For more information about `SearchEmbed` objects and attributes, see the following pages: + +* xref:SearchEmbed.adoc[SearchEmbed] +* xref:SearchViewConfig.adoc[SearchViewConfig] +* xref:Action.adoc[Actions] + +//// ++ +If you want to programmatically change the search query string, you can add a custom function; for example, `changeSearch`. You can assign this function to a button to programmatically update a search query. + +The following example defines the `changeSearch` function and adds an event handler to trigger a host app event when the query changes to `[sales] by [item type]`. + ++ +[source,TypeScript] +---- +const Search = () => { + const embedRef = useEmbedRef(); + // define a search token string to construct a search query + const searchOptions = { + searchTokenString: "[quantity purchased] [region]", + executeSearch: true, + }; + //Add a custom function to update the search query string and trigger an event when the query is changed + const changeSearch = () => { + embedRef.current.trigger(HostEvent.Search, { + searchQuery: "[sales] by [item type]", + dataSource: ["cd252e5c-b552-49a8-821d-3eadaa049cca"], + }); + }; + //add event handlers + const onQueryChanged = () => { + console.log(EmbedEvent.QueryChanged, {}); + }; + return ( +
+ + +
+ ); +}; +---- +//// + + +=== Test your app + +* Load your application. +* Check if the ThoughtSpot search bar is rendered with the search tokens you specified. ++ +[.bordered] +image::./images/embed-search-react.png[] + +//// +* Change the search query and check if the search tokens are replaced. ++ +[.bordered] +image::./images/search-query-changed.png[] + +* Check the console log to verify if the registered events are emitted. +//// + [#react-routes] == Add routes for navigation diff --git a/modules/ROOT/pages/embed-without-sdk.adoc b/modules/ROOT/pages/embed-without-sdk.adoc index 9d6dc4297..9ab4d8d94 100644 --- a/modules/ROOT/pages/embed-without-sdk.adoc +++ b/modules/ROOT/pages/embed-without-sdk.adoc @@ -68,6 +68,7 @@ Note the URL format to embed a Liveboard in an iFrame: `\https://{ThoughtSpot-Host}/?embedApp=true#/embed/viz/{Liveboard_id}` + You can also add xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[additional flags] and xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters and parameter overrides] as query parameters in the embed URL. == Embed a visualization in an iFrame @@ -203,13 +204,18 @@ For example, to filter `michigan` in the `State` columns, pass these values as f **Liveboard embed** + `\https://{ThoughtSpot-host}/?embedApp=true&p&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}` - - ++ +If the per Org URL feature is enabled on your ThoughtSpot instance, the URL format will be: ++ +`\https://{ThoughtSpot-host}/?embedApp=true&p&col1=State&op1=EQ&val1=michigan&OrgID=1#/embed/viz/{Liveboard_id}` + **Visualization embed** + `\http://{ThoughtspotHost}/?embedApp=true&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}/{visualization_id}` - ++ +If the per Org URL feature is enabled on your ThoughtSpot instance, the URL format will be: ++ +`\http://{ThoughtspotHost}/?embedApp=true&col1=State&op1=EQ&val1=michigan&OrgID=1#/embed/viz/{Liveboard_id}/{visualization_id}` + **Search embed** + @@ -224,13 +230,20 @@ To apply xref:runtime-parameters.adoc[Parameter overrides], add the Parameter na **Liveboard embed** + `\https://{ThoughtSpot-host}/?embedApp=true¶m1=Discount¶mVal1=0.25#/embed/viz/{Liveboard_id}` - ++ +If the per Org URL feature is enabled on your ThoughtSpot instance, the URL format will be: ++ +`\https://{ThoughtSpot-host}/?embedApp=true¶m1=Discount¶mVal1=0.25&OrgID=1#/embed/viz/{Liveboard_id}` + **Visualization URL embed** + `\https://{ThoughtSpot-host}/?embedApp=true¶m1=Discount¶mVal1=0.25#/ embed/viz/{Liveboard_id}/{visualization_id}` - ++ +If the per Org URL feature is enabled on your ThoughtSpot instance, the URL format will be: ++ +`\https://{ThoughtSpot-host}/?embedApp=true¶m1=Discount¶mVal1=0.25&OrgID=1#/ +embed/viz/{Liveboard_id}/{visualization_id}` + **Search embed** @@ -244,6 +257,21 @@ embed/viz/{Liveboard_id}/{visualization_id}` The Natural Language Search component does not support runtime overrides. ==== +== URL format with the per Org feature +If the per Org URL feature is enabled on your ThoughtSpot instance, a sample URL format will be: + +*Liveboard embed* + +`\https://{ThoughtSpot-Host}/?embedApp=true&OrgID=1#/embed/viz/{Liveboard_id}` + +*Visualization embed* + +`\https://{ThoughtSpot-Host}/?embedApp=true&OrgID=1#/embed/viz/{Liveboard_id}/{visualization_id}` + +*Search Embed* + +`\https://{ThoughtSpot-Host}/?embedApp=true&dataSources=["cd252e5c-b552-49a8-821d-3eadaa049cca"]&OrgID=1#/answer` + == Feature flags and query parameters to customize the embedded view To customize ThoughtSpot components embedded in an iFrame, ThoughtSpot provides additional flags that you can pass as query parameters in the iFrame embedding URL. diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 48f786422..b6af5b057 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -12,26 +12,26 @@ The xref:full-embed.adoc[AppEmbed component] embeds the entire ThoughtSpot appli The ThoughtSpot UI and navigation experience is available in two modes: * Classic experience (default) -* New navigation and homepage experience [earlyAccess eaBackground]#Early Access# +* New navigation and Home page experience [earlyAccess eaBackground]#Early Access# -=== New navigation and homepage experience +=== New navigation and Home page experience -In the new navigation and homepage experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the header bar instead of the top navigation menu. The app selector consists of different persona-based contextual elements called apps. On clicking an app from the application, the page corresponding to that app opens. Each application module has a separate left navigation panel. +In the new navigation and Home page experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the header bar instead of the top navigation menu. The app selector consists of different persona-based contextual elements called apps. On clicking an app from the application, the page corresponding to that app opens. Each application module has a separate left navigation panel. [.bordered] [.widthAuto] image::./images/homepage.png[New home page] -The new navigation and homepage experience introduces the following changes: +The new navigation and Home page experience introduces the following changes: [width="100%", cols="3,7,7"] [options='header'] |===== -||Classic experience |New navigation and homepage experience +||Classic experience |New navigation and Home page experience |Navigation a|Top navigation menu with the following buttons: * **Home** + -Opens Homepage + +Opens Home page + * **Answers** + Opens Answers page + * **Liveboards** + @@ -52,9 +52,9 @@ Opens Search data page a| App selector image:./images/app_switcher.png[the app switcher menu] with the following apps: * **Insights** + -Opens the Insights homepage. Note that the Answers, Liveboards, SpootIQ, and Monitor Subscriptions are grouped as Insights in the new homepage experience. + +Opens the Insights page. Note that the Answers, Liveboards, SpootIQ, and Monitor Subscriptions are grouped as Insights in the new Home page experience. + ** **Insights** > **Home** + -Opens homepage +Opens Home page ** **Insights** > **Search Data** + Opens the Search Data page. ** **Insights** > **Answers** + @@ -65,7 +65,7 @@ Opens the Liveboards page. Opens the SpotIQ page. ** **Insights** > **Monitor Subscriptions** + Opens Monitor alerts page. + -The **Insights** homepage also includes **Help** and **Chat with Support** menu options. +The **Insights** page also includes **Help** and **Chat with Support** menu options. * **Data workspace** + Opens the Data workspace page (Requires data management privilege) * **Admin** + @@ -78,7 +78,7 @@ Opens Search data page Opens Liveboards page * **View all Answers** + Opens Answers page -|Homepage experience |In the classic experience mode, the **Home** page shows the Natural Language Search panel, a list of Answers and Liveboards, and trending charts. | The **Insights** page in new experience mode shows a customizable homepage with features such as Natural Language Search panel, watchlist, favorites, a library of Answers and Liveboards, trending charts, and more. With the new left-hand navigation, users can navigate to your Liveboards, Answers, SpotIQ analysis, and Monitor subscriptions. +|Home page experience |In the classic experience mode, the **Home** page shows the Natural Language Search panel, a list of Answers and Liveboards, and trending charts. | The **Insights** page in new experience mode shows a customizable home page with features such as Natural Language Search panel, watchlist, favorites, a library of Answers and Liveboards, trending charts, and more. With the new left-hand navigation, users can navigate to your Liveboards, Answers, SpotIQ analysis, and Monitor subscriptions. |Application page URLs a| * **Liveboards** + `\https://{ThoughtSpot-Host}/#/pinboards` @@ -101,7 +101,7 @@ a| |===== == Enable new experience mode for ThoughtSpot embedding -By default, the new navigation and homepage experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. +By default, the new navigation and home page experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. [source,javascript] ---- @@ -159,7 +159,7 @@ The following examples show valid strings for `path`: [width="100%", cols="3,6,6"] [options='header'] |===== -|Page| Classic experience | New navigation and homepage experience +|Page| Classic experience | New navigation and Home page experience |Answers| `path: "answers"`| `path: "home/answers"` |Saved Answer| `path: "saved-answer/"` |`path: "saved-answer/"` |Liveboards| `path: "pinboards"`| `path: "home/liveboards"` @@ -191,7 +191,7 @@ Page changes within the `AppEmbed` component register as part of the embedding a The standard JavaScript `history.back()` function will cause the `AppEmbed` component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component. -== Search experience +== Search components ThoughtSpot application supports the following types of search: @@ -202,26 +202,51 @@ Starting from 10.3.0.cl, the Object Search experience will be the default search * Natural Language Search + -Allows searching a data source using a natural language query string and get AI-generated Answers. Starting from 10.3.0.cl release, the Natural Language Search experience on the ThoughtSpot application Home page is disabled by default. -+ -To enable access to Natural Language Search feature for your end users, you can do one of the following: + - -** Create a xref:embed-nls.adoc[Natural Language Search page using the SageEmbed SDK package] and build a navigation to this page from your embedding application. -** xref:full-app-customize.adoc#_customize_search_experience[Switch the Search experience on the Home page] to Natural Language Search. +Allows searching a data source using a natural language query string and get AI-generated Answers. + +If Spotter[beta betaBackground]^Beta^ is enabled on your instance, the Home page will show the Spotter search bar and the UI interface for conversational analytics. * Search data + Allows searching a data source using keywords and search tokens. This experience is available if you have embedded the **Search** page using `appEmbed` or `SearchEmbed`. -==== Customize search experience for Home page -In full application embedding, the Object Search bar is available in the following locations: +[#_search_experience_on_home_page] +=== Search interface on the Home page +On ThoughtSpot instances, the search box located in the top navigation bar allows users to search for ThoughtSpot objects. If you are embedding full ThoughtSpot experience in your app, you can control the visibility of the top navigation bar using the `showPrimaryNavbar` property in the SDK. + +If the Natural Language Search feature is enabled on the instance, the search bar on the Home page allows users to explore Natural Language Search capabilities and view AI-generated answers. + +In the ThoughtSpot 10.3.0.cl release, the search experience in the Home page was modified to decouple Natural Language Search and Object Search. On instances running 10.3.0.cl and later versions, the search experience on the Home page is set to Object Search by default. To enable access to Natural Language Search for your end users, use one of the following options: + + +* Create a xref:embed-nls.adoc[Natural Language Search page using the SageEmbed SDK package] and build a navigation to this page from your embedding application. +* xref:full-app-customize.adoc#_customize_search_experience[Switch the Search experience on the Home page] to Natural Language Search. + +[IMPORTANT] +==== +If your instance is pgraded from 10.1.0.cl to 10.5.0.cl, Natural Language Search will be set as the default search experience for the Home page and the split search experience will be turned off by default. For applications embedding full ThoughtSpot experience, the `isUnifiedSearchExperienceEnabled` property will be set to `true` in the SDK. Your users can continue to use the unified experience until it is deprecated. Developers can choose to disable unified search experience and customize the Home page search experience for their users if required. -* Top navigation bar + -__Optional__. The top navigation bar visibility is controlled via `showPrimaryNavbar` parameter in the Visual Embed SDK. If your embedding includes the top navigation bar, note that the Object Search bar is available in the navigation bar. +If your instance is upgraded from 10.3.0.cl or 10.4.0.cl to 10.5.0.cl, the unified search experience will be disabled by default and the `isUnifiedSearchExperienceEnabled` property will be set to `false`. +==== -* Home page + -Starting from 10.3.0.cl, the Object Search bar will appear on the embedded **Home** page as the default Search experience. You can switch the Search experience by setting the `homePageSearchBarMode` property to one of the following values: +//// +New home page and navigation experience mode:: +By default, the Object Search bar is displayed in the Search module on the embedded **Home** page: + +[.bordered] +image::./images/objSearchNav_modularExp.png[] + +Classic experience mode:: +By default, the Object Search bar is displayed on the embedded **Home** page. + ++ +[.bordered] +image::./images/sageDisabledwithNav_classic.png[] +//// + + +=== Customize search experience + +Developers can customize the Search experience by setting the `homePageSearchBarMode` property in the SDK to one of the following values: + ** `objectSearch` (default) + Displays Object Search bar on the **Home** page. ** `aiAnswer` + @@ -229,53 +254,41 @@ Displays the search bar for Natural Language Search ** `none` Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +If you want to use the Natural Language Search experience, enable Natural Language Search as shown in the following example: -===== In the Classic experience mode -By default, the Object Search bar is displayed on the embedded **Home** page. - -[.bordered] -image::./images/sageDisabledwithNav_classic.png[] - -If you want to use the Natural Language Search experience, enable Sage Search bar as shown in this code snippet: +New Home page and navigation experience mode:: [source,javascript] ---- const embed = new AppEmbed("#embed", { + modularHomeExperience: true, showPrimaryNavbar: true, homePageSearchBarMode: "aiAnswer", }); ---- -[.bordered] -image::./images/sageEnabledwithNav_classic.png[] - -===== In the New modular experience mode - -By default, the Object Search bar is displayed in the Search module on the embedded **Home** page: +When enabled, the Search bar functions as a Natural Language Search interface: [.bordered] -image::./images/objSearchNav_modularExp.png[] +image::./images/sageEnabledNav_modularExp.png[] -If you want to use the Natural Language Search experience, enable Sage Search bar as shown in this code snippet: +Classic experience mode:: [source,javascript] ---- const embed = new AppEmbed("#embed", { - modularHomeExperience: true, showPrimaryNavbar: true, homePageSearchBarMode: "aiAnswer", }); ---- -[.bordered] -image::./images/sageEnabledNav_modularExp.png[] +When enabled, the Search bar functions as a Natural Language Search interface: -[NOTE] -==== -If you need additional help or assistance with customization, contact ThoughtSpot Support. -==== +[.bordered] +[.widthAuto] +image::./images/sageEnabledwithNav_classic.png[] -== Include Spotter interface +=== Include Spotter interface To integrate Spotter [beta betaBackground]^Beta^ capabilities and conversation interface in full app embedding, make sure Spotter is enabled on your instance and then set the `homePageSearchBarMode` to `aiAnswer` in the SDK. [source,javascript] @@ -286,6 +299,12 @@ const embed = new AppEmbed("#embed", { }); ---- +When enabled, the Spotter search bar and conversation interface appears on the Home page: + +[.bordered] +[.widthAuto] +image::./images/spotter-fullApp.png[] + == Customize navigation controls The `AppEmbed` package in the Visual Embed SDK provides several parameters to hide or customize navigation controls. @@ -294,13 +313,13 @@ The top navigation menu bar (classic experience), app selector image:./images/ap * `hideOrgSwitcher` + Hides the Orgs drop-down. Applicable to only Orgs-enabled clusters. * `hideApplicationSwitcher` + -Hides the app selector image:./images/app_switcher.png[the app switcher menu]. The app selector is available only in the new navigation and homepage experience mode. +Hides the app selector image:./images/app_switcher.png[the app switcher menu]. The app selector is available only in the new navigation and Home page experience mode. * `disableProfileAndHelp` + ** To hide help and profile icons (Classic experience) + -** To hide help and profile icons, Help and Chat with Support menu options on the homepage (New Experience). +** To hide help and profile icons, Help and Chat with Support menu options on the Home page (New Experience). -=== Customize the left navigation panel on homepage (New experience) -If the new navigation and homepage experience is enabled and `showPrimaryNavbar` to `true`, the home page displays a navigation panel on the left side of the Insights homepage. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on. +=== Customize the left navigation panel on Home page (New experience) +If the new navigation and Home page experience is enabled and `showPrimaryNavbar` to `true`, the home page displays a navigation panel on the left side of the Insights page. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on. To hide the left navigation panel in the embedded view, set `hideHomepageLeftNav` to `true`. @@ -326,8 +345,8 @@ const embed = new AppEmbed("#embed", { }); ---- -== Customize homepage modules (New experience) -If the new navigation and homepage experience is enabled on your ThoughtSpot instance, the homepage shows modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. To customize these modules and the homepage experience, use the xref:AppViewConfig.adoc#_hiddenhomepagemodules[`hiddenHomepageModules`] array. +== Customize Home page modules (New experience) +If the new navigation and Home page experience is enabled on your ThoughtSpot instance, the Home page shows modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. To customize these modules and the Home page experience, use the xref:AppViewConfig.adoc#_hiddenhomepagemodules[`hiddenHomepageModules`] array. [source,javascript] ---- @@ -337,7 +356,7 @@ const embed = new AppEmbed("#embed", { }); ---- -To reorder homepage modules, use the xref:AppViewConfig.adoc#_reorderedhomepagemodules[ `reorderedHomepageModules`] array. +To reorder Home page modules, use the xref:AppViewConfig.adoc#_reorderedhomepagemodules[ `reorderedHomepageModules`] array. [source,javascript] ---- diff --git a/modules/ROOT/pages/jwt-migration.adoc b/modules/ROOT/pages/jwt-migration.adoc new file mode 100644 index 000000000..3bba6885a --- /dev/null +++ b/modules/ROOT/pages/jwt-migration.adoc @@ -0,0 +1,224 @@ += Migrate ABAC ^BETA^ implementation to custom token API +:toc: true +:toclevels: 2 + +:page-title: ABAC via tokens migration steps +:page-pageid: abac-migration-guide +:page-description: Steps for migrating your implementation to use custom token API workflow + +If your application instance is upgraded 10.4.0.cl or later version, ThoughtSpot recommends using the the +++/api/rest/2.0/auth/token/custom+++ API endpoint to xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[generate a JWT token with custom security rules] instead of the `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs. The `user_parameters` property is deprecated in 10.4.0.cl. + +If your current application environment is using the beta version of the ABAC, follow the steps described in this article to smoothly migrate your ABAC implementation with the `/api/rest/2.0/auth/token/full` or `/api/rest/2.0/auth/token/object` API endpoint to the new `/api/rest/2.0/auth/token/custom` API workflow. If you need additional help and assistance, contact ThoughtSpot Support. + +== Feature rollout + +To control the enablement and rollout of the ABAC via tokens feature, ThoughtSpot provides the following configuration settings: + +* `jwTokenFeatureEnabled` + +Enabled by default on all ThoughtSpot instances running 9.12.5.cl and later. It controls the availability of the beta version of the ABAC token workflow. +* `mandatoryTokenFilterFeatureEnabled` + +Disabled by default on ThoughtSpot instances. It controls the availability of the ABAC token generation method via `/api/rest/2.0/auth/token/custom` API endpoint. +* `honorJwTokenParametersFromBetaEndpoint` + +Enabled by default on all instances running 10.5.0.cl and later. This setting governs which API endpoint is used for ABAC token generation. When set to `true`, the ABAC implementation with the `/api/rest/2.0/auth/token/full` or `/api/rest/2.0/auth/token/object` API endpoint is explicitly chosen as the default JWT token method for the cluster, regardless of the status of the `mandatoryTokenFilterFeatureEnabled` flag. + +== User properties + +In the beta version of ABAC implementation with the V2.0 Get token APIs (`/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object`), security attributes are stored in the `user` > `user_parameters` object. To avoid ambiguity during the migration, ThoughtSpot uses a different user property to store security rules and other specifications defined via `/api/rest/2.0/auth/token/custom` API endpoint. For all ABAC implementation with the `/api/rest/2.0/auth/token/custom` API workflow, the user's security entitlement details are stored in the `user` > `access_control_properties` object as shown in this example: + +[source,JSON] +---- + +[ + { + "id": "...","name":"UserA","display_name":"User A","visibility":"SHARABLE", [...], + "extended_properties": null, + "extended_preferences": null, + "user_parameters": null, + "access_control_properties": { + "0": { + "ALL": { + "filter_rules": [ + { + "column_name": "Region", + "operator": "IN", + "values": [ + "West" + ] + }, + { + "column_name": "state", + "operator": "EQ", + "values": [ + "california" + ] + } + ], + "parameter_values": [] + } + } + } + } +] + +---- + +[IMPORTANT] +==== +* If the `persist` attribute is set as `true` for the beta version of the JWT tokens generated using the `/api/rest/2.0/auth/token/full` endpoint, it will be updated as `"persist_option": "REPLACE"` in the user's `access_control_properties` after migration. + +On instances running 10.4.0.cl, the persist option for the tokens generated using the `/api/rest/2.0/auth/token/custom` API appends new conditions by default, instead of replacing the existing rules. To replace the persisted attributes, set `persist_option=RESET` via a POST API call to `/api/rest/2.0/auth/token/custom`, and then send another API request with `persist_option=APPEND`. + +* The JWT tokens generated via `/api/rest/2.0/auth/token/custom` do not support runtime sorting. If there are any runtime sorting rules applied via JWT tokens generated from the `/api/rest/2.0/auth/token/full` API call, they will be ignored during migration. +==== + +== Migration steps + +This document assumes that you are currently using `/api/rest/2.0/auth/token/full` to create a JWT token to log in your users and to apply persisting security rules for user sessions in the `user_parameters` property of the user object. + +//// +=== Step 1: Verify the JWT token generation settings on your instance + +. Ensure that the `honorJwTokenParametersFromBetaEndpoint` flag is set to `true` on your ThoughtSpot instance. To check the status of this flag, send a `GET` request to the `/api/rest/2.0/system/config-overrides` API endpoint. + ++ +[source,JSON] +---- +{ + "config_override_info": { + "honorJwTokenParametersFromBetaEndpoint": { + "category": "MAIN", + "dataType": "BOOLEAN", + "description": "Flag to enable honoring of JWT Token where from Beta Endpoint.", + "current": false + } + } +} +---- + ++ +[IMPORTANT] +==== +If your ThoughtSpot instance is running 10.3.0.cl or earlier version, you must ensure that the `honorJwTokenParametersFromBetaEndpoint` is set to `true`. If this feature flag is not enabled on your instance, contact ThoughSpot Support before attempting to migrate your ABAC API workflow. +==== + +. Verify that you are using `POST /api/rest/2.0/auth/token/full` to generate tokens for ABAC for your users. +. Verify that your users have persisted data security values. To check this, send a `POST` request body with the user IDs or names to the `POST /api/rest/2.0/users/search` API endpoint and verify the persist property settings under `user_parameters` in the API response. + +//// + +=== Step 1: Enable the workflow with custom token API endpoint + +Create a ThoughtSpot Support request and ask for the JWT settings to be enabled on your instance. These settings will include the following: + +* A quick patch of your environment that adds the JWT flags to your instance. +* Enabling the `honorJwTokenParametersFromBetaEndpoint` setting to ensure that your current JWT setup is honored while you work on the migration steps. +* Setting the `mandatoryTokenFilterFeatureEnabled` attribute to `true` that allows you to set up security by default on the Worksheets or Models that you want to use for JWT security entitlements. + +=== Step 2: Flag columns whose data will be secured using the JWT endpoint. + +Navigate to your Worksheets / Models and set `is_mandatory_token_filter` to `true` on columns that you wish to secure via `filter_rules` set for ABAC. + +[.widthAuto] +[.bordered] +image:./images/worksheet-jwt-token-setting.png[Filter settings for ABAC token] + +For more information about `filter_rules`, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get tokens with custom rules and filter conditions]. + +=== Step 3: Familiarize with the custom token authentication endpoint + +After migration or upgrade to ThoughtSpot 10.4.0.cl or later, you'll need to use the `/api/rest/2.0/auth/token/custom` API endpoint to apply security entitlements via JWT authentication tokens. + +We recommend using the +++REST API v2 Playground+++ to familiarize yourself with the request payload and send test requests to demo users. Note that your production users will still be authenticated and secured via the `POST /api/rest/2.0/auth/token/full` endpoint until you complete the migration steps. + +=== Step 4: Create a script to migrate to the new endpoint + +Before creating a script, check the status of the `honorJwTokenParametersFromBetaEndpoint` flag on your instance: + +. Send a `GET` request to the `/api/rest/2.0/system/config-overrides` API endpoint. +The API returns the configuration override details in the response. +. Search for `honorJwTokenParametersFromBetaEndpoint` and check its current state. + ++ +[source,JSON] +---- +{ + "config_override_info": { + "honorJwTokenParametersFromBetaEndpoint": { + "category": "MAIN", + "dataType": "BOOLEAN", + "description": "Flag to enable honoring of JWT Token where from Beta Endpoint.", + "current": false + } + } +} +---- + +As long as the `honorJwTokenParametersFromBetaEndpoint` flag is set to `true`, the rules defined via tokens generated from the `POST /api/rest/2.0/auth/token/full` API call are applied to user profiles. +To apply the rules defined via `POST /api/rest/2.0/auth/token/custom` API endpoint, `honorJwTokenParametersFromBetaEndpoint` must be set to `false`. Therefore, we recommend creating a script with the following logic: + +* if `honorJwTokenParametersFromBetaEndpoint` is set to `true`, use the token generated via `POST /api/rest/2.0/auth/token/full` API call to authenticate your users. +* if the `honorJwTokenParametersFromBetaEndpoint` flag is set to `false`, use the token generated via `POST /api/rest/2.0/auth/token/custom` API call to authenticate your users. ++ +This ensures a smooth transition between the two endpoints that will automatically adjust when ThoughtSpot Support changes the flag for you. + +While we strongly recommend using a script to dynamically adjust the endpoint usage during the transition period, the following options are also available: + +Option 1:: + +Use `POST /api/rest/2.0/auth/token/full` until ThoughtSpot Support disables the `honorJwTokenParametersFromBetaEndpoint` setting. ++ +If your security rules change frequently, you may consider choosing Option 1. This option ensures that no data previously accessible to a user remains available to them longer than necessary. However, note that your users will see `No Data` for a period of time. + ++ +Choosing option 1 results in the following behavior: + +. As long as `honorJwTokenParametersFromBetaEndpoint` is set to `true`: + +Your users will be logged in with the data security entitlements assigned to the JWT token generated via `/api/rest/2.0/auth/token/full` endpoint, or via the data security rules persisted on the `user` > `user_parameters` object. +. When `honorJwTokenParametersFromBetaEndpoint` is set to `false`: + +Your users will see no data (assuming you secured your Worksheet/Model columns as described in xref:jwt-migration.adoc#_step_3_flag_columns_whose_data_will_be_secured_using_the_jwt_endpoint[Step 3]) until you switch to using the `POST /api/rest/2.0/auth/token/custom` endpoint. Your instance will start using this endpoint soon after the flag setting is switched. + +Option 2:: + +Use the `POST /api/rest/2.0/auth/token/custom` endpoint after logging a Support request to disable the `honorJwTokenParametersFromBetaEndpoint` setting. + ++ +If your security rules do not change often, consider using Option 2. For example, if the security rules defined via tokens generated from `POST /api/rest/2.0/auth/token/full` API call are the same as the rules that you plan to apply with tokens generated via `/api/rest/2.0/auth/token/custom`, you may start using the new endpoint. + ++ +Choosing option 2 results in the following behavior: + +. As long as `honorJwTokenParametersFromBetaEndpoint` is set to `true`: + +Your users will be logged in with the data security rules previously persisted on the `user` > `user_parameters` object (as ThoughtSpot still honors the security rules applied via `/api/rest/2.0/auth/token/full`). +. When `honorJwTokenParametersFromBetaEndpoint` is set to `false`: + +Your users will now be logged in ThoughtSpot and assigned security entitlements via the JWT token generated from the `POST /api/rest/2.0/auth/token/custom` API call and persisted on `access_control_properties` of the `user` object. + +=== Step 6: Switch your workflow to auth/token/custom endpoint + +After the transition period and when ThoughtSpot confirms that the `honorJwTokenParametersFromBetaEndpoint` setting is disabled on your instance, you can update your script and start using `/api/rest/2.0/auth/token/custom` endpoint. For more information about this endpoint, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get tokens with custom rules and filter conditions]. + + +== Additional resources + +Check the ABAC examples on the link:https://github.com/thoughtspot/ts_everywhere_resources/blob/master/examples/abac_with_token_auth/abac_test.html[ts_everywhere_resources GitHub Repo, window=_blank]. + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/pages/orgs.adoc b/modules/ROOT/pages/orgs.adoc index b8a5641bd..79685643f 100644 --- a/modules/ROOT/pages/orgs.adoc +++ b/modules/ROOT/pages/orgs.adoc @@ -89,8 +89,56 @@ If a cluster administrator wants to perform a Create, Read, Update, or Delete (C * The `Primary Org (Org 0)` is the default Org and cannot be deleted. * Each Org is identified by a unique name and ID, and can have its own users and groups. * Groups are unique to an Org and can be created only within the context of an Org. + +//// * A user can belong to multiple Orgs and can switch between the Org context. At any given time, a user can only access objects and data in the Org they have logged into. -* A user from one Org cannot share an object with the users of another Org. +* A user not having access to multiple Orgs cannot share an object with the users of another Org. +//// + +==== + +=== Orgs context for sharing links +A user belonging to multiple Orgs can share ThoughtSpot objects such as Liveboards and Answers, with users of another Org. This will require the object to have share permissions, and both users to be part of the parent Org of the shared object. + +==== Per Org URL + +[earlyAccess eaBackground]#Early Access# + +If the per Org URL feature is enabled on your ThoughtSpot instance, you can access shared objects such as Liveboards and Answers from multiple Orgs in different browser tabs. +For example, you can access a Liveboard from Org1 in one tab and open a shared object from Org2 in another browser tab. + +To enable this feature on your instance, contact link:https://community.thoughtspot.com/customers/s/contactsupport[ThoughSpot Support, window=_blank]. When this feature is enabled, the Org ID will be shown in the ThoughtSpot object URL as a query parameter, as shown in the following example: + +`\https://{ThoughtSpot-Host}/orgId=0/pinboard/22946f4b-b4ce-4643-be50-66afcd5177` + +//If you are embedding content from multiple Orgs, you can set the `overrideOrgId` property in the SDK, if the per Org URL feature is enabled on your instance. +For more information, see link:https://docs.thoughtspot.com/cloud/latest/orgs-overview#_all_org_scope[ThoughtSpot product documentation, window=_blank]. + + +==== Per Org custom embed URL (for custom link settings) + +[earlyAccess eaBackground]#Early Access# + +//With the current implementation, users belonging to multiple Orgs had to select the parent Org of a shared object from a list while trying to access it from a different Org. +Starting with ThoughtSpot Cloud 10.5.0.cl release, developers embedding ThoughtSpot in their application will be able to edit their custom link settings for their application users to allow seamless access to content from another different Org. For example, a user has +access to Org1, Org2 and Org3. While the user is logged in to Org1, they can access a Liveboard shared by another user in Org3 without using the Org switcher. + +This feature is turned off by default. To enable this feature on your instance, contact link:https://community.thoughtspot.com/customers/s/contactsupport[ThoughSpot Support, window=_blank]. When this feature is enabled, the Org ID will be passed as an additional query parameter in the `{ts-query-param}` in the URL. +For example, if you have set the custom link as: + +`\https://www.mysite.com/liveboard/{object-id}/?{ts-query-params}` + +The resulting URL will be: + +`\https://www.mysite.com/liveboard/22946f4b-b4ce-4643-be50-66afcd5177/orgId=0` + +The Org ID will passed in the URL depending on the placement of `{ts-query-params}` in the custom URL. + +//Customers can use this Org ID to access content between different Orgs by setting up the `overrideOrgId` in the SDK. + +[NOTE] +==== +The developers are advised to update their implementation to accommodate the Org ID in the `{ts-query-params}` while setting up the xref:https://developers.thoughtspot.com/docs/customize-links[custom links] for their application users. This will enable the users to seamlessly access ThoughtSpot objects across Orgs in a multi-Org setup, without causing any disruption to the current workflow. ==== == Feature availability on a multi-tenant instance diff --git a/modules/ROOT/pages/prerender.adoc b/modules/ROOT/pages/prerender.adoc index 05b32bd3a..25e7c4c0a 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -99,10 +99,10 @@ const offset = getOffset(placeholderDiv); //Move the renderer into those bounds renderDiv.style.opacity = 1; -renderDiv.style.top = offset.top; -renderDiv.style.left = offset.left; -renderDiv.style.width = coords.width; -renderDiv.style.height = coords.height; +renderDiv.style.top = offset.top + "px"; +renderDiv.style.left = offset.left + "px"; +renderDiv.style.width = coords.width + "px"; +renderDiv.style.height = coords.height + "px"; function getOffset(el) { var _x = 0; diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index b6cd6de78..144ea4938 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -36,6 +36,8 @@ ThoughtSpot Software: 10.1.0.sw ThoughtSpot Software: 10.7.0.sw |v2.10.0| ThoughtSpot Cloud: 10.4.0.cl + ThoughtSpot Software: 10.7.0.sw +|v2.11.0| ThoughtSpot Cloud: 10.5.0.cl + +ThoughtSpot Software: 10.7.0.sw |==== For information about new features, breaking changes, and deprecated parameters, see xref:rest-apiv2-changelog.adoc[API changelog]. diff --git a/modules/ROOT/pages/rest-apiv1-changelog.adoc b/modules/ROOT/pages/rest-apiv1-changelog.adoc index f4e116849..864811c14 100644 --- a/modules/ROOT/pages/rest-apiv1-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv1-changelog.adoc @@ -12,7 +12,6 @@ This changelog lists only the changes introduced in REST API v1. For information TML import:: The TML import API allows setting the `skip_cdw_validation_for_tables` property to specify if the Cloud Data Warehouse (CDW) validation checks for Table TMLs should be skipped. - + For more information, see xref:tml-api.adoc#import[TML import]. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 75166433d..c3bc89291 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,48 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 10.5.0.cl, December 2024 + +=== Custom access token API +The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: + +* `auto_create` + +Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. +* `REPLACE` enum for `persist_option` + +Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +=== TML import APIs + +TML async import:: + +The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: ++ +* `import_policy` + +Allows you specify if all objects should be imported during the TML import operation. Valid values are: + +** `PARTIAL_OBJECT` (default) +** `PARTIAL` +** `VALIDATE_ONLY` +** `ALL_OR_NONE` + +* `enable_large_metadata_validation` + +Indicates if the TMLs with large and complex metadata should be validated before the import. ++ +For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +//// +* `skip_diff_check` + +Allows skipping checks that find differences in TML content before processing TML objects for import. +//// + +TML import API:: + +The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. + +Share metadata:: + +The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. + == Version 10.4.0.cl, November 2024 === New API endpoints @@ -63,13 +105,6 @@ You can specify the following attributes in TML import requests to `/api/rest/2. * `skip_cdw_validation_for_tables` + Indicates if the Cloud Data Warehouse (CDW) validation for table imports should be skipped. -//// -* `skip_diff_check` + -Allows skipping diff checks before processing TML objects for import. -* `enable_large_metadata_validation` + -Indicates if the TMLs with large and complex metadata should be validated before the import. -//// - Report API:: The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index c2f87a0d7..ffbe26279 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -30,10 +30,7 @@ To avoid this issue, ThoughtSpot recommends the following: * Use cookieless authentication in your production environments. Developers can use either xref:embed-authentication.adoc#embedSSO[`AuthType.EmbeddedSSO`] or xref:trusted-auth-sdk.adoc[`AuthType.TrustedAuthTokenCookieless`] based on their embedding setup. * If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see link:https://docs.thoughtspot.com/cloud/latest/custom-domains[Custom domain configuration, window=_blank]. - -//// * If you are using authentication methods that rely on cookies, xref:_enable_partition_cookies[enable partition cookies]. -//// == Add domains to CSP and CORS allowlists @@ -199,6 +196,26 @@ a|+++Wildcard (*) for port+++ |==== -- +== Block access to non-embedded ThoughtSpot pages +If you have embedded ThoughtSpot content in your app, you may want your users to access only the ThoughtSpot pages embedded within the context of your host app. ThoughtSpot allows administrators to restrict user access to non-embedded application pages from the embedding application context or selectively grant access to specific user groups. For information, see xref:selective-user-access.adoc[Control User Access]. + +== Enable partitioned cookies +Many web browsers do not allow third-party cookies. If you are using authentication methods that rely on cookies, users will not be able to access the embedded content when browsers block third-party cookies. Therefore, ThoughtSpot recommends using xref:trusted-auth-sdk.adoc[cookieless authentication] in production environments. + +However, if your implementation uses cookie-based authentication or xref:embed-authentication.adoc#none[AuthType.None], ensure that you enable partitioned cookies: + +. On your ThoughtSpot application instance, go to *Develop* > *Customizations* > *Security settings*. +. Click *Edit*. +. Turn on the *Enable partitioned cookies* toggle switch. +. Click *Save changes*. + +With partitioned cookies enabled, when a user logs in to ThoughtSpot and accesses embedded content on a host application, a cookie is set with the partitioned attribute. On browsers supporting partitioned cookies, the partitioned cookie will persist in the app after a successful login. + +[IMPORTANT] +==== +Safari blocks all third-party cookies and does not support partitioned cookies. You can switch to a different browser that supports partitioned cookies, or use cookieless authentication in your embedding implementation. +==== + == Add permitted iFrame domains Some features in ThoughtSpot, such as link:https://docs.thoughtspot.com/software/latest/liveboard-notes[Liveboard Note tiles, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/chart-custom[custom charts, window=_blank], allow iFrame content. If you are planning to embed content from an external site, make sure the domain URLs of these sites are added to the iFrame domain allowlist: @@ -207,8 +224,4 @@ Some features in ThoughtSpot, such as link:https://docs.thoughtspot.com/software . In the *Permitted iFrame domains* text box, add the domain URL of the website or portal that you want to use for iFrame content. . Click *Save changes*. -== Block access to non-embedded ThoughtSpot pages -If you have embedded ThoughtSpot content in your app, you may want your users to access only the ThoughtSpot pages embedded within the context of your host app. ThoughtSpot allows administrators to restrict user access to non-embedded application pages from the embedding application context or selectively grant access to specific user groups. For information, see xref:selective-user-access.adoc[Control User Access]. - - diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index c3340d1bb..020fe18a7 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -96,7 +96,7 @@ __Optional__ |__Boolean__. Specify if import operation must be run for all Orgs __Requires Org administration privileges to access TML objects across all Orgs.__| `false` -|`import_policy` a|__String__. Policy to follow during import. The allowed values are: +|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: * `PARTIAL` + Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. @@ -110,16 +110,16 @@ Imports objects that validate successfully and skips the objects that do not val |`skip_cdw_validation_for_tables` + __Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` + +|`enable_large_metadata_validation` + +__Optional__ + |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. |`false` |==== //// |`skip_diff_check` + __Optional__ -10.6.0.cl |__Boolean__. Skips diff check before processing TMLs for imports. |`false` -|`enable_large_metadata_validation` + -__Optional__ -10.5.0.cl |__Boolean__. Enables validation for large metadata objects. |`false` +|__Boolean__. Skips diff check before processing TMLs for imports. |`false` //// - ==== Example request [source,cURL] @@ -201,10 +201,21 @@ __Optional__ |__Boolean__. Specify whether to include import response in the ta __Optional__ |__Integer__. The offset point, starting from where the task status should be included in the response. | `0` |`record_size` + -__Optional__ |__Integer__. The number of task statuses to include in the -response starting from offset position. | `5` +__Optional__ a|__Integer__. The number of task statuses to include in the +response starting from offset position. + +[NOTE] +==== +The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. +==== +| `5` |==== +[IMPORTANT] +==== +You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. +==== + ==== Example request [source,cURL] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index b03458cf1..7915a96ac 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,65 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 10.5.0.cl + +=== Default search experience on embedded ThoughtSpot Home page + +If your ThoughtSpot instance is upgraded from 10.1.0.cl to 10.5.0.cl, the Natural Language Search interface will be the default search experience on the embedded ThoughtSpot Home page. The split search experience, which was introduced in 10.3.0.cl, will be turned off by default on these instances. For applications embedding full ThoughtSpot experience, the `isUnifiedSearchExperienceEnabled` property will be set to `true` in the Visual Embed SDK. Your application users can continue to use the unified experience until it is deprecated. However, developers can choose to disable the unified search experience and customize the Home page search experience for their application users. + +On instances upgraded from 10.3.0.cl or 10.4.0.cl to 10.5.0.cl, Object Search will be the default search experience on the embedded ThoughtSpot Home page. The unified search experience will be disabled by default and the `isUnifiedSearchExperienceEnabled` property in the Visual Embed SDK will be set to `false`. If required, developers can switch to AI Search experience by setting the `homePageSearchBarMode` property to `aiAnswer`. + +For more information, see xref:full-app-customize.adoc#_search_experience_on_home_page[Home page search experience customization]. + +=== Support for partitioned cookies +With most web browsers blocking third-party cookies, cookies will no longer be shared across the ThoughtSpot +embedded pages and the host application, or other tabs in the browser. If your embed no longer functions without the use of third-party cookies, consider using one of the following options: + +* Update your implementation to use cookieless authentication; for example, `AuthType.EmbeddedSSO` or `AuthType.TrustedAuthTokenCookieless` (Recommended) +* Customize the domain of your ThoughtSpot instance to match the domain of your host application. + +For more information, see xref:custom-domain-configuration.adoc[Custom domain configuration]. +* Enable partitioned cookies on your ThoughtSpot instance. + +If your implementation relies on cookies or if you are using `AuthType.None` in your development and test environments, ThoughtSpot administrators have the option to enable partitioned cookies on their instance. With partitioned cookies, you can restrict cookie sharing between different sites and thus prevent cross-site tracking. ++ +On browsers that support partitioned cookies, the session cookie will persist in the ThoughtSpot app after a successful login. When using the `AuthType.None` embed authentication method in development or test environments with partitioned cookies, users must log in to their ThoughtSpot instance using basic authentication for seamless access to the embed. + ++ +[NOTE] +==== +Safari blocks all third-party cookies and does not support partitioned cookies. ThoughtSpot recommends switching to a Web browser that supports partitioned cookies or using cookieless authentication. +==== + +For more information, see xref:security-settings.adoc#_enable_partitioned_cookies[Security Settings]. + +=== ABAC via tokens implementation changes + +The ABAC via tokens feature is GA in 10.5.0.cl. Several changes have been introduced since the ThoughtSpot 10.4.0.cl release to improve the ABAC configuration workflows: + +* The `user_parameters` property in `auth/token/full` and `auth/token/object` APIs used for the xref:abac-user-parameters-beta.adoc[beta implementation of ABAC] was deprecated in 10.4.0.cl. +* Starting from 10.4.0.cl, administrators are advised to xref:abac-user-parameters.adoc[use the `/api/rest/2.0/auth/token/custom` API endpoint] to define security attributes for ABAC implementation. + +If you have implemented ABAC using `auth/token/full` or `auth/token/object` API endpoints and your cluster is upgraded to 10.4.0.cl or 10.5.0.cl, you can migrate your implementation to start using the `/api/rest/2.0/auth/token/custom` API endpoint. For more information, refer to xref:jwt-migration.adoc[ABAC migration guide]. + +=== Orgs context for custom links +Starting with ThoughtSpot Cloud 10.5.0.cl release, developers embedding ThoughtSpot in their application can include the Org context in ThoughtSpot URLs using custom link settings. +//For instance, being able to seamlessly access content from a different Org, while being logged in another Org. + +This feature is turned off by default. To enable this feature on your ThoughtSpot instance, contact link:https://community.thoughtspot.com/customers/s/contactsupport[ThoughSpot Support, window=_blank]. For more information, see xref:orgs.adoc[Orgs context for sharing links]. + +=== Migration to IAMv2 +All new ThoughtSpot application instances are enabled with enhanced Identity and Access Management (IAMv2). The existing ThoughtSpot embedded instances will be migrated to IAMv2 during the maintenance windows. + +* To ensure a seamless migration, review and follow the link:https://docs.thoughtspot.com/cloud/latest/okta-iam#_before_migrating_to_iam_v2[steps in the ThoughtSpot product documentation, window=_blank]. +* To understand changes to the API endpoints with this upgrade, see xref:https://developers.thoughtspot.com/docs/api-user-management#_user_migration_to_iamv2[User migration to IAMv2] +* For more information, see link:https://docs.thoughtspot.com/cloud/latest/okta-iam[Identity and Access Management V2, window=_blank]. + +=== Visual Embed SDK + +For information about the new features and enhancements introduced in Visual Embed SDK version 1.35.x, see xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API +For information about REST API enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + == Version 10.4.0.cl === Spotter AI for conversational analytics @@ -162,16 +221,16 @@ For information about deprecated features, see xref:deprecated-features.adoc[Dep .New home page and navigation [earlyAccess eaBackground]#Early Access# [%collapsible] ==== -The new navigation and homepage experience is now available for ThoughtSpot users. +The new navigation and Home page experience is now available for ThoughtSpot users. -ThoughtSpot administrators can enable this feature on their application instance on the **Admin** page. If the new navigation and homepage experience is enabled on your instance, users can turn on the New Experience mode on their *Profile* settings page. +ThoughtSpot administrators can enable this feature on their application instance on the **Admin** page. If the new navigation and Home page experience is enabled on your instance, users can turn on the New Experience mode on their *Profile* settings page. -On embedding apps, the new navigation and homepage experience is disabled by default. To enable it, you must set the `modularHomeExperience` property to `true` in the `AppEmbed` component. +On embedding apps, the new navigation and Home page experience is disabled by default. To enable it, you must set the `modularHomeExperience` property to `true` in the `AppEmbed` component. -The new navigation and homepage experience introduces the following notable changes: +The new navigation and Home page experience introduces the following notable changes: * The top navigation menu bar is replaced with an app selector image:./images/app_switcher.png[the app switcher menu] that allows users to switch between different apps. -* The **Insights** module presents a redesigned homepage with modular content and a left navigation panel. Users can navigate to Liveboards, Answers, SpotIQ Analysis, and Monitor Subscriptions pages from the homepage by using the left navigation menu options. +* The **Insights** module presents a redesigned Home page with modular content and a left navigation panel. Users can navigate to Liveboards, Answers, SpotIQ Analysis, and Monitor Subscriptions pages from the Home page by using the left navigation menu options. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. ==== diff --git a/src/components/Document/index.scss b/src/components/Document/index.scss index 87fcb9f7c..0f4decf5d 100644 --- a/src/components/Document/index.scss +++ b/src/components/Document/index.scss @@ -50,7 +50,7 @@ img { width: 100%; - margin: 10px; + margin: 0 5px 0 5px; } pre { diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 92048bc90..cd6805cb9 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,7 +35,7 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.4.0.cl', + label: '10.5.0.cl', link: ' ', subLabel: 'Cloud (Latest)', }, diff --git a/static/doc-images/images/auth-type-embed.png b/static/doc-images/images/auth-type-embed.png index 6c7b2c1d0..4fa8bec2e 100644 Binary files a/static/doc-images/images/auth-type-embed.png and b/static/doc-images/images/auth-type-embed.png differ diff --git a/static/doc-images/images/check_parameter_definition.png b/static/doc-images/images/check_parameter_definition.png index 7bd5eb969..30d68248b 100644 Binary files a/static/doc-images/images/check_parameter_definition.png and b/static/doc-images/images/check_parameter_definition.png differ diff --git a/static/doc-images/images/parameter_with_default.png b/static/doc-images/images/parameter_with_default.png index af91bcd2d..8ef933a56 100644 Binary files a/static/doc-images/images/parameter_with_default.png and b/static/doc-images/images/parameter_with_default.png differ diff --git a/static/doc-images/images/spotter-fullApp.png b/static/doc-images/images/spotter-fullApp.png new file mode 100644 index 000000000..69fad9963 Binary files /dev/null and b/static/doc-images/images/spotter-fullApp.png differ diff --git a/static/doc-images/images/worksheet-jwt-token-setting.png b/static/doc-images/images/worksheet-jwt-token-setting.png new file mode 100644 index 000000000..3418cd85f Binary files /dev/null and b/static/doc-images/images/worksheet-jwt-token-setting.png differ diff --git a/static/doc-images/images/worksheet_edit_sidebar.png b/static/doc-images/images/worksheet_edit_sidebar.png index 18044927e..f13ddd8fa 100644 Binary files a/static/doc-images/images/worksheet_edit_sidebar.png and b/static/doc-images/images/worksheet_edit_sidebar.png differ diff --git a/static/doc-images/images/worksheet_formula.png b/static/doc-images/images/worksheet_formula.png index cac27188d..175adbbbd 100644 Binary files a/static/doc-images/images/worksheet_formula.png and b/static/doc-images/images/worksheet_formula.png differ