Access control examples¶

Introduction¶

This is a guide to help you set up a basic authorization architecture for your GraphQL fields. It is recommended that you first check out Roles & Session variables and Configuring permission rules that will be referred to throughout this guide.

Here are some examples of common use cases.

Anonymous (not logged in) users¶

• Create a role called anonymous (this value is up to you, you could even name the role public).
• Generally, you wouldn’t add insert, update, or delete permissions.
• For the select permission condition, create a valid condition depending on your data model. For example, is_published: {_eq: true}.
• If you don’t have a condition, then just set the permission to Without any checks, represented by a {}.
• Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive information will not be exposed.

See Unauthenticated / Public access for steps to configure the anonymous user role in Hasura.

Logged-in users¶

• Create a role called user.
• Access control rules in this case are usually dependent on a user_id or a owner_id column in your data model.
• Set up a permission for insert/select/update/delete that uses said column. E.g.: author_id: {_eq: "X-Hasura-User-Id"} for an article table.
• Note that the X-Hasura-User-Id is a dynamic session variable that comes in from your auth webhook’s response, or as a request header if you’re testing.

Managers of an organisation in a multi-tenant app¶

Suppose you have a multi-tenant application where managers of a particular organisation can see all of the data that belongs to the organisation. In this case, your data models will probably have an org_id column that denotes the organisation either in the same table or via a related table.

• Create a role called manager.
• Create a permission for select, which has the condition: org_id: {_eq: "X-Hasura-Org-Id"}.
• X-Hasura-Org-Id is a dynamic variable that is returned by your auth webhook for an incoming GraphQL request.

Collaborators of an article¶

Let’s say the “ownership” or “visibility” information for a data model (table) is not present as a column in the table, but in a different related table. In this case, let’s say there is an article table and a collaborator table that has article_id, collaborator_id columns.

• Create a relationship called collaborators from the article table.
  • Array relationship (article has array of collaborators): article :: id → collaborator :: article_id.
• Create a role called collaborator.
• Create a select permission on the article table, which has the condition: collaborators: {collaborator_id: {_eq: "X-Hasura-User_id"}}.
  • This reads as: Allow the role collaborator to select if article.collaborators has a collaborator_id equal to that of X-Hasura-User-Id.

Multiple roles per user¶

Sometimes your data/user model requires that:

• Users can have multiple roles.
• Each role has access to different parts of your database schema.

If you have the information about roles and how they map to your data in the same database as the one configured with the GraphQL engine, you can leverage relationships to define permissions that effectively control access to data and the operations each role is allowed to perform.

To understand how this works, let’s model the roles and corresponding permissions in the context of a blog app with the following roles:

• author: Users with this role can submit their own articles.
• reviewer: Users with this role can review articles assigned to them and add a review comment to each article. A mapping of articles to reviewers is maintained in the reviewers table.
• editor: Users with this role can edit and publish any article. They can also leave a private rating for each article. However, they cannot overwrite a reviewer’s notes. A list of editors is maintained in the editors table.

Database Schema¶

The following is a reference database schema for our example:

Based on the above schema, we’ll create the following tables:

-- user information from your auth system

users (
  id INT PRIMARY KEY,
  name TEXT,
  profile JSONB, -- some profile information like display_name, etc.
  registered_at TIMESTAMP -- the time when this user registered
)

-- information about articles

articles (
  id INTEGER PRIMARY KEY,
  title TEXT,
  author_id INT REFERENCES users(id), -- Foreign key to users :: id
  is_reviewed BOOLEAN DEFAULT FALSE,
  review_comment TEXT,
  is_published BOOLEAN DEFAULT FALSE,
  editor_rating INTEGER
)

-- mapping of reviewers to articles

reviewers (
  id INTEGER PRIMARY KEY,
  article_id INTEGER REFERENCES articles(id), -- Foreign key to articles :: id
  reviewer_id INTEGER REFERENCES users(id) -- Foreign key to users :: id
)

-- a  list of editors

editors (
  editor_id INTEGER PRIMARY KEY REFERENCES users(id) -- Foreign key to users :: id
)

Relationships¶

Create an array relationship named reviewers based on the foreign key constraint reviewers :: article_id → articles :: id: