Permissions
The GraphQL API is protected by a role-based permission system.
For each role, you create rules for the select, insert, update, and delete operations.
Example: Let's say you have a posts
table with id
title
and user_id
columns, and you want users to only access their own posts. This is how you would do it:
The permission above makes sure users can only select their own posts, 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. The permission variable comes from the access token that all authenticated users have. You can add custom permission variables to create more complex permission rules unique to your project.
Permission Variables
You can add permission variables in the Nhost Dashboard under Settings -> Roles and permissions -> Permission Variables. These permission variables are automatically added to users' access tokens. This way, permission variables are available when creating permissions for your GraphQL API.
Example: Let's say you add a new permission variable x-hasura-company-id
with path user.company.id
. This means that Nhost Authentication will get the value for x-hasura-company-id
by internally generating the following GraphQL query:
query {
user(id: "<user-id>") {
company {
id
}
}
}
Arrays
You must add []
at the end of the path for permission variables that are arrays.
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\"}"
}
Limitation on JSON/JSONB columns
JSON columns cannot be used in custom claims, except the users.metadata
column.
Local Permission Variables
To use permission variables locally, add your claims to the config.yml
.
Example: Add a permission variable x-hasura-organization-id
:
auth:
jwt:
custom_claims: '{"organization-id":"profile.organization.id"}'
The claim path should not start with user
when defined in the config.yaml
file.
✅ Correct:
custom_claims: '{"organization-id":"profile.organization.id"}'
🛑 Incorrect:
custom_claims: '{"organization-id":"user.profile.organization.id"}'
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. The 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.
- At the top of the page, click "insert" on the "user" role.
- Select "Without any checks".
- Select the columns you want to allow users to insert. In our example, we only mark
title
, because that's the only column that should be inserted by the user. Theid
is automatically generated by the database anduser_id
is set using a column preset. - Under Column presets, set
user_id
tox-hasura-user-id
. This way, every new record'suser_id
value is set to the ID of the user making the request.
Now, authenticated users are allowed to insert posts. Users are allowed to add a title when inserting a post. The post'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:
- Go to the Database section in the Nhost Dashboard.
- In the context menu of the table you want to edit, click on Edit Permissions.
- Click on the role and operation you want to set.
- Select "With custom check" to create a new rule
- Enter
user_id
,_eq
andx-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. - Limit the number of rows to 100 (or some other relevant number).
- Select the columns you want the user to be able to read. In our case, we'll allow the user to read all columns.
- 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.
Next Steps
Hasura has more in-depth documentation related to permissions that you can learn from: