Using Row-Level Security (RLS) with Tags to Restrict Access to a Dataset When Embedding Dashboards for Anonymous Users - Amazon QuickSight

Using Row-Level Security (RLS) with Tags to Restrict Access to a Dataset When Embedding Dashboards for Anonymous Users

 Applies to: Enterprise Edition 
   Intended audience: Amazon QuickSight developers 

When you embed Amazon QuickSight dashboards in your application for users who are not provisioned (registered) in QuickSight, you can use row-level security (RLS) with tags to specify which data your users can see in the dashboard depending on who they are.

For example, let's say you're a logistics company who has a customer-facing application for various retailers. Thousands of users from these retailers access your application to see metrics related to how their orders are getting shipped from your warehouse. You don't want to manage thousands of users in QuickSight, so you use anonymous embedding to embed the selected dashboards in your application that your authenticated and authorized users can see. However, you want to make sure retailers see only data that is for their business and not for others. You can use RLS with tags to make sure your customers only see data that's relevant to them.

To do so, complete the following steps:

  1. Add RLS tags to a dataset using the CreateDataSet or UpdateDataSet API operation.

  2. Assign values to those tags at runtime using the GenerateEmbedUrlForAnonymousUser API operation.

Before you can use RLS with tags, keep in mind the following points:

  • Using RLS with tags is currently only supported for anonymous embedding, specifically for embedded dashboards that use the GenerateEmbedUrlForAnonymousUser API operation.

  • Using RLS with tags isn't supported for embedded dashboards that use the GenerateEmbedURLForRegisteredUser API operation or the old GetDashboardEmbedUrl API operation.

  • RLS tags are not supported with IAM or the QuickSight identity type.

Step 1: Add RLS Tags to a Dataset

You can configure and enable 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.

create-data-set --aws-account-id <value> --data-set-id <value> --name <value> --physical-table-map <value> [--logical-table-map <value>] --import-mode <value> [--column-groups <value>] [--field-folders <value>] [--permissions <value>] [--row-level-permission-data-set <value>] [--column-level-permission-rules <value>] [--tags <value>] [--cli-input-json <value>] [--generate-cli-skeleton <value>] [--row-level-permission-tag-configuration '{ "Status": "ENABLED", "TagRules": [ { "TagKey": "tag_retailer_id", "ColumnName": "retailer_id", "TagMultiValueDelimiter": ",", "MatchAllValue": "*" }, { "TagKey": "tag_role", "ColumnName": "role" } ] }' ]

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. For example, 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, enable or disable them using the mandatory property Status. For enabling the tag rules use the value ENABLED for this property. By enabling tag rules, you can use them to set tag values at runtime, described in Step 2: Assign Values to RLS Tags at Runtime.

The following is an example of the response definition.

{ "Status": 201, "Arn": "arn:aws:quicksight:us-west-2:11112222333:dataset/RLS-Dataset", "DataSetId": "RLS-Dataset", "RequestId": "aa4f3c00-b937-4175-859a-543f250f8bb2" }

UpdateDataSet

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.

update-data-set --aws-account-id <value> --data-set-id <value> --name <value> --physical-table-map <value> [--logical-table-map <value>] --import-mode <value> [--column-groups <value> [--field-folders <value>] [--row-level-permission-data-set <value>] [--column-level-permission-rules <value>] [--cli-input-json <value>] [--generate-cli-skeleton <value>] [--row-level-permission-tag-configuration '{ "Status": "ENABLED", "TagRules": [ { "TagKey": "tag_retailer_id", "ColumnName": "retailer_id", "TagMultiValueDelimiter": ",", "MatchAllValue": "*" }, { "TagKey": "tag_role", "ColumnName": "role" } ] }' ]

The following is an example of the response definition.

{ "Status": 201, "Arn": "arn:aws:quicksight:us-west-2:11112222333:dataset/RLS-Dataset", "DataSetId": "RLS-Dataset", "RequestId": "aa4f3c00-b937-4175-859a-543f250f8bb2" }
Important

Once tags are assigned and enabled on the dataset, QuickSight authors must be given 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.

Step 2: Assign Values to RLS Tags at Runtime

Tags for RLS can only be used 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.

POST /accounts/AwsAccountId/embed-url/anonymous-user HTTP/1.1 Content-type: application/json { “AwsAccountId”: “string”, “SessionLifetimeInMinutes”: integer, “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” } { “Key”: “tag_role”, “Value”: “shift_manager” } ], “AuthorizedResourceArns”: [ “string” ], “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 by using the GenerateEmbedUrlForAnonymousUser API operation. In this API 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, and the value West, Central, or South in the retailer_id column.