Using row-level security (RLS) with tag-based rules to restrict access to a dataset when embedding dashboards for anonymous users - Amazon QuickSight

Using row-level security (RLS) with tag-based rules to restrict access to a dataset when embedding dashboards for anonymous users

 Applies to: Enterprise Edition 
   Intended audience: Amazon QuickSight Administrators and 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. In this case, you use 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 that 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.

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

    For more information about embedding dashboards for anonymous users using the GenerateEmbedUrlForAnonymousUser API operation, see Embedding QuickSight data dashboards for everyone.

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 aren't supported with AWS Identity and Access Management (IAM) or the QuickSight identity type.

Step 1: Add RLS tags to a dataset

You can add tag-based rules to a dataset in Amazon QuickSight. Alternatively, you can call the CreateDataSet or UpdateDataSet API operation and add tag-based rules that way. For more information, see Add RLS tags to a dataset using the API.

Use the following procedure to add RLS tags to a dataset in QuickSight.

To add RLS tags to a dataset

  1. From the QuickSight start page, choose Datasets at left.

  2. On the Datasets page, choose the dataset that you want to add RLS to.

  3. Choose Row-level security.

    
										Image of the row-level security button when you choose a dataset on the dataset page.
  4. On the Set up row-level security page that opens, choose Tag-based rules.

  5. For Column, choose a column that you want to add tag rules to.

    For example, in the case for the logistics company, the retailer_id column is used.

    Only columns with a string data type are listed.

  6. For Tag, enter a tag key. You can enter any tag name that you want.

    For example, in the case for the logistics company, the tag key tag_retailer_id is used. Doing this sets row-level security based on the retailer that's accessing the application.

  7. (Optional) For Delimiter, choose a delimiter from the list, or enter your own.

    You can use delimiters to separate text strings when assigning more than one value to a tag. The value for a delimiter can be 10 characters long, at most.

  8. (Optional) For Match all, choose the *, or enter your own character or characters.

    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 this value is specified, it can be at least one character, or at most 256 characters long

  9. Choose Add.

    The tag rule is added to the dataset and is listed at bottom, but it's not applied yet. To add another tag rule to the dataset, repeat steps 5–9. To edit a tag rule, choose the pencil icon at right of the rule. To delete a tag rule, choose the delete icon at right of the rule.

  10. When you're ready to apply the tag rules to the dataset, choose Apply rules.

    
										Image of the Apply rules button for tag-based row-level security.
  11. On the Turn on tag-based security? page that opens, choose Apply and activate.

    The tag-based rules are now active. On the Set up row-level securitypage, a toggle appears for you to turn tag rules on and off for the dataset.

    To turn off all tag-based rules for the dataset, switch the Tag-Based toggle off, and then enter "confirm" in the text box that appears.

    
										Image of the Tag-Based toggle on the set up row-level security page.

    On the Datasets page, a lock icon appears in the dataset row to indicate that tag rules are enabled.

    You can now use tag rules to set tag values at runtime, described in Step 2: Assign values to RLS tags at runtime. The rules only affect QuickSight readers when active.

    Important

    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.

Add RLS tags to a dataset using the API

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 --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. 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.

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

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

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.

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.

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 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 , or GenerateEmbedUrlForAnonymousUser in the Amazon QuickSight API Reference