From a18e0c42f2fb693c0d599535dffdf4c3944e7eff Mon Sep 17 00:00:00 2001 From: zachary painter <60552605+ZPain8464@users.noreply.github.com> Date: Tue, 9 Apr 2024 14:32:17 -0400 Subject: [PATCH 1/3] adds rego docs --- content/docs/capabilities/authorization.mdx | 106 ++++++++++++++++++-- 1 file changed, 100 insertions(+), 6 deletions(-) diff --git a/content/docs/capabilities/authorization.mdx b/content/docs/capabilities/authorization.mdx index 7890fbf79..1d54fffde 100644 --- a/content/docs/capabilities/authorization.mdx +++ b/content/docs/capabilities/authorization.mdx @@ -126,17 +126,97 @@ Reapply policies as necessary to any route or namespace: ### Rego support -Pomerium Core and Enterprise support policies expressed in [Rego](https://www.openpolicyagent.org/docs/latest/#rego) for organizations that prefer to use [OPA](https://www.openpolicyagent.org/). +Pomerium supports policies expressed in [Rego](https://www.openpolicyagent.org/docs/latest/#rego) for organizations that prefer to use [OPA](https://www.openpolicyagent.org/). -For Enterprise customers, use the **Rego** tab to configure your policy: +See the [Outputs](#outputs), [Inputs](#inputs), and Functions reference sections below to learn how they apply to policy evaluation. -![Apply Rego in Console editor](./img/authorization/ppl-rego-policy.png) +#### Outputs -:::tip +Authorization policy written in Rego is expected to return results in `allow` and/or `deny` rules: -A policy can only support PPL or Rego. Once one is set, the other tab is disabled. +```rego +# a policy that always allows access +allow := true +``` -::: +```rego +# a policy that always denies access +deny := true +``` + +Pomerium grants access according to the same rules as [PPL](/docs/capabilities/ppl#actions): + +> Only two actions are supported: allow and deny. deny takes precedence over allow. More precisely: a user will have access to a route if at least one allow rule matches and no deny rules match. + +`allow` and `deny` rules support four forms: + +1. A simple boolean: + +```rego +allow := true +``` + +2. An array with a single boolean value: + +```rego +deny := [true] +``` + +3. An array with two values: a boolean and a **reason**: + +```rego +allow := [false, "user-unauthorized"] +``` + +4. An array with three values: a boolean, a reason, and additional data: + +```rego +allow := [false, "user-unauthorized", { "key": "value" }] +``` + +The **reason** value is useful for debugging, since it appears in [authorization logs](/docs/reference/authorize-log-fields#find-authorize-logs). There are two special reasons that trigger functionality in Pomerium: + +- `user-unauthenticated` indicates that the user needs to sign in, and results in a redirect to the Authenticate service +- `device-unauthenticated` indicates that the user needs to register a new device + +#### Inputs + +Rego scripts are evaluated with inputs available on the `input` object: + +```rego +allow if input.http.method == "POST" +``` + +Rego defines the following inputs: + +| **Input name** | **Type** | **Description** | +| :--- | :--- | :--- | +| `http` | Object | Represents the HTTP request | +| `http.method` | String | The method used in the HTTP request | +| `http.hostname` | String | The hostname in the HTTP request | +| `http.path` | String | The path in the HTTP request | +| `http.url` | String | The full URL in the HTTP request | +| `http.headers` | Object | The headers in the HTTP request | +| `http.client_certificate` | Object | The client certificate details | +| `http.client_certificate.presented` | Boolean | `true` if the client presented a certificate | +| `http.client_certificate.leaf` | String | The leaf certificated provided by the client (unvalidated) | +| `http.client_certificate.intermediates` | String | The remainder of the client certificate chain | +| `http.ip` | String | The user's IP address | +| `http.session` | Object | Represents the user's session | +| `http.session.id` | String | The session ID | +| `http.is_valid_client_certificate` | Boolean | `true` if the presented client certificate is valid | + +#### Functions + +The function below is available in Rego scripts: + +- `get_databroker_record(record_type, record_id)`: Returns data from the Databroker service. + +For example: + +```rego +session := get_databroker_record("type.googleapis.com/session.Session", input.session.id) +```
Example Rego Policy @@ -192,6 +272,20 @@ This example pulls session data from the Databroker service using `type.googleap
+::::enterprise + +In the [**Enterprise Console**](/docs/deploy/enterprise), you can write policies in Rego with the PPL builder: + +![Apply Rego in Console editor](./img/authorization/ppl-rego-policy.png) + +:::note + +A policy can only support PPL or Rego. Once one is set, the other tab is disabled. + +::: + +:::: + ### Policy overrides Pomerium Core and Enterprise offer the following options for overriding your authorization policy: From 2b15e64a46c5a73035a2e421a7a786469cbaf924 Mon Sep 17 00:00:00 2001 From: zachary painter <60552605+ZPain8464@users.noreply.github.com> Date: Tue, 9 Apr 2024 14:36:21 -0400 Subject: [PATCH 2/3] fixes precommit failures --- content/docs/capabilities/authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/capabilities/authorization.mdx b/content/docs/capabilities/authorization.mdx index 1d54fffde..25c629b6f 100644 --- a/content/docs/capabilities/authorization.mdx +++ b/content/docs/capabilities/authorization.mdx @@ -1,5 +1,5 @@ --- -# cSpell:ignore abac, gset, nxon +# cSpell:ignore abac, gset, nxon, unvalidated title: Authorization & Policy lang: en-US @@ -190,7 +190,7 @@ allow if input.http.method == "POST" Rego defines the following inputs: | **Input name** | **Type** | **Description** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | `http` | Object | Represents the HTTP request | | `http.method` | String | The method used in the HTTP request | | `http.hostname` | String | The hostname in the HTTP request | From ce409bb4da9282cb809aac7674aba0d9f7742100 Mon Sep 17 00:00:00 2001 From: zachary painter <60552605+ZPain8464@users.noreply.github.com> Date: Tue, 9 Apr 2024 14:44:33 -0400 Subject: [PATCH 3/3] Adds anchor link --- content/docs/capabilities/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/capabilities/authorization.mdx b/content/docs/capabilities/authorization.mdx index 25c629b6f..eff831575 100644 --- a/content/docs/capabilities/authorization.mdx +++ b/content/docs/capabilities/authorization.mdx @@ -128,7 +128,7 @@ Reapply policies as necessary to any route or namespace: Pomerium supports policies expressed in [Rego](https://www.openpolicyagent.org/docs/latest/#rego) for organizations that prefer to use [OPA](https://www.openpolicyagent.org/). -See the [Outputs](#outputs), [Inputs](#inputs), and Functions reference sections below to learn how they apply to policy evaluation. +See the [Outputs](#outputs), [Inputs](#inputs), and [Functions](#functions) reference sections below to learn how they apply to policy evaluation. #### Outputs