How To Create a Policy

This step-by-step guide will cover how to define a CERBOS resource, then how to set its policies. For example: The resource 'Death Star Plans', has a policy that Rebels are denied access but Sith Lords are granted access

We assume the following:

• The app is named death-star and sits under the apps/death-star

1. Create a folder for your policies in the app's directory

Create the cerbos structure in the app's directory (see Cerbos Best Practices).

apps/death-star/
  cerbos/
    _schemas/
    derived_roles/
    principal_policies/
    resource_policies/

2. Create a Schema File

Under the ./apps/death-star/cerbos/_schemas directory:

• Create a file in the new directory which defines your resource, ie death-star-plans.json
• In the new file define the structure of your resource

It should look something like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "locationOfDeathStarWeakSpot": {
      "type": "string"
    }
  },
  "required": ["locationOfDeathStarWeakSpot"]
}

3. Create Resource Policy

• In the ./apps/death-star/cerbos/resource_policies directory create a new file with the format <resource_name>.yaml, ie death_star_plans.yaml
• In this new file define the policies you wish to apply to the resource, as an example:

# yaml-language-server: $schema=https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json
---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  version: 'default'
  resource: 'death-star-plans'
  rules:
    - actions: ['view']
      effect: EFFECT_ALLOW
      roles:
        - sith_lord
    - actions: ['view']
      effect: EFFECT_DENY
      roles:
        - member_of_rebel_alliance

  schemas:
    principalSchema:
      ref: cerbos:///principal.json
    resourceSchema:
      ref: cerbos:///death-star-plans.json

4. Create CERBOS Tests

• Go to the directory ./apps/death-star/cerbos/resource_policies and create a directory called testdata and create two files principals.yaml and resources.yaml, these will be used as our test-data when writing CERBOS tests to verify our policies work.

---
principals:
  # user
  darth_vader:
    id: darth_vader
    roles:
      - sith_lord
    attr:
  han_solo:
    id: han_solo
    roles:
      - member_of_rebel_alliance
    attr:

---
resources:
  basket:
    id: death-star-plan-1
    kind: business-death-star:death-star-plans
    attr:
      locationOfDeathStarWeakSpot: 'ventilation duct'

• In the cerbos/tests/business-<service-id> directory add a file with the name <resource_name>_test.yaml.
• Using the test resource and principals you just created define your CERBOS test expectation, It should look something like this:

# yaml-language-server: $schema=https://api.cerbos.dev/latest/cerbos/policy/v1/TestSuite.schema.json
---
name: Death Star PlansTestSuite
description: Tests for verifying the death-star:death-star-plans resource policy

tests:
  - name: Death Star Plans Access
    input:
      principals:
        - rebel-soldier
        - darth-vader
      resources:
        - death-star-plans
      actions:
        - view
    expected:
      - principal: darth-vader
        resource: death-star-plans
        actions:
          view: EFFECT_ALLOW
      - principal: rebel-solider
        resource: death-star-plans
        actions:
          view: EFFECT_DENY

Official documentation on CERBOS testing can be found here.

5. Run the Tests

Tests can be run be executing the test:cerbos target in Nx. This will be automatically registered if you have the cerbos/ directory in your application.

nx run death-star:cerbos