August 29, 2022

Navigating user permissions with Cerbos.

In this article, I discussed the issues with building user permissions from scratch and how Cerbos can assist developers to replace complicated, hardcoded permissions logic with a simple API request.

Navigating user permissions with Cerbos.

User permissions (authorizations and authentication) are an indisputable aspect of most systems’ essential operation, and they demand careful consideration in terms of design, structure, and construction.

Image Source (Actitime)

As software engineers, products like Okta and Auth0 come to mind as tools for navigating user authentications, and then you investigate different authorization policies and models depending on the Infrastructure you want to use, of which ABAC, RABC, LDAP, or SAML (single sign-on authentication) are just a few examples.

Understanding Authorizations and Authentications and why you should care

Authorization is the process of giving someone the ability to access a piece of information.

Authorization rules are part of the Identity and Access Management group in computing, and we can simply define it as the identification of system managers to control and validate users who have access to system resources and set client privileges.

While User authentication is a security process that prevents unauthorized users from accessing your device or network, It’s a login procedure where an application requests personalized passwords to give you authorized access to it. If a user lacks the proper login rights to the network, their authentication fails.

There is almost no doubt that authorization, as overlooked as it is, is one of the most complicated to get right and a possible future threat if not done correctly since minor errors or misconfiguration might result in millions of user records being exposed.

Sign Language Permission GIF By ISL Connect

While researching the best options for properly navigating user permissions without having to worry about the problems that come with it, one product stood out as the central focus of this article.

Cerbos is an open-source decoupled access control for your software making user permissions and authorization simple to implement and manage.

With cerbos, user permissions become a plug-in solution and you do not have to build from scratch or worry about exposing user details as cerbos provides you with a Low-code, human-readable configuration and goes way beyond basic role-based-access-control with context-aware role definitions and attributes and you can get it implemented and running in minutes.

A typical code without Cerbos:

With Cerbos:

How Cerbos Works

So let’s start with the basics of this diagram, which shows how your application would interact with Cerbos.

When a user performs an action, the application layer unbundles that request to determine who is attempting to perform what action and on which resource or object. The application layer then unbundles these two data points further.

The first is the user’s identity, which could include things like the groups the user is a part of or the departments and or geographies it belongs to; the second is the resource or object that is being accessed or mutated; the application knows what state that object is in and any additional information about its attributes at this point in order to make a decision whether or not that activity should be permitted.

Traditionally, you would construct an if then else block that implements a conditional branch depending on all of the preceding bits of information we discussed. Cerbos decouples and centralizes that logic out of your application code, as seen in this figure. The call to the SDK would provide information about the user action and the resource, and it would ask Cerbos to decide whether or not that action should be allowed. The SDK interacts with the servos instance running within your environment via the rest API or GRPC based on the policies defined.

The application that uses the Cerbos SDK would implement a very simple API for two different courses one for action allowed and another for action denied. This way, you would not have to change your application code when the rules of what should be allowed change.

Installing and using the Cerbos API

To install cerbos using Docker (run from a container):

docker run --rm --name cerbos -p 3592:3592

You should see something like this:

Screenshot from running Cerbos with a container

Creating a directory for the policies and config files

mkdir -p cerbos-quickstart/policies

Creating a config file

cat > cerbos-quickstart/conf.yaml <<EOF
httpListenAddr: “:3592”
driver: “disk”
directory: /quickstart/policies
watchForChanges: true

Launching the container with the config files

docker run — rm — name cerbos -d -v $(pwd)/cerbos-quickstart:/quickstart -p 3592:3592 server — config=/quickstart/conf.yaml

A screenshot of what you would have running on your Docker desktop client

You can view the latest API documentation from a running Cerbos instance by running:

docker run --rm --name cerbos -p 3592:3592 -p 3593:3593

or you can easily navigate to http://localhost:3592/ using your browser.

Screenshot of the Cerbos API docs on localhost

Demo Implementation

To test out the Cerbos practical Demo, you can begin by cloning any of these examples depending on your preferred languages:

We would use the Application (Python) and the following calls in the application to query the Cerbos PDP and make policy decisions. To get started, you can use the Cerbos PDP hosted demo instance.
Note: If you’re deploying for production use cases, a self-hosted instance should be deployed for security and latency reasons.

Cerbos PDP Instance:

To install the Cerbos NPM package

npm i @cerbos/sdk
// or
yarn add @cerbos/sdk

Configuring the Cerbos Client

Then wherever is needed in the business logic, you can call Cerbos to check the authorization.

Alternatively, you can watch this tutorial to see Cerbos policies in action.


In this article, I discussed the issues with building user permissions from scratch and how Cerbos can assist developers to replace complicated, hardcoded permissions logic with a simple API request. I also gave code snippets for running Cerbos, integrating the APIs, and seeing Cerbos policies in action.