Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Add page with output example (#1622)
Update the API response to include outputs and introduce a new page with an example of how to use outputs. Signed-off-by: Charith Ellawala <charith@cerbos.dev>
- Loading branch information
Showing
3 changed files
with
99 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| include::ROOT:partial$attributes.adoc[] | ||
|
|
||
| = Outputs | ||
|
|
||
| You can define an optional expression to be evaluated when a policy rule is activated. The collected outputs from all the activated rules are included in the Cerbos API response. | ||
|
|
||
| Output expressions are useful if you want to take specific actions in your application based on the triggered rules. For example, if your policy contains a rule that denies access if the request is issued outside working hours, it could output a string that explains the restriction. Your application could then display that back to the user so that they know the specific reason why the request was denied. | ||
|
|
||
|
|
||
| Consider the following policy definition: | ||
|
|
||
| [source,yaml,linenums] | ||
| ---- | ||
| --- | ||
| apiVersion: api.cerbos.dev/v1 | ||
| resourcePolicy: | ||
| version: "default" | ||
| resource: "system_access" | ||
| rules: | ||
| - name: working-hours-only | ||
| actions: ['*'] | ||
| effect: EFFECT_DENY | ||
| roles: ['*'] | ||
| condition: | ||
| match: | ||
| expr: now().getHours() > 18 || now().getHours() < 8 | ||
| output: | ||
| expr: |- | ||
| {"principal": P.id, "resource": R.id, "timestamp": now(), "message": "System can only be accessed between 0800 and 1800"} | ||
| ---- | ||
|
|
||
| If a request is made outside working hours, the response from Cerbos would resemble the following: | ||
|
|
||
| [source,json,linenums] | ||
| ---- | ||
| { | ||
| "requestId": "xx-010023-23459", | ||
| "results": [ | ||
| { | ||
| "resource": { | ||
| "id": "bastion_002", | ||
| "kind": "system_access" | ||
| }, | ||
| "actions": { | ||
| "login": "EFFECT_DENY" | ||
| }, | ||
| "meta": { | ||
| "actions": { | ||
| "login": { | ||
| "matchedPolicy": "resource.system_access.vdefault" | ||
| } | ||
| } | ||
| }, | ||
| "outputs": [ | ||
| { | ||
| "src": "resource.system_access.vdefault#working-hours-only", | ||
| "val": { | ||
| "message": "System can only be accessed between 0800 and 1800", | ||
| "principal": "john", | ||
| "resource": "bastion_002", | ||
| "timestamp": "2023-06-02T21:53:58.319506543+01:00" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ---- | ||
|
|
||
| Output expressions can be any valid CEL expression. You can return simple values such as strings, numbers and booleans or complex values such as maps and lists. | ||
|
|
||
| CAUTION: Excessive use of output expressions could affect policy evaluation performance. If you use them for debugging purposes, remember to remove them before going to production. |