Alternatively, you can configure and enable tag-based row-level security on your dataset by calling the CreateDataSet or UpdateDataSet API operation. Use the following examples to learn how.
CreateDataSet
The following is an example for creating a dataset that uses RLS with tags. It assumes the scenario of the logistics company described previously. The tags are defined in the row-level-permission-tag-configuration element. The tags are defined on the columns that you want to secure the data for. For more information about this optional element, see RowLevelPermissionTagConfiguration in the Amazon QuickSight API Reference.
create-data-set
"Status": "ENABLED", "TagRules":
[ {
"TagKey": "tag_retailer_id", "ColumnName": "retailer_id", "TagMultiValueDelimiter": ",", "MatchAllValue": "*"
The tags in this example are defined in the TagRules part of the element. In this example, two tags are defined based on two columns:
• The tag_retailer_id tag key is defined for the retailer_id column. In this case for the logistics company, this sets row-level security based on the retailer that's accessing the application.
• The tag_role tag key is defined for the role column. In this case for the logistics company, this sets an additional layer of row-level security based on the role of the user accessing your application from a specific retailer. An example is store_supervisor or manager.
For each tag, you can define TagMultiValueDelimiter and MatchAllValue. These are optional.
• TagMultiValueDelimiter – This option can be any string that you want to use to delimit the values when you pass them at runtime. The value can be 10 characters long, at most. In this case, a comma is used as the delimiter value.
• MatchAllValue – This option can be any character that you want to use when you want to filter by all the values in that column in the dataset. Instead of listing the values one by one, you can use the character. If specified, this value can be at least one character, or at most 256 characters long. In this case, an asterisk is used as the match all value.
While configuring the tags for dataset columns, turn them on or off using the mandatory property Status. For enabling the tag rules use the value ENABLED for this property. By turning on tag rules, you can use them to set tag values at runtime, described in Step 2: Assign values to RLS tags at runtime (p. 113).
The following is an example of the response definition.
{
You can use the UpdateDataSet API operation to add or update RLS tags for an existing dataset.
The following is an example of updating a dataset with RLS tags. It assumes the scenario of the logistics company described previously.
Using tag-based rules
"TagKey": "tag_retailer_id", "ColumnName": "retailer_id", "TagMultiValueDelimiter": ",", "MatchAllValue": "*"
The following is an example of the response definition.
{ "Status": 201,
After tags are assigned and enabled on the dataset, make sure to give QuickSight authors permissions to see any of the data in the dataset when authoring a dashboard.
To give QuickSight authors permission to see data in the dataset, create a permissions file or query to use as dataset rules. For more information, see Creating dataset rules for row-level security (p. 105).
For more information about the RowLevelPermissionTagConfiguration element, see RowLevelPermissionTagConfiguration in the Amazon QuickSight API Reference.
Step 2: Assign values to RLS tags at runtime
You can use tags for RLS only for anonymous embedding. You can set values for tags using the GenerateEmbedUrlForAnonymousUser API operation.
The following example shows how to assign values to RLS tags that were defined in the dataset in the previous step.
“Namespace”: “string”, // The namespace to which the anonymous end user virtually belongs “SessionTags”: // Optional: Can be used for row-level security
[ {
“Key”: “tag_retailer_id”, “Value”: “West,Central,South”
}
],
“ExperienceConfiguration”:
{ “Dashboard”:
{
“InitialDashboardId”: “string”
// This is the initial dashboard ID the customer wants the user to land on. This ID goes in the output URL.
} } }
The following is an example of the response definition.
HTTP/1.1 Status
Content-type: application/json { "EmbedUrl": "string",
"RequestId": "string"
}
RLS support without registering users in QuickSight is supported only in the
GenerateEmbedUrlForAnonymousUser API operation. Any new features for anonymous embedding are planned to be added to this operation only. In this operation, under SessionTags, you can define the values for the tags associated with the dataset columns.
In this case, the following assignments are defined:
• Values West, Central, and South are assigned to the tag_retailer_id tag at runtime. A comma is used for the delimiter, which was defined in TagMultipleValueDelimiter in the dataset. To use call values in the column, you can set the value to *, which was defined as the MatchAllValue when creating the tag.
• The value shift_manager is assigned to the tag_role tag.
The user using the generated URL can view only the rows having the shift_manager value in the role column. That user can view only the value West, Central, or South in the retailer_id column.
For more information about embedding dashboards for anonymous users using the GenerateEmbedUrlForAnonymousUser API operation, see ??? (p. 736), or GenerateEmbedUrlForAnonymousUser in the Amazon QuickSight API Reference