Get started with Cerbos Hub

Managing permissions and authorization for SaaS applications is a critical challenge that developers, security, and product teams face. And we’re not exaggerating it, the Open Worldwide Application Security Project (OWASP) has named authorization a top 10 API security risk multiple years in a row.

Everyone at Cerbos strives to make solving permissions and authZ challenges as smooth as possible for software development teams. In software development, setting up access rules, known as authorization policies, is crucial for security and proper functioning. However, making and updating these rules can often be tricky and take a lot of time, especially in large or complex projects.

Cerbos PDP vs Hub

You may already know of our open source solution - Cerbos Policy Decision Point (PDP); a devtool which helps developers enforce access control over different parts of their software. If you need to learn more about Cerbos in general, we strongly recommend checking out the website and the docs.

While Cerbos PDP enables you to make decisions against your access control policies, Cerbos Hub helps you manage and synchronize PDP instances across all your apps and services, increasing security through consistency in policies everywhere, and saving you hours of time.

Cerbos Hub also helps you collaborate, validate, and test policies in real-time in an IDE environment and quickly adapt to changing app requirements.

Cerbos Hub can deploy authorization within browsers, serverless architectures, embedded devices, and at the edge. This is especially helpful for teams that need to frequently adjust their rules or manage a large number of them.

By using Cerbos Hub, developers can focus on building and improving their software, rather than spending too much time updating access management.

So far, so good? Great!

Now, let me walk you through the process of getting started with Cerbos Hub.

Setting up Cerbos Hub

Go to https://hub.cerbos.cloud/ and you will land on a page looking like the one from the screenshot below.

Click on the Log in or sign up button on the left-hand side. That will lead you to the login/signup page. Choose to sign in with your Google or GitHub ID, or create a new ID with your email address.

Next you’ll see the set-up wizard appear with instructions on how to set up your workspace. Take your time and read the instructions there, before clicking the Connect my policy repository button.

If you already use Cerbos PDP, you’ve most likely created a policy repository. You’ll need to grant Cerbos Hub access to your GitHub profile/organization by navigating to your GitHub account. Then click the ‘Refresh list’, and your repository will appear listed in the dropdown.

If you don’t have a ready policy repository, you can get started with one of our templates, which is linked in the prompt right below the GitHub access prompt. The example repository contains all the necessary features to let you experiment with Cerbos Hub and get you up to speed with its capabilities.

When you’ve successfully selected the policy repository you want to use in your workspace, click ‘Continue’ and move on to the final step of your workspace setup. Make sure to set a proper name for your workspace, and define the branch from which you want the Hub to read your .cerbos-hub.yaml file. And if the repository you’re connecting is a full-fledged project, make sure to define a path to the directory that holds your Cerbos policies.

With that, your workspace is set, and you’ll be provided with a secret key. Make sure to safely store it before closing the dialog box.

Now that everything is set, you’re ready to access your Cerbos Hub.

Your Hub homepage will look something like this:

On the left-hand side, you’ll see a sidebar menu, and the majority of your screen will be filled with whatever item on that sidebar is selected. Right now you’re looking at the screenshot for the ‘Home’ page of this demo workspace.

Managing The Hub

Right after successfully connecting, the Hub will try to run builds against the configuration found in your repository.

My build seems to be failing at the compilation level. Let me check the commit to find out more about what is going wrong.

It seems when connecting the repository, we didn’t set the correct path for where our policies are stored. If you make a similar mistake, you’ll want to correct it right away. So let’s fix that real quick.

Select the Settings option of the sidebar, type the correct policy directory, and click the Update button.

This change will trigger an automatic rebuild, so quickly go back to the Builds page, and check what happened.

Everything seems to be working just fine; the build is generated, and all of the labels and options provided in configuration are recognized. Now whenever we update our connected policy repository, those changes will be recognized and the builds for each of the changes will run automatically.

What we showed here is how easily you can connect your policy repositories with the Cerbos Hub, and how to troubleshoot on the fly.

Connect the PDP to the Hub

Now let’s deploy the Cerbos PDP instance that will be connected to the Cerbos Hub.

Navigate to the Decision points page in the sidebar. This page keeps all the important information regarding your deployed PDPs, as well as the tools to deploy more of them.

Considering you’ve just created your Hub a couple of minutes ago, this should be a fairly empty page, looking similar to the screenshot below.

Click on the Deploy a decision point button, and you’ll see a modal with several options, each containing its own set of instructions.

Being a Mac person, for this piece I chose to select Homebrew. Whatever you choose, take some time to read and understand the provided steps.

Upon selecting your preferred deployment method, you’ll be able to select what deployment label you’d like to link it to. Our demo came with latest, main and production labels included in the .cerbos-hub.yaml file, so I’ll deploy an instance linked to latest.

That means every single time I make a change to a policy repository having the label latest, Hub will automatically notify the PDP, resulting in a seamless real-time delivery, with no service redeployments or downtime whatsoever.

For more PDP configuration details, make sure to read the full configuration reference.

Given I already have Cerbos installed, the brew tap cerbos/tap along with the brew install cerbos step would be redundant, but it doesn’t hurt to double-check.

Pay special attention to the contents of the conf.yaml file. For the sake of getting started, in the desired directory create a config.yaml file, then click on the copy icon at the top right of the config.yaml snippet on the instructions modal and paste it to the created file, then save it.

Upon creating the workspace, you were asked to save the private key provided to you. You will use that key now to replace the value of the workspaceSecret field of the credentials part of your config.yaml file.

For the clientID and the clientSecret fields, navigate to the Settings page in your left sidebar, and click the Generate a client credential button in the right lower corner.

You’ll then be prompted to name the credential. After you do, click Create client credential.

Make sure to copy the Client ID, and paste it as the values of the clientID and clientSecret fields of your config.yaml file. Upon finishing, you’ll now have it listed on the Settings page, right beneath the Policy Repository details.

Now that you’ve replaced the credentials fields with the values relevant to your workspace, and (if you’re also doing it via Homebrew) simply run the cerbos server –config=./conf.yaml command in the terminal, positioned in the directory where you created the conf.yaml file.

Your PDP instance(s) should now appear on the Decision points page.

That’s it! Your policy repository is now connected to the Hub, as well as the PDP instance(s) we just deployed. You can deploy as many of them as you wish. Cerbos is stateless so you can scale as you need, without worrying about instances being out of sync or losing performance on heavy load periods.

To Conclude

Cerbos Hub helps developers focus on building and improving their software, rather than spending too much time on upgrading access management. It helps connect your Cerbos policy repository and your Cerbos PDP instances and manage them collaboratively and smoothly from a single place.

This piece was an intro to Cerbos Hub, showing all the basic steps needed to get it up and running. In upcoming posts we will show you more complex and detailed cases to help you navigate through the Hub with ease.

If you’ve been following this tutorial step-by-step, your policy repo and PDP should be connected to the Hub by now. Let us know how it went in our Cerbos Slack Community. If you stumbled upon any challenges, don’t hesitate to reach out. We’ll be happy to help!