Quickstart

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 -p 3593:3593  ghcr.io/cerbos/cerbos:0.32.0

Time to try out a simple request.

• cURL

• .NET

• Go

• Java

• JS

• PHP

• Python

• Ruby

• Rust

cat <<EOF | curl --silent "http://localhost:3592/api/check/resources?pretty" -d @-
{
  "requestId": "quickstart",
  "principal": {
    "id": "bugs_bunny",
    "roles": [
      "user"
    ],
    "attr": {
      "beta_tester": true
    }
  },
  "resources": [
    {
      "actions": [
        "view:public",
        "comment"
      ],
      "resource": {
        "kind": "album:object",
        "id": "BUGS001",
        "attr": {
          "owner": "bugs_bunny",
          "public": false,
          "flagged": false
        }
      }
    },
    {
      "actions": [
        "view:public",
        "comment"
      ],
      "resource": {
        "kind": "album:object",
        "id": "DAFFY002",
        "attr": {
          "owner": "daffy_duck",
          "public": true,
          "flagged": false
        }
      }
    }
  ]
}
EOF

using Cerbos.Api.V1.Effect;
using Cerbos.Sdk.Response;
using Cerbos.Sdk.Builder;
using Cerbos.Sdk.Utility;

internal class Program
{
    private static void Main(string[] args)
    {
        var client = CerbosClientBuilder.ForTarget("http://localhost:3593").WithPlaintext().Build();
        var request = CheckResourcesRequest
            .NewInstance()
            .WithRequestId(RequestId.Generate())
            .WithIncludeMeta(true)
            .WithPrincipal(
                Principal
                    .NewInstance("bugs_bunny", "user")
                    .WithAttribute("beta_tester", AttributeValue.BoolValue(true))
            )
            .WithResourceEntries(
                ResourceEntry
                    .NewInstance("album:object", "BUGS001")
                    .WithAttribute("owner", AttributeValue.StringValue("bugs_bunny"))
                    .WithAttribute("public", AttributeValue.BoolValue(false))
                    .WithAttribute("flagged", AttributeValue.BoolValue(false))
                    .WithActions("comment", "view:public"),

ResourceEntry
                    .NewInstance("album:object", "DAFFY002")
                    .WithPolicyVersion("20210210")
                    .WithAttribute("owner", AttributeValue.StringValue("daffy_duck"))
                    .WithAttribute("public", AttributeValue.BoolValue(true))
                    .WithAttribute("flagged", AttributeValue.BoolValue(false))
                    .WithActions("comment", "view:public")
            );

CheckResourcesResponse result = client.CheckResources(request);
        foreach (var resourceId in new[] { "BUGS001", "DAFFY002" })
        {
            var resultEntry = result.Find(resourceId);
            Console.Write($"\nResource ID: {resourceId}\n");
            foreach (var actionEffect in resultEntry.Actions)
            {
                string action = actionEffect.Key;
                Effect effect = actionEffect.Value;
                Console.Write($"\t{action} -> {(effect == Effect.Allow ? "EFFECT_ALLOW" : "EFFECT_DENY")}\n");
            }
        }
    }
}

package main

import (
    "context"
    "log"

"github.com/cerbos/cerbos-sdk-go/cerbos"
)

func main() {
    c, err := cerbos.New("localhost:3593", cerbos.WithPlaintext())
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

principal := cerbos.NewPrincipal("bugs_bunny", "user")
    principal.WithAttr("beta_tester", true)

kind := "album:object"
    actions := []string{"view:public", "comment"}

r1 := cerbos.NewResource(kind, "BUGS001")
    r1.WithAttributes(map[string]any{
        "owner":   "bugs_bunny",
        "public":  false,
        "flagged": false,
    })

r2 := cerbos.NewResource(kind, "DAFFY002")
    r2.WithAttributes(map[string]any{
        "owner":   "daffy_duck",
        "public":  true,
        "flagged": false,
    })

batch := cerbos.NewResourceBatch()
    batch.Add(r1, actions...)
    batch.Add(r2, actions...)

resp, err := c.CheckResources(context.Background(), principal, batch)
    if err != nil {
        log.Fatalf("Failed to check resources: %v", err)
    }
    log.Printf("%v", resp)
}

The following code snippets are examples in different languages to perform similar operations.

import json
from cerbos.sdk.client import CerbosClient
from cerbos.sdk.model import Principal, Resource, ResourceAction, ResourceList
from fastapi import HTTPException, status

principal = Principal(
    "bugs_bunny",
    roles=["user"],
    attr={
        "beta_tester": True,
    },
)

actions = ["view:public", "comment"]
resource_list = ResourceList(
    resources=[
        ResourceAction(
            Resource(
                "BUGS001",
                "album:object",
                attr={
                    "owner": "bugs_bunny",
                    "public": False,
                    "flagged": False,
                },
            ),
            actions=actions,
        ),
        ResourceAction(
            Resource(
                "DAFFY002",
                "album:object",
                attr={
                    "owner": "daffy_duck",
                    "public": True,
                    "flagged": False,
                },
            ),
            actions=actions,
        ),
    ],
)

with CerbosClient(host="http://localhost:3592") as c:
    try:
        resp = c.check_resources(principal=principal, resources=resource_list)
        resp.raise_if_failed()
    except Exception:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN, detail="Unauthorized"
        )
print(json.dumps(resp.to_dict(), sort_keys=False, indent=4))

After you have defined the policies, you can perform checks as previously and see the updated responses.

After you are done experimenting, the cerbos server can be stopped with the command:

docker kill cerbos