Managing access at the data row level (RLS)

Written by

Improved by

Updated at November 7, 2024

Configuring RLS at the dataset level
Configuring RLS at the data source level
How to change permissions to a row in a dataset

With RLS (row-level security), you can restrict data access for users or user groups within a single dataset. For example, you can introduce data access control for different customers.

Warning

When using RLS, restrict access to the connection by using the Execute permission. This will prevent changes to row access permissions and restrict access to opening the preview window and creating a new dataset from the connection.
RLS supports access control for string values only.

You can introduce data access control at the row level either in a dataset or a data source.

Configuring RLS at the dataset level

You can control access to any dataset dimension. Each user or user group can be granted permissions for an unlimited number of measure values.

With RLS, a query to a dataset passes through the following filter:

where dimension in (value_1, value_2 ... value_N)

User access

For users, access control is based on the access configuration which looks like this:

'value_1': user_1, user_2
'value_2': user_3
'value_3': user_1, user_2, user_3

For example, to permit the user-login user to access the first-company value of the Company name field, specify the following configuration:

'first-company': user-login@yandex.ru

To configure access for multiple users, list their accounts in the access configuration separated by commas:

'first-company': user-login-1@yandex.ru, user-login-2@yandex.ru, user-login-3@yandex.ru

Access for user groups

For user groups, access control is based on the access configuration which looks like this:

'value_1': @group:group_1_name
'value_2': @group:group_1_name, @group:group_2_name

The configuration specifies the group name rather than its identifier. If a group is renamed, you will need to update its RLS configuration accordingly.

For example, to allow the group-name user group to access the first-company value of the Company name field, specify the following configuration:

'first-company': @group:group-name

To configure access for multiple user groups, list them in the access configuration separated by commas:

'first-company': @group:group-name-1, @group:group-name-2, @group:group-name-3

You can configure access for users and groups at the same time:

'first-company': user-login-1@yandex.ru, user-login-2@yandex.ru, @group:group-name-1, @group:group-name-2

Wildcards and quotation marks in RLS configuration

You can define values, users, and group names using wildcard characters:

User_1, user_2, and group_1_name can access all the field's values
```
*: user_1, user_2, @group:group_1_name
```
For example, to configure access to all values of the Company name field, specify the following configuration:
```
*: user-login-1@yandex.ru, @group:group-name-1
```
value_1 is available to all users and groups
```
'value_1': *
```
For example, to allow all users and groups to access the first-company value in the Company name field, specify the following configuration:
```
'first-company': *
```

Quotes in values are set using double quotes:

'value in ''quotes''': user_1, user_2

For example, to set quotation marks for the first-company "Example" company name in the Company name field, specify the following configuration:

'first-company ''Example''': user-login-1@yandex.ru, @group:group-name-1

You can also use the " character:

'first-company "Example"': user-login-1@yandex.ru, @group:group-name-1

Configuring RLS at the data source level

Configuring RLS at the dataset level requires editing the dataset every time the RLS settings change.

To avoid this, you can move the access control logic at the row level to the data source side:

Add a new field for storing user IDs to the source data. All requests to the source will be filtered by this field.

To view your ID, follow this link. If you need another user's ID, ask them to open this link and pass the ID to you.
For each row of source data, specify the ID of the user who is allowed to access this row. If multiple users must have access to the same row, you can move the access control logic to a separate table and join it to the main table at the dataset level.
In the dataset, enter userid:userid in the ID field under the RLS settings. The userid variable can be used together with the regular RLS type in the dataset:
```
'value_1': user_1, user_2
'value_2': user_3
   userid:userid
```

Note

You can transfer the RLS logic to the source side for sources where the data structure can be changed. In Yandex Metrica and AppMetrica, the data structure is closed, so this method is unavailable.

How to change permissions to a row in a dataset

To configure access to a data row value:

In the dataset

In the source

Open the dataset.
On the right side of the row, click and select Access rights.
Enter the value of the field and users in the specified format and click Save.
```
'value_1': user_1, user_2
'value_2': user_3
```
For example, to configure access to the first-company value for the Company name field:
```
'first-company': login-to-access-your-row-data@yandex.ru
```
Save the dataset.

Add a field to the source that will store user IDs and be used for filtering. You can add this field to a new table and join it using the JOIN operator.
Add the field to the dataset.
Open the dataset.
On the right side of the row, click and select Access rights.
In the permission settings, add userid:userid to the field and click Save.
Save the dataset.

Example

Let's create a dashboard based on sales data by four regions (West, East, North, and South). Regional managers should only have access to their own data, while the company's CEO, to all data.

1. Let's define user IDs.
2. In the source, create an additional table named MANAGER_ID with the region related to the user ID. If multiple regions are available for the same ID, list all unique pairs:

REGION	MANAGER_NAME	MANAGER_ID
West	Arkady	19287318273912873
East	Vasily	92877912837318927
North	Olga	02993284928374346
South	Dmitry	10836293849237642
West	Maxim	71726123712891283
East	Maxim	71726123712891283
North	Maxim	71726123712891283
South	Maxim	71726123712891283

3. Let's add the table to the dataset.
4. To do this, make a JOIN by the REGION field.
5. Then set up RLS by the MANAGER_ID field and add userid:userid.

To change the access control settings, update the data in the source table.

Managing access at the data row level (RLS)

Configuring RLS at the dataset levelConfiguring RLS at the dataset level

User accessUser access

Access for user groupsAccess for user groups

Wildcards and quotation marks in RLS configurationWildcards and quotation marks in RLS configuration

Configuring RLS at the data source levelConfiguring RLS at the data source level

How to change permissions to a row in a datasetHow to change permissions to a row in a dataset