🔐 Role-based access control (RBAC)

Intro

Role-based access control (RBAC) is a method of assigning permissions to users based on their roles. By controlling access to resources through role authorization, RBAC can help in different perspectives:

• Improved security By assigning permissions based on roles, RBAC limits access to resources only to those who need it. This reduces the risk of unauthorized access and data breaches.
• Greater efficiency RBAC allows for quick and easy addition and modification of roles and permissions and implementing them across APIs, making it easy to manage access rights for large numbers of users.
• Reduced administrative overhead RBAC eliminates the need for manual assignment of permissions and reduces the potential errors.
• Better compliance RBAC can help organizations comply with regulatory and statutory requirements for confidentiality and privacy by ensuring that only authorized users have access to sensitive data.
• Flexibility RBAC can be easily customized and adapted to suit the specific needs of an organization, making it a versatile access control method.
• Scalability RBAC can be implemented in an organization of any size, from small businesses to large enterprises, and can be easily scaled up or down as necessary.

RBAC in Logto

In Logto, we have implemented RBAC using the most standard and scalable method, allowing for a wide range of scenarios. To understand how it works, it's important to familiarize yourself with key terms:

Permissions (Scopes)

Permission refers to the authorization to access a resource (we call it API Resource). In the real world, entities such as orders, products, and documents can be designated as resources, and various actions can be assigned.

note

"Permission" is identical to "scope" in OAuth 2.0. We use the word "permission" in Admin Console since it's more intuitive for business.

Examples of permissions, including the ability to edit an order, read a document, and delete a product, are as follows:

• write:orders
• read:documents
• delete:products

In Logto, a permission ALWAYS belongs to an API Resource.

The above figure shows the permission read:item in resource https://api-1.store.io is different from the permission read:item in resource https://api-2.store.io.

If no API Resource is provided, permission will be treated as "for OIDC". Usually this is not what you want in RBAC.

Roles

Roles are a grouping of permissions that can be assigned to users. They also provide a way to aggregate permissions defined for different APIs, making adding, removing, or adjusting permissions more efficient than assigning them individually to users.

Here's an example of an order_admin role with several permissions for two resources:

Also, it's OK to have permission overlap between roles.

Example: An online bookstore

Let's say you have an online bookstore to manage. Here, we greatly simplify the access control model for demonstration purpose.

The model is divided to two major API Resources: orders and products. They have different resource indicators as below:

• Orders: https://api.store.io/orders
• Products: https://api.store.io/products

For each resource, you'd like to separate permissions into read, write, and delete. So you define six permissions in total:

• https://api.store.io/orders
  • Permission read:order
  • Permission write:order
  • Permission delete:order
• https://api.store.io/products
  • Permission read:product
  • Permission write:product
  • Permission delete:product

Here's the illustration of this model:

You want to have two types of admin, order admin and product admin:

• Order admin can manage orders and see products (as orders consist of products), but cannot manage products.
• Product admin can manage products, and they should not be aware of any orders.

So you create two roles, order_admin and product_admin, with the permissions:

• order_admin
  • https://api.store.io/orders
    • read:order, write:order, delete:order
  • https://api.store.io/products
    • read:product
• product_admin
  • https://api.store.io/products
    • read:product, write:product, delete:product

Here's the illustration of these two roles:

It's OK to assign both order_admin and product_admin to a user, then they will have all six permissions you just defined.

Note the order admin shares the permission read:product with the product admin, and the final permissions that a user holds is the union of all permissions from the roles they has been assigned.

Recap

We introduced two new terms: permission and role. To summarize:

• An API resource can hold multiple permissions.
• When we talk about a permission, we are actually talking about "a permission of an API Resource".
• A role is a group of permissions.