Conditions

A powerful feature of Cerbos policies is the ability to define conditions that are evaluated against the data provided in the request. Conditions are written using the Common Expression Language (CEL).

Every condition expression must evaluate to a boolean true/false value. A condition block in a policy can contain either a single condition expression, or multiple expressions combined using the all, any, or none operators. These logical operators may be nested.

Condition block

condition:
  match:
    all:
      of:
        - expr: request.resource.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in request.resource.attr.geographies

Top-level identifiers

Within a condition expression, you have access to several top-level identifiers:

request

Data provided in the check or plan request (principal, resource, and auxiliary data).

runtime

Additional data computed while evaluating the policy.

variables

Variables declared in the variables section of the policy.

constants

Variables declared in the constants section of the policy.

globals

Global variables declared in the policy engine configuration.

There are also single-letter aliases available to allow you to write terser expressions:

P

request.principal

R

request.resource

V

variables

C

constants

G

globals

The request object

request:
  principal: (1)
    id: alice (2)
    roles: (3)
      - employee
    attr: (4)
      geography: GB

resource: (5)
    kind: leave_request (6)
    id: XX125 (7)
    attr: (8)
      owner: alice

auxData: (9)
    jwt: (10)
      iss: acme.corp

The runtime object

runtime:
  effectiveDerivedRoles: (1)
    - owner
    - gb_employee

Expressions and blocks

Single boolean expression

condition:
  match:
    expr: P.id.matches("^dev_.*")

all operator: all expressions must evaluate to true (logical AND)

condition:
  match:
    all:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"

any operator: only one of the expressions has to evaluate to true (logical OR)

condition:
  match:
    any:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"

none operator: none of the expressions should evaluate to true (logical negation)

condition:
  match:
    none:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"

Nesting operators

condition:
  match:
    all:
      of:
        - expr: R.attr.status == "DRAFT"
        - any:
            of:
              - expr: R.attr.dev == true
              - expr: R.attr.id.matches("^[98][0-9]+")
        - none:
            of:
              - expr: R.attr.qa == true
              - expr: R.attr.canary == true

The above nested block is equivalent to the following:

condition:
  match:
    expr: >
      (R.attr.status == "DRAFT" &&
        (R.attr.dev == true || R.attr.id.matches("^[98][0-9]+")) &&
        !(R.attr.qa == true || R.attr.canary == true))

Quotes in expressions

Single and double quotes have special meanings in YAML. To avoid parsing errors when your expression contains quotes, use the YAML block scalar syntax or wrap the expression in parentheses.

expr: >
  "GB" in R.attr.geographies

expr: ("GB" in R.attr.geographies)

Policy variables

To avoid duplication in condition expressions, you can define variables and constants in policies.

Auxiliary data

If you have auxiliary data sources configured, they can be accessed using request.auxData.

Accessing JWT claims

"cerbie" in request.auxData.jwt.aud && request.auxData.jwt.iss == "cerbos"

Operators

Durations

| | Duration values must be specified in one of the following units. Larger units like days, weeks or years are not supported because of ambiguity around their meaning due to factors such as daylight saving time transitions.

Test data

...
"resource": {
  "kind": "leave_request",
  "attr": {
    "cooldownPeriod": "3750s",
    "lastAccessed": "2021-04-20T10:00:20.021-05:00"
  }
}
...```

| Function | Description | Example |
| --- | --- | --- |
| `duration` | Convert a string to a duration. The string must contain a valid duration suffixed by one of `ns`, `us`, `ms`, `s`, `m` or `h`. E.g. `3750s` | `duration(R.attr.cooldownPeriod).getSeconds() == 3750` |
| `getHours` | Get hours from a duration | `duration(R.attr.cooldownPeriod).getHours() == 1` |
| `getMilliseconds` | Get milliseconds from a duration | `duration(R.attr.cooldownPeriod).getMilliseconds() == 3750000` |
| `getMinutes` | Get minutes from a duration | `duration(R.attr.cooldownPeriod).getMinutes() == 62` |
| `getSeconds` | Get seconds from a duration | `duration(R.attr.cooldownPeriod).getSeconds() == 3750` |
| `timeSince` | Time elapsed since the given timestamp to current time on the server. This is a Cerbos extension to CEL | `timestamp(R.attr.lastAccessed).timeSince() > duration("1h")` |

## Hierarchies

|     |     |
| --- | --- |
|   | The hierarchy functions are Cerbos-specific extensions to CEL. |

Test data

```json
...
"principal": {
  "id": "john",
  "roles": ["employee"],
  "attr": {
    "scope": "foo.bar.baz.qux",
  }
},
"resource": {
  "kind": "leave_request",
  "attr": {
    "scope": "foo.bar",
  }
}
...

IP addresses

Test data

...
"principal": {
  "id": "elmer_fudd",
  "attr": {
    "ipv4Address": "192.168.0.10",
    "ipv6Address": "2001:0db8:0000:0000:0000:0000:1000:0000"
  }
}
...

Lists and maps

Test data

...
"principal": {
  "id": "elmer_fudd",
  "attr": {
    "id": "125",
    "teams": ["design", "communications", "product", "commercial"],
    "clients": {
      "acme": {"active": true},
      "bb inc": {"active": true}
    }
  }
}
...

Math

Strings

Test data

...
"resource": {
  "kind": "leave_request",
  "attr": {
    "id": "125",
    "department": "marketing"
  }
}
...

Timestamps

Test data

...
"resource": {
  "kind": "leave_request",
  "attr": {
    "lastAccessed": "2021-04-20T10:00:20.021-05:00",
    "lastUpdateTime": "2021-05-01T13:34:12.024Z",
  }
}
...

Example: Assert that more than 36 hours has elapsed between last access time and last update time

timestamp(R.attr.lastUpdateTime) - timestamp(R.attr.lastAccessed) > duration("36h")

Example: Add a duration to a timestamp

timestamp(R.attr.lastUpdateTime) + duration("24h") == timestamp("2021-05-02T13:34:12.024Z")