---
metadata:
- name: generator
content: Diplodoc Platform v5.63.0
alternate:
- en/security/row-level-security
- ru/security/row-level-security
- href: en/security/row-level-security.md
type: text/markdown
title: Markdown version
csp:
- script-src:
- https://mc.yandex.ru
img-src:
- https://mc.yandex.ru
connect-src:
- https://mc.yandex.ru
- wss://mc.yandex.ru
child-src:
- 'blob:'
- https://mc.yandex.ru
frame-src:
- 'blob:'
- https://mc.yandex.ru
frame-ancestors:
- 'blob:'
- https://mc.yandex.ru
canonical: en/security/row-level-security.html
vcsPath: en/security/row-level-security.md
---
# Row-level security (RLS)
RLS (_row-level security_) enables you to restrict data access for users or [user group](../security/manage-user-groups.md) within a single dataset. For example, you can introduce data access control for different customers.
{% note 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 based on the connection.
* RLS only supports access control for row values.
* The RLS limits apply to whole rows, not just the fields used to configure access control.
{% endnote %}
You can introduce row-level access control either in a [dataset](#dataset-rls) or a [data source](#datasource-rls).
## Configuring RLS at the dataset level {#dataset-rls}
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:
```sql
where dimension in (value_1, value_2 ... value_N)
```
You can configure access to rows from the interface or set the configuration in JSON format:
{% list tabs group=instructions %}
- Interface {#interface_datalens}
1. Open the dataset and go to the **Fields** tab.
1. For the field you need to configure access to, click or → **Access permissions**.
1. In the window that opens, on the **Table** tab, click **Add rule** and specify:
* Who gets the access:
* `Users and groups`: Grant access to the specified users and groups. You can use search by name, login, or email.
* `All users`: Grant access to all users.
* `User IDs`: Control access at [data source level](#datasource-rls).
* Field value. Grant access to all rows with the specified field value.
{% cut "Configuring RLS" %}
{% endcut %}
1. To add another rule, repeat the previous step.
1. Click **Save**.
1. Save the dataset.
- JSON {#json}
1. Open the dataset and go to the **Fields** tab.
1. For the field you need to configure access to, click or → **Access permissions**.
1. In the window that opens, set the RLS configuration in JSON format on the **JSON** tab:
```json
[
{
"allowed_value": "sp-21",
"pattern_type": "value",
"subject": {
"subject_id": "ssxiy********",
"subject_name": "user:ssxiy********",
"subject_type": "user"
}
}
]
```
Where:
* `allowed_value`: Grant access to all rows with specified field value. You need to specify the value only if `pattern_type` is set to `value`; otherwise, it takes the `null` value.
* `pattern_type`: How to grant the access:
* `value`: For the specific field value from the `allowed_value` field.
* `all`: For any field values. In this case, `allowed_value` must be `null`.
* `userid`: Control access at [data source level](#datasource-rls).
* `subject`: Description of the subject getting the access:
* `subject_id`: ID of the user or group to grant access to. Specify `*` if `subject_type` is set to `all` or an empty value if it is set to `userid`.
* `subject_name`: Name of the user to grant access to. Specify `*` if `subject_type` is set to `all` or the `userid` value if it is set to `userid`.
* `subject_type`: Who will get the access:
* `user`: Grant acces to a specific user. In this case, you need to specify the user ID and username in `subject_id` and `subject_name`, respectively.
* `group`: Grant access to a user group. In this case, you need to specify the group ID and group name in `subject_id` and `subject_name`, respectively.
* `all`: Grant access to all users. In which case you need to specify `*` in `subject_id` and `subject_name`.
* `userid`: Control access at [data source level](#datasource-rls).
You can set multiple rules by describing each one in an object with the specified fields.
1. Click **Save**.
1. Save the dataset.
{% endlist %}
## Configuring RLS at the data source level {#datasource-rls}
Configuring RLS at the dataset level requires editing the datatset every time the RLS settings change.
To avoid this, you can move the row-level security logic to the data source side:
1. Add a new field for storing the DataLens user ID to the source data. All requests to the source will be filtered by this field.
You can view your ID in [your account](./user-account.md#see-account) parameters. If you need another user's ID, ask them to open their account and send you the ID.
1. For each source data row, specify the ID of the DataLens user who should get access to 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](../dataset/settings.md#multi-table) it to the main table at the dataset level.
1. In the dataset, configure access to the field containing user IDs:
{% list tabs group=instructions %}
- Interface {#interface_datalens}
1. In the RLS settings window, on the **Tables** tab, click **Add rule**.
1. Select **User IDs** for the `Who has access` parameter.
{% cut "Configuring RLS by user ID" %}
{% endcut %}
1. Click **Save**.
- JSON {#json}
1. In the RLS configuration window, set the RLS configuration in JSON format on the **JSON** tab:
```json
[
{
"allowed_value": null,
"pattern_type": "userid",
"subject": {
"subject_id": "",
"subject_name": "userid",
"subject_type": "userid"
},
}
]
```
1. Click **Save**. Access will be granted to users whose IDs are specified in the field.
{% endlist %}
1. Save the dataset.
{% note info %}
You can transfer the RLS logic to the source side for sources where the data structure can be changed.
{% endnote %}
## How to change permissions to a row in a dataset {#how-to-manage-rls}
To configure access permissions to data rows:
{% list tabs %}
- In the dataset
1. Open the dataset.
1. Go to the **Fields** tab.
1. On the right side of the row, click and select **Access permissions**.
1. In the window that opens, set the access permissions for the field:
{% list tabs group=instructions %}
- Interface {#interface_datalens}
1. On the **Table** tab, click **Add rule** and specify the users, groups, or `All users` and the field value. For example, to configure user access to all rows with the `first-company` value:
* **Who has access**: Select the user.
* **Field values**: Enter `first-company`.
1. Click **Save**.
- JSON {#json}
1. On the **JSON** tab, set the RLS configuration in JSON format. For example, to configure user access to all rows with the `first-company` value:
```json
[
{
"allowed_value": "first-company",
"pattern_type": "value",
"subject": {
"subject_id": "ssxiy********",
"subject_name": "user:ssxiy********",
"subject_type": "user"
}
}
]
```
1. Click **Save**.
{% endlist %}
1. Save the dataset.
- In the source
1. In the source, add a field with the DataLens user IDs to use for filtering. You can add this field to a new table and join it using the `JOIN` operator.
1. Add a field with user IDs to the dataset:
* If you added a field to an existing table, go to the **Fields** tab in the dataset and click **Update fields** at the top of the screen. The user ID field will appear in the list.
* If you added a field to a new table, join it using the `JOIN` operator. To do this, go to the **Sources** tab in the dataset and drag the new table to the workspace. The table will be automatically linked with the existing table. If required, edit the [link](../dataset/create-dataset.md#links) between the tables and [remove](../dataset/create-dataset.md#field-operations) duplicate fields left after the join.
1. Configure field access permissions:
1. In the dataset, go to the **Fields** tab.
1. Find the field with user IDs. On the right side of the row, click and select **Access permissions**.
1. In the window that opens, set the access permissions for the field:
{% list tabs group=instructions %}
- Interface {#interface_datalens}
1. In the RLS settings window, on the **Tables** tab, click **Add rule**.
1. Select **User IDs** for the `Who has access` parameter.
1. Click **Save**. Access will be granted to users whose IDs are specified in the field.
- JSON {#json}
1. In the RLS configuration window, set the RLS configuration in JSON format on the **JSON** tab:
```json
[
{
"allowed_value": null,
"pattern_type": "userid",
"subject": {
"subject_id": "",
"subject_name": "userid",
"subject_type": "userid"
},
}
]
```
1. Click **Save**. Access will be granted to users whose IDs are specified in the field.
{% endlist %}
1. Save the dataset.
{% cut "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. Define DataLens user IDs.
1. In the source, create a table named `MANAGER_ID`, where the region is mapped to the user ID. If a single ID is associated with multiple regions, add all unique pairs:
| REGION | MANAGER_NAME | MANAGER_ID |
|--------|--------------|-------------------|
| West | Arkady | 19287318273912873 |
| East | Vassily | 92877912837318927 |
| North | Olga | 02993284928374346 |
| South | Dmitry | 10836293849237642 |
| West | Maxim | 71726123712891283 |
| East | Maxim | 71726123712891283 |
| North | Maxim | 71726123712891283 |
| South | Maxim | 71726123712891283 |
1. Open the dataset and add the new table: on the **Sources** tab, drag the table to the workspace.
1. Make sure the `JOIN` is based on the `REGION` field.
1. Based on the `MANAGER_ID` field, customize RLS.
{% list tabs group=instructions %}
- Interface {#interface_datalens}
- JSON {#json}
{% endlist %}
Each user will only see data for regions they have access to.
To change the access permissions, update the data in the source table.
{% endcut %}
{% endlist %}