10-15-0-docs

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

@@ -1,76 +1,63 @@
-= ABAC via tokens
+= ABAC via tokens (Legacy method)
 :toc: true
-:toclevels: 3
+:toclevels: 2
 
 :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
 
-In Attribute-Based Access Control (ABAC) implementation, security entitlements are sent in as lists of attributes at session creation time via the authentication service.
-
-This article provides a detailed overview of the ABAC implementation via tokens for row-level security (RLS), and lists configuration recommendations, and best practices.
+ThoughtSpot's Attribute-Based Access Control (ABAC) implementation allows administrators to send user-specific security entitlements as attributes at session creation via JSON Web Token (JWT) tokens.
 
 [IMPORTANT]
 ====
-The ABAC feature is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support.
+The ABAC feature is disabled by default on ThoughtSpot instances. To implement ABAC with data security in ThoughtSpot, refer to the instructions in the xref:abac_rls-variables.adoc[ABAC via RLS with  template variables] documentation.
 ====
 
+== Overview
 
-// * 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.
-// * The  +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">Custom access token </a>+++ REST API endpoint.
-
-
-== Configuration recommendations and best practices
-
-Before you begin, note the following recommendations and feature limitations:
+To generate JWT tokens for ABAC implementation, you must use the `/api/rest/2.0/auth/token/custom` REST API endpoint.
 
-Indexing::
-Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in Explore mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token.
- +
-You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS, or also include an RLS Rule on fields that must also be filtered for the Indexing system.
-
-////
-+
 [NOTE]
 ====
-ABAC rules are not supported on Liveboards with AI Highlights and Change Analysis features, and on the Answers generated from Spotter.
+* To pass different data contexts, based on the data slices that your users are allowed to visualize, use runtime filters and Parameters. These features are designed to keep your embedded ThoughtSpot content in sync with the context of host application.
+* Runtime filters and runtime parameters are not security features. For data security, use xref:rls-rules.adoc[RLS rules].
 ====
-////
 
-Mandatory token filters::
-When setting filter rules within the token, you must 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.
+To create an easier implementation of data security for your application users, ThoughtSpot recommends using RLS rules with system variables such as `ts_username` or `ts_groups`, or by using xref:abac_rls-variables.adoc[custom variable references] whose values can be assigned to users as login tokens.
 
-+
-[NOTE]
-====
-On instances running 10.5.0.cl and 10.4.0.cl versions, if a column is set as hidden (`is_hidden: true`), the `is_mandatory_token_filter: true` setting will not be applied to the column. Due to this, the user may see no data. To work around this issue, we recommend upgrading your instance to 10.6.0.cl. On versions lower than 10.6.0.cl, ensure that you set the `is_hidden` parameter to `false` on the column before applying filter rules.
-====
+=== ABAC attributes
 
-[#column-name-warning]
-Column names in Worksheet/ Model::
-The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name, or the values will not bind to any column. You must coordinate between the team that maintains the Worksheets or Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model or Worksheet. +
-For the same reasons, the end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens. +
-Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data gets returned for users when column names change.
+Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups:
 
-API for token generation::
-The ABAC via tokens feature in ThoughtSpot 10.4.0.cl and later versions involves generating a token with filter rules and parameter values using the +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fauthentication%2Fget-custom-access-token">auth/token/custom</a>+++ API endpoint. Customers using 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].
+* Filter rules +
+This method uses xref:runtime-filters.adoc[runtime filters] (`filter_rules`) in the token to create data security rules. It can filter multiple values of any data type and binds to any Column in any Model with a matching column name in ThoughtSpot.
 
+* Parameter values +
+This method uses xref:runtime-parameters.adoc[runtime Parameters] (`parameter_values`) in the token to create data security rules. It binds a single value to any Parameter in any Model by Parameter Name and Type match. Parameters can be used in *Formulas* and then as *Filters* in  Models.
 
-== ABAC attributes
+=== Mandatory token filters
 
-Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups:
+The `is_mandatory_token_filter: true` setting in object TML enforces that a filter rule must be provided for a specific column. When this attribute is set on a column in a Model, ThoughtSpot will deny all data access for users who do not have a corresponding filter rule for that column in their ABAC token.
 
-* 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).
+When setting filter rules within the token, you must place the `is_mandatory_token_filter: true` property on every column in a Model where a filter rule is expected. This setting will deny any access to data if a user has not been assigned values for the expected set of fields.
 
-* 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*.
+[#column-name-warning]
+The filter rules require passing the *exact* column name as defined in the Model. Otherwise, the values will not bind to any column. You must coordinate between the team that maintains the data objects and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model and to ensure column names remain consistent. +
+For this reason, end users of an embedded app must not be granted edit access to any Model using ABAC rules via tokens. Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data is returned for users when column names change.
+
+[NOTE]
+====
+If a column is set with both `is_hidden: true` and `is_mandatory_token_filter: true`, and filter conditions for that column are defined in the ABAC token, the filter will be applied as expected. The column will be hidden from the user interface, but the mandatory filter requirement will still be enforced, and data will be shown according to the filter values provided in the token.
+====
+
+=== Indexing
+Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in *Explore* mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. This means the indexed columns may expose values in search suggestions or autocompletion that a user should not see, even if ABAC filters would block access to the underlying data. To prevent this, you can do one of the following:
 
-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.
+- Disable indexing for columns and fields that must be restricted by ABAC. You may also want to disable indexing on all sensitive columns.
+- Define an RLS rule on those fields, since RLS is enforced at the indexing layer and will secure suggestions and sample values.
 
 == Token request
-The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format. This token can be used as a bearer token for Cookieless trusted authentication or REST API access. You can also use it as a sign-in token to create a session, in which case, we recommend that the ABAC user properties be  *persisted*, to ensure scheduled exports remain secure after the session ends.
+The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format. This token can be used as a bearer token for Cookieless trusted authentication or REST API access. You can also use it as a sign-in token to create a session, in which case, we recommend that the ABAC user properties be *persisted*, to ensure scheduled exports remain secure after the session ends.
 
 [NOTE]
 ====
@@ -455,24 +442,6 @@ An example workflow might be:
 4. Worksheets that need these entitlements use the combination of pass-through function with parameter + formula + filter so that all queries in ThoughtSpot include a WHERE clause with the sub-select.
 
 == 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.
-
-For indexing recommendations, see xref:abac-user-parameters.adoc#_configuration_recommendations_and_best_practices[Configuration recommendations and best practices].
-
-////
-* 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.
-
-
-// * 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 ABAC via tokens method requires using xref:trusted-authentication.adoc[trusted authentication], and using Worksheets or Models 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.
+For indexing recommendations, see xref:abac-user-parameters.adoc#_indexing[Indexing].