Permissions

Permissions or authorization rules are used to control acess to data and are set per role and table for each of the select, insert, update, and delete database operations.

Permissions follow a Zero Trust model, meaning that by default, no role, with the exception of admin, has any access. Access has to be explicitly granted.

Imagine a table todos with id, title, and user_id columns. We want users to only have access to their own todos. This is how we would do it:

The permission above makes sure users can only select their own todos, because the value of user_id must be equal (_eq) to the authenticated user’s ID (x-hasura-user-id).

What is x-hasura-user-id?

x-hasura-user-id is a permission variable that is used to create permission rules. Permission Variables come from the session’s access token. You can add custom permission variables to create more complex permission rules unique to your project.

Permission Variables

You can add your own permission variables through the Nhost Dashboard under Settings -> Roles and Permissions -> Permission Variables. All variables are available in users’ access tokens which means you can use them when defining permissions for the GraphQL API.

Example

Let’s say you add a new permission variable x-hasura-company-id with path user.company.id. Nhost Auth will get the value for x-hasura-company-id by generating and running the following GraphQL query:

query {
  user(id: "<user-id>") {
    company {
      id
    }
  }
}

JSONPath

We leverage JSONPath to extract the data which means you have a good amount of flexibility. To help you build your queries you can leverage the following playground. Just remember to skip $. when configuring them.

Example

Let’s say you have a permission variable x-hasura-organization-ids, the path should be, e.g., user.profile.organizations[*].id.

This will result in the following GraphQL query internally:

query {
  user(id: "<user-id>") {
    profile {
      organizations {
        id
      }
    }
  }
}

And result in the following permission variable:

{
  "x-hasura-organization-ids": "{\"13\",\"37\"}"
}

Note

This example is very useful for those building multi-tenant applications.

Limitation on JSON/JSONB columns

JSON columns cannot be used in custom claims, except the users.metadata column.

Permission Variables locally with the CLI

To use permission variables locally, add your claims to nhost.toml as follows:

Example

Add a permission variable x-hasura-organization-id:

[[auth.session.accessToken.customClaims]]
key = 'organization-id'
value = 'profile.organization.id'
default = '00000000-0000-0000-0000-000000000000'

Caution

The claim path should not start with user when defined in nhost.toml.

Roles

Every GraphQL request resolves permissions using a single role.

Default Role

Every user has one default role. The default role is used to resolve permissions if no role is specified using the x-hasura-role header in the GraphQL request.

user is the default role for authenticated users.

Allowed Roles

Every user also has an array of allowed roles. Allowed roles are roles that the user is allowed to use to override the default role when making a GraphQL request. To override the default role, add a header x-hasura-role = <role> to the GraphQL request.

Public Access and Unauthenticated Users

GraphQL requests from unauthenticated users resolve permissions using the public role.

Insert Permissions

Here is a popular approach for insert permission for authenticated users.

1. At the top of the page, click “insert” on the “user” role.
2. Select “Without any checks”.
3. Select the columns you want to allow users to insert. In our example, we do not mark id nor user_id, because they should not be inserted by the user. The id is automatically generated by the database and user_id is set using a column preset.
4. Under Column presets, set user_id to x-hasura-user-id. This way, every new record’s user_id value is set to the ID of the user making the request.

Now, authenticated users are allowed to insert todos. Users are allowed to add a title when inserting a todo. The todo’s id is automatically generated by the database and the user_id is automatically set to the user’s id using the user_id = x-hasura-user-id column preset.

Select, Update and Delete Permissions

Select, update, and delete permissions usually follow the same pattern. Here’s an example of how to add select permissions:

One of the most common permission requirements is that authenticated users should only be able to read their own data. This is how to do that:

1. Go to the Database section in the Nhost Dashboard.
2. In the context menu of the table you want to edit, click on Edit Permissions.
3. Click on the role and operation you want to set.
4. Select “With custom check” to create a new rule
5. Enter user_id, _eq and x-hasura-user-id into the rule form. This means that in order for users to read data, the user ID value in the database row must be the same as the user ID in the access token.
6. Limit the number of rows to 100 (or some other relevant number).
7. Select the columns you want the user to be able to read. In our case, we’ll allow the user to read all columns.
8. Click Save.

Known issues

Permissions are slow

In certain situations, permission checks can cause significant delays. One way to identify this issue is by comparing the execution time of a GraphQL query when performed as an admin versus as a regular user. To resolve such cases, disabling the Just-in-Time (JIT) compilation in Postgres can be beneficial.

Github issue

Next Steps

Hasura has more in-depth documentation related to permissions that you can learn from:

• Authorization / Access control
• Access control basics
• Roles & Session variables
• Inherited roles
• Configuring permission rules
• Access control examples
• Multiple column + row permissions for the same role