Merge pull request #249 from thoughtspot/jwt-doc-fixes

review comments

Author: ShashiSubramanya

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

@@ -36,17 +36,15 @@ Binds a single value to any Parameter in any Worksheet or Model by Parameter Nam
 [IMPORTANT]
 ====
 [#column-name-warning]
-The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name the values will not bind to any column. 
-
-You must coordinate between the team that maintains the Worksheets and Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] if any changes will be made to a Model or Worksheet.
-
-For the same reasons, end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens.
+The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name the values will not bind to any column. You must coordinate between the team that maintains the Worksheets and Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] if any changes will be made to a Model or Worksheet.
+For the same reasons, the end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens.
+When column names change, ensure that the `is_mandatory_token_filter: true` property is set on every column where a filter rule is expected.
 ====
 
 The request for a token with ABAC details can xref:abac-user-parameters.adoc#persistForUser[persist] the set of filters and Parameter values to user sessions within ThoughtSpot, after which all sessions and scheduled reports will use the persisted values until they are changed by another token generation request.
 
 == Token request
-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*.
+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]
 ====
@@ -119,6 +117,12 @@ When using a `persist_option` other than `NONE`, the *filter_rules* and *paramet
 
 Persisted values for a user are used by ThoughtSpot for any scheduled reports, as well as when no other token is provided.
 
+[IMPORTANT]
+====
+* 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.
+* Note that the stored properties of the user are updated when the token request is successful, rather than at the first use of the token.
+====
+
 The `persist_option` has the following possible values :
 
 [cols="1,1,2"]
@@ -148,8 +152,6 @@ In 10.4.0.cl, the `REPLACE` behavior can be achieved by making a `RESET` request
 ====
 |=====
 
-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.
-
 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.
 
 [cols="1,1,2"]
@@ -160,6 +162,10 @@ Filters and parameters must be *persisted* for them to apply to user sessions wh
 |Cookieless Trusted Authentication
 |Attributes assigned to the token override the user's access control properties, without updating the user object.
 
+|`NONE`
+|Cookie-based Trusted Authentication
+|Attributes assigned to the token will not be considered. The user logs in using a session cookie and  the properties from the previous session persist.
+
 |`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
@@ -173,8 +179,6 @@ Filters and parameters must be *persisted* for them to apply to user sessions wh
 |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

modules/ROOT/pages/jwt-migration.adoc

@@ -146,7 +146,7 @@ The API returns the configuration override details in the response.
       "category": "MAIN",
       "dataType": "BOOLEAN",
       "description": "Flag to enable honoring of JWT Token where from Beta Endpoint.",
-      "current": false
+      "current": true
     }
   }
 }
@@ -174,7 +174,7 @@ 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.
+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 should start using this endpoint soon after the flag setting is switched.
 
 Option 2::