Users, Roles & Permissions
Users, roles, and permissions work together to determine who can access what inside your database. Users are the individual accounts for authenticating into the project. Each user is assigned a role which defines its access permissions.
Before You Begin
We recommend you try the Quickstart Guide to get an overview of the platform.
To manage users, role and permissions programmatically via the API, please see our API guides on users, roles, and permissions.
In order to understand how users, roles, and permissions work in Directus, a conceptual understanding of how they work in general will be helpful. The following few paragraphs will introduce you to how users, roles, and permissions work within a relational database. If you're already familiar with these concepts, feel free to skip to How it Works in Directus.
Remember, users are data. They are simply rows in a
users data table. It may be easy to forget this if you are new to working with data models, as the term users can create a warm place in our hearts which distinguishes or elevates it above and beyond term "data". But from the perspective of the data model, that's not the case. Users are still just data.
Projects typically have many different kinds of users. For example, you'll need developers and administrators to design the data model as well as manage all its data. Your team may have other users, such as data analysts, content writers, or managers who need to access to some sensitive data, but not the entire data model. Finally, you might have end-users, such as customers, subscribers, 3rd party sellers, and beyond who need access to their own personal data, but should not be able to access any other business data. Therefore, we need to be able to create permissions to define what a user can and can't access.
Another key point is that a user does not need to be a person at all. A user could be an AI bot, chat bot, API, or any other entity that can login and interact with the database.
In many cases, your project will have multiple users doing the same thing (managers, writers, subscribers, etc). If we assigned permissions directly to the user, we would have to configure the same permissions over and over, which makes it tedious to change configurations for all users doing the same job and also leads to a higher chance of misconfiguration. This problem is an example of data duplication. To avoid this, we create roles, configure the role's permissions once, then assign the role to users as desired.
Regardless of your project, your SQL database will always need an administrator role and a public role. In addition, you may need any number of custom roles.
An administrator role provides complete, unrestricted control over the database, including the data model and all it data. This cannot be limited, as by definition it would no longer be an administrator role. You need at least one user in an administrator role. Otherwise, it would be impossible to fully manage the database.
A public role defines access permissions for unauthenticated requests to the database. That means that if you enable an access permission for this role, everybody has that permission enabled. Remember, the database has no idea which data you'd want the public to see. So to be safe, all permissions begin turned off by default. It is up to the administrators to re-configure these and define exactly what the public role has access to.
In addition to these two extreme types of roles, you may need to create more roles each with their own unique set of permissions. The roles you create and the permissions you configure for them are completely open-ended and dependent on your project's needs.
Remember, for the majority of projects, it wouldn't be safe or ethical to give every user full access to the data. Users could accidentally damage data or even take malicious actions against the project and its users. For example, a student may need to be able to see their grade, but not be able to change it.
Thus, there are four types of permissions for each data table, based on the four CRUD actions you can do to data in a database: create, read, update, and delete... Hence you often hear the term CRUD permissions. You can configure CRUD permissions on each data table as desired. For example, you can grant:
- read-only permission
- read and write but not update or delete permissions
- any other combination of the four
In many cases, you will need to grant permissions to data based on its value, or by some other conditional logic. This type of conditional permission is often called a business rule.
To give an example, students should be able to read to their own grades, but not the grades of other students. So you could create a business rule for the
student role, so that a user can only see his or her own grade.
Taking this example one step further, we'd also want to allow students to read and create answers to an online test, but not update or delete their test answers once submitted. Then you may need a business rule to crate a submission deadline. Finally, you likely want to restrict each student's CRUD access to all other student tests.
It is common to have multiple, complex business rules in a project.
How it Works in Directus
While you have full reign to configure these using SQL, Directus also provides a complete system to configure and manage users, roles, and permissions without writing a single line of SQL. The process has three key steps.
No Artificial Limits
You can create as many roles as you need, (re)assign them to as many users as many times you please, and configure complex granular permissions as desired.
Remember, the following users, role and permissions systems built into Directus cannot be deleted, however using them is optional. You may configure your own system as desired.
Within the Data Studio, users are managed within the User Directory. However, there are some controls available to assign users to roles in Settings > Roles and Permissions.
To learn more, please see our guide on users.
You can create as many roles as you need for your project. Directus also comes with built-in administrator and public roles, which cannot be deleted.
The administrator role provides full permissions for all data in the app, and this cannot be limited. You must always have at least one user with an administrator role.
The public role comes with all access permissions turned off by default, but this can be reconfigured as desired. Remember, any access permissions granted to this role will apply to everyone, including unauthenticated web traffic and all existing users. If you wish to keep the project private, simply keep all permissions turned off.
To learn more, see our guide on roles.
Directus offers an extremely granular, yet easy to configure permissions system. When you create a role, all permissions are turned off by default, allowing you to explicitly grant permissions as desired.
There are two other key points to note about Directus. First, the term custom access permissions is used in place of business rules, however the concept is the same. Second, instead of the standard CRUD permissions, Directus provides CRUDS permissions: create, read, update, delete, and share. This fifth type of permission, share, defines whether a user has permissions to perform data sharing on items in a collection.
To learn more, see our guide on permissions.
Workflows are a way to setup structured stages to content authoring and data management. They are created primarily with custom access permissions, but can be enhanced with email notifications, custom Interfaces as well as flows. Directus supports endlessly configurable workflows.
To learn more, see our recipe on Content Approval Workflows.