# Quickstart

|     |     |
| --- | --- |
|  | This documentation is for<br>a previous<br>version of Cerbos. Choose 0.53.0 from the version picker at the top right or navigate to [https://docs.cerbos.dev](https://docs.cerbos.dev/) for the latest version. |

Create a directory to store the policies.

```sh
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](https://docs.cerbos.dev/cerbos/0.48.0/installation/binary) for more information.

```shell
docker run --rm --name cerbos -d -v $(pwd)/cerbos-quickstart/policies:/policies -p 3592:3592 -p 3593:3593  ghcr.io/cerbos/cerbos:0.48.0
```

Time to try out a simple request.

|     |     |
| --- | --- |
|  | If you prefer to use [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/) 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](http://localhost:3592/schema/swagger.json). You can also use the built-in API browser by pointing your browser to [http://localhost:3592](http://localhost:3592/). |

### Example Request using cURL

```shell
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
```

### Example Response

```json
{
  "requestId": "quickstart",
  "results": [
    {
      "resource": {
        "id": "BUGS001",
        "kind": "album:object"
      },
      "actions": {
        "comment": "EFFECT_DENY",
        "view:public": "EFFECT_DENY"
      }
    },
    {
      "resource": {
        "id": "DAFFY002",
        "kind": "album:object"
      },
      "actions": {
        "comment": "EFFECT_DENY",
        "view:public": "EFFECT_DENY"
      }
    }
  ]
}
```

In this example, the `bugs_bunny` principal is trying to perform two actions (`view:public` and `comment`) on two `album:object` resources. The resource instance with the ID `BUGS001` belongs to `bugs_bunny` and is private (`public` attribute is `false`). The other resource instance with the ID `DAFFY002` belongs to `daffy_duck` and is public.

### Derived Roles Example

Now create a defined derived roles definition that assigns the `owner` dynamic role to a user if the `owner` attribute of the resource they’re trying to access is equal to their ID.

```sh
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
```

Also create a resource policy that gives `owner`s full access to their own albums.

```sh
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
```

### Update the Policy Example

Try the request again. This time `bugs_bunny` should be allowed access to his own album but denied access to the album owned by `daffy_duck`.