Introduction
Welcome to Space Blocks Permissions! 👋
You are looking at the documentation of a powerful Permissions Engine. It acts as a building block for your applications and allows you to define roles and access rights, assign them to your users, and perform permission checks and queries against them with ease. This is not another library. It's a hosted permission service that you can integrate into your applications with a few API calls or by using our SDKs.
Why do I need this?
Managing permissions is a very common requirement in most software applications. At some point, we want to define which users do have access to which resources and what the actions are that they are allowed to perform on them.
What might sound simple (and solvable with a few Arrays/Dictionaries at first) can become very complex quickly. So complex, that Google published a research paper called Zanzibar about their challenges with this problem. What about multi-tenancy? How can I make it scalable? How to group multiple access rights into roles? How to handle inheritance? How can I get all the resources, to which user has specific permissions on? These are just a few questions that you will have to answer when implementing a permission system.
The good news is: You don't have to implement it yourself. We did it for you. And we did it in a way that it can be used in any application, no matter if it's a web app, a mobile app, or a backend service, and no matter if it's a simple, flat use case or a hierarchical multi-tenant resource tree across multiple levels. It's a hosted service that you can integrate into your applications with a few API calls or by using our SDKs.
Basic Example
Imagine you build an accounting application that allows users to create and manage invoices.
User Alice should have all permissions in a tenant, whereas user Bob, who is an external Tax Accountant, should only be able to View "Invoice" resources. For this, Alice gets the Admin role assigned and Bob gets the Invoice Viewer role assigned.
When opening the application, Alice now sees everything, while Bob only sees the Invoices. When Bob tries to access a resource that he is not allowed to, he gets an error. For every new resource that is created, the access rights are automatically calculated and stored in the system.
Whenever Alice searches for a resource, the system automatically filters the results based on her permissions. When Bob searches for a resource, he only sees the Invoices.
For every new resource that is created, the access rights are automatically calculated and stored in the system.
Recap what Space Blocks Permission does for you in this example:
- Ensures that all resources automatically get the correct permissions per user assigned
- Provides simple API/SDK endpoints to assign roles and permissions to users
- Provides simple API/SDK endpoints to filter search results based on permissions
- Blocks Bob from accessing resources other than invoices
Hierarchical Example
Imagine you build a file management application that allows users to create and manage files and folders.
User Alice creates a folder within Tenant A. She also creates a file picture.png in that folder. User
Bob, is not part of this tenant. He is a member of Tenant B and this should never be able access or see
this file. User Charlie however is a member of Tenant A but does not get access to the file by default,
since he is not the file's creator. Alice can assign the Viewer role with Read permissions to
Charlie if she wants, to give him read-only access.
But in order for Charlie to be able to view the file in the UI with a folder-structured tree, he must be given Read Permissions on the containing folder itself additionally. Based on its configuration, this "upward inheritance" is done automatically by using the Permissions Space Block, you don't need to take care of this separately.
Moreover, Alice, as the creator of the folder, automatically gets the same permissions that she has in that folder for any subfolder, or file she creates inside that folder! Yet, Charlie gets to see only what Alice lets him see. The Permissions Space Block also automatically takes care of that.
Lastly, permissions can also be inherited. So if Charlie would get the Admin role assigned to the whole Tenant A, based on your configuration, this would automatically imply that he gets all permission on each folder, subfolder and file within that tenant.
Recap what Space Blocks Permission does for you in this example:
- Ensures that a file's creator automatically has read, write, and delete permissions on the file
- Provides simple API/SDK endpoints to assign roles and permissions to users
- Automatically assigns permissions to a user on a resource's parent folder if the user has permissions on the resource itself
- Inherits existing permissions on a resource's parent (like a tenant)
- Blocks Bob from accessing the file since he is not part of the tenant
How does it work?
The Permissions Space Block is hosted and fully managed by us. Managing and checking user permissions on specific resources, creating groups, assigning roles, and so on is done via a call to our service - either via API or by using our SDKs. The service can be configured to your use-case and needs via our cloud portal or the Management API.
After authentication, your clients can call the Permissions API directly, to manage and check permissions. For mutating operations or queries that need to be filtered by what a user or group is allowed to access, your backend services also call the Permissions API.
What can it do?
Customize the module to your needs:
- Define your permissions structure (flat or hierarchical)
- Define available permissions (read, write, delete, ...) for each resource type
- Define your roles (which are permission bundles)
- Define rules (which permissions should be automatically assigned and when)
Modify permissions:
- Assign or unassign users to resources with a role
Check permissions:
- Check if a user has a specific permission on a resource
- List all resources that a user has specific permissions on
- List all users who have permissions on a resource
Check out the Scenarios section for more details and examples.