Feb 15, 2022 7 min read Getting Started

Everything you need to know about Directus Roles

Roles are a core feature of Directus which controls how your users interact with the data. Learn how you can use roles to build a successful team and secure your application.

In Directus, there is a User Management module where you can add new users to your platform. By default, Directus only has 2 roles available for these users, Public (no access) and Adminisrator (full access). In this article I will cover how you can create and use Roles to build a successful team and secure your application.

Roles are a core feature of Directus that controls how your users interact with the data. It can be as simple as read and write access or as complex as specific fields within a collection. It's good practice to create a new role for each new user or team and limit their access to what they need. You can always grant access when something else is required.

Why are roles required?

Not all your users will have the same understanding of the platform. You may share the documentation will all your users, but everyone learns differently and will need hands-on experience. Also, not all your data will be appropiate for your users to see or presents a security risk. Lastly, the responsibility of you users might be focused on just a few collections - why show them all?

This is where roles comes in. You can use roles to limit access to your collections for the assigned users. It's worth noting that a user cannot have more than one role. If your users have a lot of overlap between your teams, you will need an individual role based structure.

How do Roles Work?

Roles are split into 5 areas, Create, View, Edit, Delete and Share. For each collection, including system collections, you can specify if that user can perform that action. Each action has your expected binary choice of Allow or Decline but there is a 3rd option called Custom. Custom permissions work differently for each action. I will outline each one below. Details on how to use the interfaces are included further down this article.

Create

Users can create a new row in this collection. You can customize this action to:

Specify what fields are allowed to be written into
Limit what values are permitted in each field
Add default values to fields for this role

An example would be a content writer for a department can only write articles for that department (limited value) and that department is set as default and they cannot approve their own articles.

View

This one is simple, what is the user allowed to see? You can customize this action to:

Filter the data by one or more values
Limit what fields are allowed to be seen?

An example would be a content writer can only see articles that they have created. Or a moderator can only see articles that a not a draft.

Edit

This is very similar to Create. You can customize this action to:

Specify what existing rows can be changed by this role
What fields are allowed to be changed
Limit what values are permitted in each field
Add default values to fields for this role

Delete

This one is simple, can the user delete items from this collection. You can customize this action to:

Specify what existing rows can be deleted by this role

To protect others data, you can limit this action to the user's own records.

In Directus your users can share an item using a link token to anyone who has permission to at least view the item. You can customize this action to:

Specify what existing rows can be shared by this role

An example for a content writer, when they have completed the article, they can create a share link and send it for approval. The moderator can open the link and approve the article.

Create a role

To create a new role, you will need Administrator privilages to the platform. Once logged in, click on the settings cog. Roles lives in the Roles and Permissions menu item.

Example of the Roles and Permissions page

In the corner, click the green plus to create a new role. The name of the role should reflect the indiviual or team, for example, Blog Author, Web Team or Content Manager. Admin Access should always be left unchecked.

There are scenarios where App Access can be unchecked such as an API user.

Roles are divided into 5 columns, Create, View, Edit, Delete and Share. By default a new role will deny access to all your collections. Notice in the screenshot below I have a relational collection call Blog Albums. If this role needs to create a blog entry, they will need read access to Albums and Read, Write, Edit and Delete access on the relation collection Blog Albums. This is becuase adding and removing an Album from the Blog will need to create and delete records from the relational collection. Simply viewing the field will need read access, and changing the Album or sorting the chosen Albums will need to edit existing records.

If you are concerned about security, relational collections are hidden to the user so they cannot make changes directly. Another option is to change your relation field to NULL the value if deleted rather than deleting the record. However, this will leave behind orphaned records and may become an issue for larger datasets.

Customising an Action

When customising an action, there are a few different interfaces that can be confusing.

Field Selection

This a list of fields available in the selected collection. If there a too many, the rest are hidden under Show X more, where X is the amount hidden. Ticking the box will enable that field to be Created/Seen/Changed depending on the action. If you have any required fields, make sure they are chosen. For example, to create a record, the ID must be writable.

Rules or Filters

Item Permissions and Field Validation uses the rules structure to determine the outcome. If you intend to use multiple filters, be sure to add the and / Or group first.

The idea is you choose a field, an operator and a value. When you select a field, the default operator is chosen such as Equals or Contains. Click the operator to change it.

Lastly the value that you want to use. For boolean fields, a checkbox appears. Click the checkbox to toggle betweem the different states.

In the screenbox above, this will only allow posts to be updated if they are marked as featured. But if we use the same rule under Item Permissions, then only Featured albums can be edited.

Field Preset or Default Values

This is a manual entry field and can be very intimidating or frustrating for those new to Directus. Basically, the format is JSON so must follow the following structure:

{
    "field_1": "value",
    "field_2": true,
    "field_3": 1
}

Here is an example where the featured field is change to ticked, the selected album is the ID of the album and the summary change to a string.

Example of setting the default values for fields

Bare in mind, if these fields already have and value that is not NULL, then the presets won't overwrite the value.

The main use case I see for this, is if you want a different default value for certian roles for their convenience. Maybe it's a required field that you don't want them to change? Adding a preset will mean it gets a value without their input.

Delete a Role

If you want to remove roles, make sure to check if they are used first. Removing a role with users attached will NULL their role and lock them out. You will see a number next to the role name that indicates how many users have that role. If it's --, then it's safe to delete.

Example of the user count next to each role

What is the Public Role?

The public role relates more to the API than the app. This is important for sharing data or digital assets.

For example, you can have a folder full of images that you want to display on your website. You will need to customise the Public Role to allow read access to any item that matches the folder ID.

If your users need to share data with an external source, you can allow read-only access to that collection in the Public Role.

Securing you Application

It's very tempting to allow all permissions for each role for the collections needed but it's important to keep your data safe. I've put together a list to consider when building your roles.

Treat each user as a potential risk. Customise your collection permissions to ensure each user can only access the bare minimum that's required.
If a team rule does not meet the needs of the user, create a new role.
If using SSO, create a read-only role as the default role for new users.
If using an API, create a new role and use the same approach as users. Ask yourself, if the API token was compromised, how much damage can this do. You'll find most occasions only require read-only access.
Be mindful what is enabled in the public role.