Permission actions

User permissions

Permissions

Permissions are the core security functionality offered by Authress. They represent the most granular aspect. In extreme cases, permissions will directly reflect the API resource endpoints of a service application. For simplicity, the example used here will not be as granular, and we’ve adjusted the example to only understand a few actions allowed.

Document model

Before diving into the permissions and what is allowed, let’s review what outcome we want:

Allow, Grant, Delegate

In simple cases, users take actions in the document repository with regard to those documents. However, what happens when a user wants to share a document with another user or an external entity. In these cases, a flat permissions list becomes problematic. In Authress, above Allow there is Grant and Delegate.

With this pattern Authress providers users the ability to perform an action Allow, assign Allow-based roles to others (Grant) or Delegate their role to others.

Roles

Roles contain a list of actions with their associated permission. There can be any number of permissions in a role, and the permissions in a role are scoped. For instance, a role may contain *, documents:*, documents:flat-documents:*, and documents:flat-documents:read. Any of which if applied in an access record to a resource would give documents:flat-documents:read to the user. For this reason when defining permissions, it’s valuable to put the least specific part of the permission scope at the beginning. read:documents is great if you provide read:*, however, it’s usually better to have documents:*.

With the Grant and Delegate permissions a user with a role that contains one of these can assign roles to other users. This is done through Access Records.

Roles are orthogonal to resources. The permissions added to roles, don’t inherently impact your application or grant any permission, until they are joined with explicit resources. Therefore, documents:read and just read may operate the same or differently based upon which roles are added to access records, and which permissions are being checked in an application.

Reviewing the model

With this we can see why the roles look the way they do: Admin star permissions

The admin has star access to perform any action on specified resources. Just because the admin has Allow: * which resources this applies to are restricted based on the Access Records. The admin also has the access to Grant any user any permission role. From our list of three roles, this would only be the User role. Just looking at the Allow and Grant permissions for the action * a user would not be able to grant the Editor role because it also contains a Grant. However, since the admin role also has Delegate, an admin can Delegate additionally the Admin and Editor roles. Additionally, even without the Grant permission, the admin would be able to also delegate the User role.

user role permissions

The user role has only Allow: document:read, meaning any check to read a document will be successful, if the user has the role on that document. They can neither give other users the User role nor any other role, since they don’t have Grant.

editor role permissions

The Editor is the most complex based on our example use cases. We know all the permission actions that the role needs, but to handle the additional cases, we need to configure the permission grants. The Editor role to manage documents needs documents:create, documents:read, and documents:update. Depending on the changes in an application over time, a single permission documents:* may be sufficient. Additionally, the Editor role must be allowed to assign the User role, but not the Editor role. In this case since the User role has no Grants, adding Grant to documents:read is all we need. Adding the Grant on documents:create and documents:udpate is unnecessary because there is no role with those permission actions without Grant. So having Grant on them doesn’t offer any additional value, until those roles exist. Additionally because Editor does not have Delegate on any permission, it cannot assign any role which contains a Grant including the Editor role. The only role which can assign the Editor role with the current configuration is the Admin role.

Expanding for many roles

As systems grow more complex use cases can arise. In these situations it makes sense to evaluate which roles should be created and how to optimize.

Mix and match roles

Since multiple roles can be applied for a user on a single resource, occasionally it makes sense to create roles that are independent without overlapping permissions. For example, let’s say we wanted to add the resource audit-trail and the permission audit-trail:read. We need to answer the question of which roles to add this permission to.

Sometimes adding the new permission to existing roles works best. In other cases, we might think about creating a new role Auditor, which will only contain the permission audit-trail:read. This would result in four roles total. So the complexity of the system increases, however, it makes it easy to enable the user’s access to audit trails, simply by giving them this additional role, without needing to think about whether to promote them to Editor or Admin.

Since you're here, check out what Authress is all about!

Enjoyed reading this article? There's more in our Knowledge Base.