You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Custom roles allow you to create granular permission sets tailored to your organization's specific needs. With custom roles, you can define exactly which scopes (permissions) users should have, giving you fine-grained control over access to Lightdash features and resources."
**Custom roles are only available on Lightdash Enterprise plans.**
14
+
15
+
For more information on our plans, visit our [pricing page](https://www.lightdash.com/pricing).
16
+
</Info>
17
+
18
+
## Overview
19
+
20
+
Lightdash provides two types of roles:
21
+
22
+
-**System roles**: Pre-defined roles (like Admin, Developer, Viewer) with a standard set of scopes. For more information about what these roles can do, check our [default system roles permission matrix](https://docs.lightdash.com/references/roles#roles-and-permissions).
23
+
-**Custom roles**: User-defined roles where you can select specific scopes to match your exact requirements
24
+
25
+
Custom roles are created at the organization level but are assigned to users or groups at the project level, allowing you to control access on a per-project basis.
26
+
27
+
<Info>
28
+
**Additive Permissions**: Lightdash uses an additive permission model. If a user already has a scope granted through their organization-level role, assigning a custom role will not restrict that access. Custom roles can only add permissions, not remove existing ones.
29
+
</Info>
30
+
31
+
## Creating Custom Roles
32
+
33
+
### Access Custom Roles Settings
34
+
35
+
1. Navigate to **Settings** → **General Settings** → **Custom Roles**
36
+
2. You'll see a list of existing custom roles in your organization
37
+
38
+
### Create a New Role from Scratch
39
+
40
+
1. Click **Create New Role**
41
+
2. Enter a **Role Name** (e.g., "Marketing Analyst", "Finance Viewer")
42
+
3. Add an optional **Description** to explain the role's purpose
43
+
4. Select the specific **scopes** (permissions) you want to include:
44
+
-**View permissions**: Allow users to see content (dashboards, charts, spaces)
45
+
-**Create permissions**: Allow users to create new content
46
+
-**Manage permissions**: Allow users to edit, delete, or administer content
If you want to create a role similar to an existing one:
54
+
55
+
1. Find the role you want to duplicate (system role or custom role)
56
+
2. Click the **⋯** menu next to the role
57
+
3. Select **Duplicate Role**
58
+
4. Enter a new name for the duplicated role
59
+
5. Modify the scopes as needed
60
+
6. Click **Save**
61
+
62
+
This is particularly useful when you want to create a role similar to a system role but with some modifications.
63
+
64
+
65
+
66
+
## Assigning Custom Roles
67
+
68
+
Custom roles are assigned at the project level to provide granular access control:
69
+
70
+
### Assign to Users
71
+
72
+
1. Go to **Project Settings** → **Access**
73
+
2. Find the user you want to assign a role to
74
+
3. Select the custom role from the dropdown
75
+
4. The user will now have the permissions defined in that custom role for this project
76
+
77
+
### Assign to Groups
78
+
79
+
1. Go to **Project Settings** → **Access**
80
+
2. Find the group you want to assign a role to
81
+
3. Select the custom role from the dropdown
82
+
4. All members of the group will inherit the custom role permissions for this project
83
+
84
+
## Troubleshooting
85
+
86
+
### Users Can't See Expected Content
87
+
88
+
- Verify the custom role includes the necessary view scopes
89
+
- Check that the role is assigned at the project level where the content exists
90
+
- Remember that organization-level permissions may override custom role limitations
91
+
92
+
### Role Changes Not Taking Effect
93
+
94
+
- Users may need to refresh the page for role changes to take effect
95
+
- Verify the role was saved successfully and assigned to the correct users/groups
96
+
97
+
## Managing Existing Custom Roles
98
+
99
+
### Edit a Custom Role
100
+
101
+
1. Go to **Settings** → **General Settings** → **Custom Roles**
102
+
2. Click on the role you want to edit
103
+
3. Modify the name, description, or scopes
104
+
4. Click **Save** - changes will apply to all users and groups assigned this role
105
+
106
+
### Delete a Custom Role
107
+
108
+
1. First, ensure no users or groups are assigned this role
109
+
2. Go to **Settings** → **General Settings** → **Custom Roles**
110
+
3. Click the **trash icon** next to the role
111
+
4. Confirm the deletion
112
+
113
+
<Info>
114
+
**Deleting Roles**: Once deleted, a custom role cannot be recovered. You can't remove a role that is currently assinged to users or groups.
115
+
</Info>
116
+
117
+
Custom roles provide powerful flexibility in managing access to your Lightdash organization. By carefully designing roles that match your team's responsibilities and workflows, you can ensure users have exactly the permissions they need while maintaining security and organization.
Once the pull request with your new Dimension is merged, you can click `Refresh dbt` in Lightdash (or, if you're [using GitHub actions](../guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action), your project will automatically refresh once your changes are merged).
63
60
64
-
65
61
### Known limitations
66
62
67
63
##### Bin Dimensions
@@ -72,40 +68,36 @@ Writing back bin Dimensions is not supported at the moment. If you want to help
72
68
73
69
At the moment, if you write back a Custom Dimension to your dbt project's YAML, the Custom Dimension will not be automatically replaced with the new YAML Dimension. Once your new Dimension is created in dbt, you'll need to manually update your charts and replace the Custom Dimensions with the new Dimension.
74
70
75
-
76
71
## Write back dbt Models from the SQL Runner
77
72
78
73
You can use Lightdash to build models in dbt from queries that you've built in the SQL runner. We recommend writing back models from the SQL runner if you're planning to use the query regularly so it can be easily used, governed and managed like other dbt models in your Lightdash project.
79
74
80
75
To get started, build and run a query in the SQL runner, then select the `Write back to dbt` option from the `Save` drop-down.
You'll be asked to enter a name that will be used as the model name and file names in your dbt project. Clicking `Open pull request` will open a pull request created by Lightdash against your dbt project in GitHub.
81
+
You'll be asked to enter a name that will be used as the model name and file names in your dbt project. Clicking `Open pull request` will open a pull request created by Lightdash against your dbt project in GitHub or GitLab.
The new model will be written to your dbt project in a `models/lightdash/` directory. The model will have the tag `created-by-lightdash` included in the model config.
93
88
94
-
95
89
### Getting your model to appear as a `Table` in Lightdash
96
90
97
91
You might need to adjust your Table Configuration settings in your project to have your new models appear as Tables in Lightdash.
98
92
99
93
If you've selected:
100
94
101
-
*`Show entire project` then you don't need to do anything. The models should appear automatically if you refresh your dbt project connection.
102
-
103
-
*`Show models with any of these tags`, you'll need to add `created-by-lightdash` to the list of accepted tags. By default, models that you write back to dbt will have the tag `created-by-lightdash` included in the model config.
104
-
105
-
*`Show models in this list`, you'll need to manually add the new models to the list of accepted models here.
95
+
-`Show entire project` then you don't need to do anything. The models should appear automatically if you refresh your dbt project connection.
96
+
-`Show models with any of these tags`, you'll need to add `created-by-lightdash` to the list of accepted tags. By default, models that you write back to dbt will have the tag `created-by-lightdash` included in the model config.
97
+
-`Show models in this list`, you'll need to manually add the new models to the list of accepted models here.
@@ -114,22 +106,19 @@ If you get an `Error: not found your_table_name`, it's likely because you haven'
114
106
115
107
#### Manual approach
116
108
117
-
Once your model is merged to your dbt project, you can run `dbt run -s your_model_name_here` to create the table in your data warehouse. You might need to add `--target prod` if your default profile is set to `dev`!
109
+
Once your model is merged to your dbt project, you can run `dbt run -s your_model_name_here` to create the table in your data warehouse. You might need to add `--target prod` if your default profile is set to `dev`\!
118
110
119
111
#### Automated approach using dbt Cloud
120
112
121
113
If you're using dbt Cloud to manage your dbt project, you can create a job that will automatically run any new models with the tag `created-by-lightdash`.
122
114
123
115
To create a job that does this, you'll want to:
124
116
125
-
1. open dbt Cloud, head to `Deploy` --> `Jobs` and click `create new job`
126
-
117
+
1. open dbt Cloud, head to `Deploy` --\>`Jobs` and click `create new job`
127
118
2. toggle on `triggered by pull requests` in the `Git Trigger` section
128
-
129
119
3. add the command `dbt run --select tag:created-by-lightdash`
130
-
131
120
4. set `compare changes against environment` to `prod`. This will make sure that this job only runs when a model is changed from your pull request
0 commit comments