How Cerbos Works
Watch the videos and hover over the diagram below to learn how applications interact with Cerbos
When a user performs an action, the first thing that would happen in the application layer is the unbundling of that request to understand who is trying to perform what action; and on which resource or object.
The application layer then further unbundles these two data points:
- User’s identity: The attributes like the groups the user is a part of; or the departments and/or geographies it belongs to.
- The resource that is being accessed or mutated: What state that object is in, and any additional information about its attributes.
In order to make a decision whether an action should be allowed; traditionally one would implement an if-then-else block based on the principal and resources attributes. This block would implement a conditional branch based on all the contextual information gathered.
Cerbos decouples and centralizes the logic out of the application code. All of the information about the principal, action and the resource gets submitted via Cerbos SDK to its API.
The SDK interacts with the Cerbos instance that would be running within your environment via the REST API or gRPC. Cerbos makes a decision whether that action should be allowed or not. See point 4 for more details about the request.
There are two main types of requests an application can issue to Cerbos.
One for checking permissions; either individually or in a batch, and another one to get a Query Plan.
Every request that comes to Cerbos includes the details and attributes of the principal, and the properties of the resource that the principal is trying to act on.
Cerbos replies with a very simple true/false response, which can be implemented in the application. In the future, if the decision logic changes, aka the policy, the application code does not have to change.
Cerbos API can also return a Query Plan. See the Allow/Deny and Query Plan boxes below for more details.
Every decision that Cerbos makes get logged with the full details of the request, decision and why/how that decision was made: which policy it matched etc.
The application can send either individual or batch requests to the “check” end point for each principal. By evaluating each request, considering the context, Cerbos returns allow or deny answer to each resource-and-action pair. At this point the application implements how it should proceed if the action is allowed or how to proceed if the action is denied.
This way, when the decision making logic changes, your application code does not need to change.
Another request type the application can send to Cerbos is a request for a Query Plan. This is useful if the application has millions of objects it needs to quickly filter based on the user’s permission.
For example: to render a listing page, fetching only the objects the user has edit, delete, update etc. permissions on.
Cerbos is capable of returning the filtering logic the application needs to apply against its data storage to fetch the right objects the user has permissions to perform the specific action on.
The Query Plan API returns an abstract syntax tree (AST) that you can implement in your application’s data fetching layer.
If the application is in Node.js and make use of the Prisma ORM, Cerbos has an integration you can use out of the box.
The application layer also further unbundles the object the action is being taken on. The application provides the details on that object in the request call.
Finally the application can reply to the user or the front end with the appropriate answer based on the output the implementation produces.
Cerbos can run as a binary on bare metal machine or VM; or you can deploy Cerbos’s container in your environment. You can even run Cerbos on serverless infrastructure like AWS Lambda, Google Cloud Functions or Google Cloud Run.
If Cerbos is deployed to a container orchestrator like Kubernetes, it can be run either as a service or as a sidecar.
Cerbos is a stateless decision engine that will make decisions based on the incoming request and the provided policies.
No matter which storage method you choose, you can always use the Cerbos’s unit testing framework and policy validation tools before making changes to your environments.
Once policies are loaded, the Cerbos instance is ready to process incoming requests via its REST and gRPC APIs, and log both the requests it receives and decisions it makes.
When Cerbos starts, after reading its configuration file, it finds its policies and loads them into memory. It uses these policies to make its decisions.
The access rules for each resource and action are stored in the policy files. In addition to the resource policies, these files can also include derived role definitions, individual principal policies, and request attribute requirements.
Cerbos does not have to reload or look up the policies every time it gets a new request. However, on a periodic basis it can monitor the storage for updates and automatically hot-reload the latest policy. Alternatively one can always use an admin end point to force a refresh of policies on an instance..
The policies can be stored in three different main storage types: git, disk, or database.
For git-based policy storage, Cerbos is capable of storing and checking policies from any git repository and branch you give it access to.
Cerbos also comes with a full unit testing framework and Github Actions, making deployment of policy changes via CI/CD pipeline easy to implement.
Policies can also be stored on a disk. If you choose this option, a typical installation usually has the policy files with the codebase or on a Cloud Storage location such as Google cloud storage or any S3 API compatible Cloud Storage.
You may choose a database-backed storage. This is an ideal solution if your application is planning to make programmatic changes to the policies. You can connect to the Admin API to make changes, and it will automatically take care of all the change management and the audit trail. Currently Cerbos supports SQLite, MySQL, Postgres, and MSSQL out of the box.
Book a free Policy Workshop to discuss your requirements and get your first policy written by the Cerbos team