Cerbos is an authorization solution that's designed to simplify access control in your applications. With Cerbos, you don't have to hard-code complex authorization logic into your applications. Instead, Cerbos allows you to manage authorization using defined policies that can work with Cerbos Policy Decision Point (PDP) or through a centralized policy administration hub called Cerbos Hub.
In this article, you'll get a general overview of Cerbos and how to start using it today. Along the line, you'll learn the following:
- The problem that Cerbos aims to solve
- Explanation of Cerbos PDP and Cerbos Hub
- How to start using Cerbos PDP and Cerbos Hub
- Overview of Cerbos SDKs
- Where to get help when you're stuck
The Problem That Cerbos Aims To Solve
Gone are the days when you have to write complex authorization logic in your code. Undoubtedly, this will contain complex if/else
statements, possibly making your code difficult to read or understand. What's more, and depending on the complexity of the application, this can take months of developer time. With Cerbos, you can reduce this time. How? Allow me to explain.
First, Cerbos introduces a policy-first approach to authorization. This allows you to decouple the rules for who can access what from your application logic, ensuring access control decisions are consistent, transparent, and easy to maintain across your application. What's more, you can create fine-grained authorization rules tailored to your application's needs because Cerbos supports role-based access control (RBAC) and attribute-based access control (ABAC).
Now, you'll ask: How does Cerbos achieve this? And how can I see how this works? To answer these questions, we'll have to explore Cerbos PDP and Cerbos Hub. Let's begin with Cerbos PDP.
Cerbos PDP: What It is and How it Works
Cerbos PDP (Policy Decision Point) is an open-source, scalable authorization solution that allows you to manage access control in your application through policies defined in YAML files. The image below shows how it can fit into your application architecture. What follows is an explanation.
Request Flow
When a Client App submits a request to access a resource, the request is forwarded to the API. This in turn sends it to the Application. The latter interacts with the Cerbos Policy Engine through its API or SDK by passing three key components.
These are:
- Subject: The user or entity making the request.
- Action: The operation the subject intends to perform (e.g., view, edit, delete).
- Resource: The object the subject wants to act upon (e.g., a document or album).
Policy Evaluation
The Cerbos Policy Engine evaluates the request against your policies that's either stored on disk or a cloud storage like Git. Cerbos performs this evaluation to determine whether to ALLOW or DENY the user action. For example, Cerbos might check if the user is the owner of the resource, or if the resource is marked as public. Based on this evaluation, Cerbos returns ALLOW if the request satisfies the policy or DENY otherwise.
Advanced Features
- Query Criteria: This feature provides granular filtering of resources based on specific attributes.
- Logs: Every decision made by Cerbos is logged, creating an audit trail.
- Test Framework: Cerbos includes a Test Framework (referred to as Play) that lets you test policies in isolation.
Practical Example
To see Cerbos PDP in action, you can follow the example detailed on the Quickstart page in the documentation. Mind you, if you're running on Microsoft Windows, ensure that you update the Docker command appropriately.
Therefore, change the following command:
docker run --rm --name cerbos -d -v $(pwd)/cerbos-quickstart/policies:/policies -p 3592:3592 -p 3593:3593 ghcr.io/cerbos/cerbos:0.40.0
To the following and replace YOUR_WINDOWS_USER_NAME accordingly:
docker run --rm --name cerbos -d -v C:/Users/YOUR_WINDOWS_USER_NAME/cerbos-quickstart/policies:/policies -p 3592:3592 -p 3593:3593 ghcr.io/cerbos/cerbos:0.40.0
If you have done everything correctly, browse the built-in API browser by pointing your web browser to http://localhost:3592
. You should have something similar to the following UI:
Finally, after following the aformentioned tutorial and you choose to accept the challenge at the end of the page, which says:
If you try the request again, bugs_bunny now has view:public access to the album owned by daffy_duck but not comment access. Can you figure out how to update the policy to give him comment access as well?
Your resource_album.yaml
file should match the following:
---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
version: "default"
importDerivedRoles:
- common_roles
resource: "album:object"
rules:
- actions: ['*']
effect: EFFECT_ALLOW
derivedRoles:
- owner
- actions: ['view:public']
effect: EFFECT_ALLOW
roles:
- user
condition:
match:
expr: request.resource.attr.public == true
- actions: ['comment']
effect: EFFECT_ALLOW
roles:
- user
condition:
match:
expr: request.resource.attr.owner != request.principal.id &&
request.resource.attr.public == true
As a result, sending the request to the application should result in the following response from the Cerbos PDP:
[
{
"checkResourcesResult": {
"resource": {
"id": "BUGS001",
"kind": "album:object",
"policyVersion": "",
"scope": ""
},
"actions": {
"comment": "EFFECT_ALLOW",
"view:public": "EFFECT_ALLOW"
},
"validationErrors": [],
"metadata": undefined,
"outputs": []
}
},
{
"checkResourcesResult": {
"resource": {
"id": "DAFFY002",
"kind": "album:object",
"policyVersion": "",
"scope": ""
},
"actions": {
"comment": "EFFECT_ALLOW",
"view:public": "EFFECT_ALLOW"
},
"validationErrors": [],
"metadata": undefined,
"outputs": []
}
}
]
Cerbos Hub: Policy Management and Deployment Made Easy
Cerbos Hub is where you can manage the policies for your application. It has a CI/CD pipeline feature, built-in testing features, fast deployment of policies to connected PDP's, and more. The following image is a high-level overview of how it works. What follows is a summary of what's going on.
The following is a summary of what's going on in the image above:
- The Client App sends a request to the API Gateway.
- The API Gateway forwards the request to the Application.
- The Application queries the Cerbos PDP (or Embedded PDP) with three things. These are the Subject, Action, and Resource.
- The Cerbos PDP evaluates the request using policies and either ALLOW or DENY the action.
- You can author and manage policies via the Cerbos Hub, which is synchronized with a Git Repo.
- Logs and metrics provide visibility into decision-making
To start using Cerbos Hub, visit the website, and sign up for an account. The welcome wizard will walk you through and make you feel comfortable. If you need any help, take a look at the Cerbos Hub documentation.
As a heads-up, the following is the User Interface of Cerbos Hub after you have successfully signed up or logged in. Note that Test_Org
is for testing purposes, and you can select your organization name during initial setup.
The Workspace (accessible from Workspaces in the image above), is where you can connect your Git repository to Cerbos Hub. Any changes that you make to the repository will be synchronized with the Hub. In the image below, I forked the policy example-cerbos-policy-repository, and I have connected to it.
From the image, please, understand the following:
- The Organization ID uniquely identifies your organization within Cerbos.
- The Workspace ID represents the specific environment you are managing within the organization.
- The Policy store section tells you where your policy files are stored. In this case, the policies are stored in my GitHub repo named
ziizium/example-cerbos-policy-repository
. - The Latest builds section tracks the history of your policy builds. Audit logs are used to track every decision made by the system, such as whether access was granted or denied.
Cerbos Amplifies the Developer Experience Using SDKs
Cerbos provides SDKs for popular languages and frameworks. Here, we'll explore the JavaScript SDK and the code example that's used in the official documentation.
To get started, do the following:
- Ensure that you have Node.js installed
- Create a new project directory
- Initiate a new Git repository (optional)
- Install the following individual packages from npm.
npm i cerbos
npm i @cerbos/grpc
Next, do the following:
- Ensure that you have the policies that you used earlier when you explored the tutorial on the Quick start page in the documentation.
- Go to the Quickstart page, and copy the code under the JS tab.
- Save the code as
index.js
in your project directory. - Start Cerbos PDP via Docker.
- Open the terminal or command prompt in your project directory.
- Run
node index.js
via the command line, and observe the response from the Cerbos PDP.
The following image is a sample response from the Cerbos PDP. You should have something similar provided that followed the tutorial on the Quickstart page, and you accepted the challenge.
Where To Get From Here
We have barely scratched the surface of what you can do with Cerbos. Now, if you're thinking Cerbos is what you need for authorization and not some complex or complicated if/else
statements, then I have successfully achieved what I set out with this article.
Meanwhile, that does not mean that you're not going to need help along the way. When that happens to you, turn to the documentation of Cerbos PDP or that of Cerbos Hub. You can also join the Cerbos official Slack channel or explore the official website of Cerbos.
Top comments (0)