MeshyDB Now Supports Roles & Permissions

For the past several months our development team has been working hard on a new feature designed to help manage user access better. We are calling this feature “Roles” (clever huh?) and it allows you to specify permissions on specific data elements for a group of users. Before we dive into the feature, let’s first get an understanding of the terms.

What is a Permissible?

A permissible represents a grouping of data. A permissible can be a mesh collections, projections, users or roles.

What is a Permission?

A permission is a level of control or access on a permissible. Permissions can be as specific as create, read, update and/or delete access.

What is a Role?

A role is a shared group of permissions that can be assigned to users within your application.

Using System Roles

With the introduction of Roles, MeshyDB predefines several system roles to help facilitate access within your application. These roles cannot be removed and, in some cases, are assigned automatically when users are created. They are great for defining common permissions that apply to all users of a specific type. For clarity’s sake these roles are prefixed with “meshy.”. Let’s dive into the roles themselves:

meshy.admin

This role is essentially god-mode as far as the API is concerned. Users with this role can access and modify all your data. No one will have this role by default, however you can give this role out as needed. We suggest giving this role out sparingly in favor of custom roles (see below).

Note: because this role needs all permissions, no changes can be made to permissions.

meshy.user

This role is a catch all for all users who register or are created in your system. MeshyDB classifies these individuals as users and they are automatically given the meshy.user role. This role should be used to define base access to all users. For example, if you have a mesh collection called “payments” that you only want users to insert into but not read directly from you would create a permission on the meshy.user role that establishes that business rule.

Note: because this role is auto assigned, no changes can be made to the user list.

meshy.anonymous

This role represents users who register anonymously. Why would you want to control access for anonymous users? Well in some cases, your application may want to allow users to interact with your system without having to register. MeshyDB classifies these individuals as anonymous and they are automatically given the meshy.anonymous role. This role should be used to define the data elements you are comfortable exposing to the public.

Note: because this role is auto assigned, no changes can be made to the user list.

Creating a Custom Role

Systems roles are great; however, most applications will require more precise control over user access. This is where custom roles come into play. To create a new custom role, you will want to navigate to the Roles page and click + Add Role.

Defining the Role

All roles in the system must have a unique name. This name can be whatever makes sense to your application; however, it must be only alpha characters. A description is also required to help define what your role can do, this value is simply for reference purposes only and does not drive any permissions.

Tip: Try to keep your role names short and concise focusing on the purpose and not the functionality. For extra definition you can always add information in the role description.

Adding Users to the Role

By default, your new role will not be associated to any users. You can start adding users to the new role by navigating to the Users tab on the Roles detail page and searching for users by name, username or email address. Once you find the users you want to associate simply click the checkbox next to their name. After searching for and adding all the users who belong to the role you can save your changes by clicking Add.

Note: Due to the secure nature of roles, auto assigning roles during registration is limited to the meshy.user and meshy.anonymous roles. Since registration is a public endpoint, we needed to prevent any sort of way for a user to request a role of higher permission than the default role. The consequence of this security consideration is the need for nondefault roles to be explicitly granted by a user the with meshy.admin role from within your own app or the MeshyDB admin portal.

Specifying Permissions for the Role

Controlling access to specific data elements is accomplished via permissions. To add a permission, click on the permissions tab on the Role details page and search for the element by name you want to limit or grant access to. For example, if you have a mesh named “people” just start typing “people” in the search field and select the option found. After selecting the permissible you will be able to specify create, read, update and delete permissions.

Note: since projections are read only in nature, only read access can be granted to those objects.

Using Your Custom Role

And there you have it! Your data is now protected and only the appropriate users can access it.

The MeshyDB API automatically enforces permissions upon each request made. This means that if a user lacks permission to a specific object or endpoint they will receive a forbidden 403 status code. There is nothing your application needs to do to take advantage of roles, however we do suggest preventing any calls you know would be blocked so that your logs only show malicious 403s.

For more information on how to implement roles we suggest checking out docs.meshydb.com.