{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/introducing-user-roles-authorization-with-supertokens", "result": {"data":{"markdownRemark":{"html":"

Table of Contents

\n\n

Part 1 - Introducing user roles and understanding why authorization matters

\n

Introduction

\n

Today, we’re excited to announce the launch of user roles within SuperTokens! With user roles, you can now easily attach different sets of permissions to each user.

\n

At SuperTokens, we’ve put a lot of thought into authentication and authorization.

\n

Authentication is about: “Which user is this request coming from?”

\n

Authorization is about: “Is this user allowed to do a certain operation?”

\n

In the past, we’ve focused on authentication with our email password, password-less, social, and phone authentication recipes.

\n

User roles address the authorization side of the puzzle. Continuing on our momentum with our authentication product, we’re excited to help you manage your users with finer controls without compromising on application security.

\n

If you’re looking to implement user roles today, check out the second part of this post or our user roles documentation.

\n

\n \n \n \n \n

\n

What are user roles and why are they important for user authentication?

\n

User Roles is built based on principles of roles-based access control (RBAC).

\n

RBAC is a security model that restricts access to resources based on the roles that users have within an organization. Users are assigned to specific roles and those roles are granted permissions to access certain resources.

\n

Let’s try building a blogging app with user roles.  

\n

We’d want to have a regular-users role that allows regular users to read all blog posts, but only edit or delete posts created by themselves. We’d also want to have an admin role where admins can create, edit, and delete all blog posts.

\n

In formal notation, the actions that can be taken can be represented as strings like:

\n\n

These are known as permissions. In a grid form, the roles and permissions for our example app will look like this:

\n

\n \n \n \n \n

\n

Enabling user roles with SuperTokens

\n

We’ve built user roles based on the principles of RBAC.

\n

Let’s use our previous example again. A quick reminder -

\n\n
\n

The code snippets below are for a NodeJS backend, but similar logic applies for the other backend SDKs offered by SuperTokens as well. 

\n
\n

Step 1) Creating the roles and permissions

\n

To start, SuperTokens needs to know about the roles and permissions before they can be assigned to users. For that, we can use the UserRoles.createNewRoleOrAddPermissions function exposed by the SDK:

\n\n \n \n \n \n
import UserRoles from \"supertokens-node/recipe/userroles\";\n\n// creating the admin role and adding permissions to it.\nawait UserRoles.createNewRoleOrAddPermissions(\"admin\", [\"read:all\", \"delete:all\", \"edit:all\"])\n\n// creating the regular-user role and adding permissions to it.\nawait UserRoles.createNewRoleOrAddPermissions(\"regular-user\", [\"read:all\", \"delete:self\", \"edit:self\"])
\n

This allows us to declare both the name of the role as well as the permissions related to the role. Fairly simple stuff.

\n

Step 2) Assigning roles to users on sign up

\n

With SuperTokens you can:

\n\n

For our example, we’ll simply assign our created roles to users through the UserRoles.addRoleToUser function. To do this, we use the following snippet in our override function for the sign up API:

\n\n \n \n \n \n
import UserRoles from \"supertokens-node/recipe/userroles\";\n\n// The value of roleToAssign needs to be fetched by you.\n// For example, you could check if the user's email is of a certain domain,\n// and if it is, then they would be an admin, else not.\nif (roleToAssign === \"admin\") {\n    // the userId belongs to the user who just signed up.\n    await UserRoles.addRoleToUser(userId, \"admin\");\n} else {\n    await UserRoles.addRoleToUser(userId, \"regular-user\");\n}
\n

We can even manually add the roles and permissions to the user’s session payload for efficient access at a later point. SuperTokens does this automatically as long as you have assigned the roles to a user before their session is created.

\n

Step 3) Guarding APIs based on a user’s role or permissions

\n

Assigning roles to users is only half the battle.

\n

We also need to retrieve the roles and permissions to understand if a user is allowed to perform certain functions. We can use the following code snippet to complete session verification (the authentication piece of the puzzle) and then implement our authorization logic:

\n {\n    let blogId = req.body.blogId\n    let userId = req.session.getUserId();\n\n    // if the user is an admin, we will get ["admin"], \n // else we will get ["regular-user"]\n let roles = req.session.getClaimValue(UserRoles.UserRoleClaim)\n\n    // if the role is "admin", we get ["read:all", "delete:all", "edit:all"]\n    // else we get ["read:all", "delete:self", "edit:self"]\n let permissions = await req.session.getClaimValue(UserRoles.PermissionClaim)\n\n    if (permissions.includes("delete:all")) {\n        // allow delete\n    } else if (permissions.includes("delete:self")) {\n        if (getOwnerOfBlog(blogId) === userId) {\n            // allow delete\n        } else {\n            // return access denied error\n        }\n    }\n})`, `88005330037289140000`)\"\n >\n \n \n \n \n
import { verifySession } from \"supertokens-node/recipe/session/framework/express\";\nimport UserRoles from \"supertokens-node/recipe/userroles\";\n\napp.delete(\"/blog\", verifySession(), async (req, res) => {\n    let blogId = req.body.blogId\n    let userId = req.session.getUserId();\n\n    // if the user is an admin, we will get [\"admin\"], \n    // else we will get [\"regular-user\"]\n    let roles = req.session.getClaimValue(UserRoles.UserRoleClaim)\n\n    // if the role is \"admin\", we get [\"read:all\", \"delete:all\", \"edit:all\"]\n    // else we get [\"read:all\", \"delete:self\", \"edit:self\"]\n    let permissions = await req.session.getClaimValue(UserRoles.PermissionClaim)\n\n    if (permissions.includes(\"delete:all\")) {\n        // allow delete\n    } else if (permissions.includes(\"delete:self\")) {\n        if (getOwnerOfBlog(blogId) === userId) {\n            // allow delete\n        } else {\n            // return access denied error\n        }\n    }\n})
\n

To sum this code snippet up -

\n
    \n
  • we’ve found the user’s role using UserRoles.UserRoleClaim
    • \n
  • we’ve found the user’s permissions using UserRoles.PermissionClaim
    • \n
  • we’ve set up permission barriers around the delete function
    • \n
\n

And we’re done! We’ve now created new roles + permissions, assigned them to users, and protected our API routes against unauthorized access.

\n

Conclusion

\n

User roles is a major step forward for SuperTokens as a company. By pooling both authentication and authorization, we’re one step closer to making the best user authentication tool on the market. And we couldn’t have done it witout you.

\n

You can learn more about how to use user roles and permissions with SuperTokens via the recipe guides docs!

","frontmatter":{"date":"October 27, 2022","title":"Introducing User Roles Authorization with SuperTokens","cover":"user_roles_cover.png","author":"Advait Ruia","description":"With user roles, you can now use SuperTokens to easily attach a different set of permissions to each user."},"fields":{"slug":"/introducing-user-roles-authorization-with-supertokens/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"0f8f5fa1-f411-5de4-919b-2f10a558a528","fields__slug":"/introducing-user-roles-authorization-with-supertokens/","__params":{"fields__slug":"introducing-user-roles-authorization-with-supertokens"}}}, "staticQueryHashes": []}