Create a directory to store the policies.
mkdir -p cerbos-quickstart/policies
Now start the Cerbos server. We are using the container image in this guide but you can follow along using the binary as well. See installation instructions for more information.
docker run --rm --name cerbos -d -v $(pwd)/cerbos-quickstart/policies:/policies -p 3592:3592 ghcr.io/cerbos/cerbos:0.15.1
Launch a browser and navigate to http://localhost:3592/. You will be presented with a webpage with documentation about the Cerbos API. Click on the
/api/check endpoint to follow the rest of this quickstart guide.
Click on Example tab to view an example of a request you can make to Cerbos. In the example, the
bugs_bunny principal is trying to perform two actions (
comment) on two
album:object resource instances. The resource instance with the ID
XX125 belongs to
bugs_bunny and is private (
public attribute is
false). The other resource instance with the ID
XX225 belongs to
daffy_duck and is public.
Click on the Try button to try out the example request.
|If you prefer to use Postman, Insomnia or any other software that supports OpenAPI, you can follow this guide along on those tools by downloading the OpenAPI definitions from http://localhost:3592/schema/swagger.json.|
The response from the server denies
bugs_bunny from viewing or commenting on any of the album resources — even the ones that belong to him. This is because currently there no policies defined for the
Let’s create a derived roles definition that assigns the
owner dynamic role to a user if the
owner attribute of the resource they are trying to access is equal to their ID.
cat > cerbos-quickstart/policies/derived_roles_common.yaml <<EOF --- apiVersion: "api.cerbos.dev/v1" derivedRoles: name: common_roles definitions: - name: owner parentRoles: ["user"] condition: match: expr: request.resource.attr.owner == request.principal.id EOF
Let’s also create a resource policy that gives
owners full access to their own albums.
cat > cerbos-quickstart/policies/resource_album.yaml <<EOF --- apiVersion: api.cerbos.dev/v1 resourcePolicy: version: "default" importDerivedRoles: - common_roles resource: "album:object" rules: - actions: ['*'] effect: EFFECT_ALLOW derivedRoles: - owner EOF
Try the request again. This time
bugs_bunny should be allowed access to his own album but denied access to the album owned by
Now let’s add a rule to the policy to allow users to view public albums.
cat > cerbos-quickstart/policies/resource_album.yaml <<EOF --- 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 EOF
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?
Once you are done experimenting, the Cerbos server can be stopped with the following command:
docker kill cerbos