From adeb9de0a529dd59304c1ab8388e04dc7754bfab Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 11:15:42 -0400 Subject: [PATCH 1/7] fix invalid docker-compose yaml in fundamentals/core/build-routes --- content/docs/get-started/fundamentals/core/build-routes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/get-started/fundamentals/core/build-routes.md b/content/docs/get-started/fundamentals/core/build-routes.md index 93aabc4be..a2f63e449 100644 --- a/content/docs/get-started/fundamentals/core/build-routes.md +++ b/content/docs/get-started/fundamentals/core/build-routes.md @@ -60,9 +60,9 @@ routes: is: user@example.com pass_identity_headers: true # Add Grafana route here: - - from: https://grafana.localhost.pomerium.io - to: http://grafana:3000 - allow_any_authenticated_user: true + - from: https://grafana.localhost.pomerium.io + to: http://grafana:3000 + allow_any_authenticated_user: true ``` In your `docker-compose.yaml` file, add Grafana as a service: From bea6f8334acc7a659e300522407fdd41fb3be444 Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 11:36:28 -0400 Subject: [PATCH 2/7] rework confusing build policy section --- .../fundamentals/core/build-policies.md | 34 ++++++++++++++++--- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/content/docs/get-started/fundamentals/core/build-policies.md b/content/docs/get-started/fundamentals/core/build-policies.md index cc5d5e301..0dea142b4 100644 --- a/content/docs/get-started/fundamentals/core/build-policies.md +++ b/content/docs/get-started/fundamentals/core/build-policies.md @@ -64,17 +64,41 @@ PPL allows administrators to express authorization policy in a high-level, decla You can think of it as coded instructions to tell Pomerium how authorization decisions are made for capturing all niche and edge-case scenarios. It's as flexible as you want it to be! + + ### How does PPL work? -PPL consists of **Rules**, **Actions**, **Logical Operators**, **Criteria**, and **Matchers**. +PPL is made up of **Rules**, **Actions**, **Logical Operators**, **Criteria**, and **Matchers**. + +Below is a simple policy example in PPL format that allows access for the email example@domain.com. The following sections will break down each of these components in more detail. + +```yaml +# PPL Example +policy: + # ────────── Rule ────────── + allow: # Action (at least one must match) + and: # Logical Operator + - email: # Criterion + is: example@domain.com # Matcher +``` #### Rules -A PPL document is either an object or an array of objects. The object represents a rule where the action is the key and the value is an object containing the logical operators. +A rule is the basic building block of a PPL policy. Each rule says what action to take (allow or deny) and under what conditions. + +- The action (allow or deny) is the outcome if the conditions are met. +- The conditions are expressed using logical operators, criteria, and matchers. + +A PPL document can contain: +- A single rule, or +- An array of rules (evaluated together). #### 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. +Actions are one of the two values : `allow` or `deny`. `deny` always takes precedence over `allow`. + +Users will have access to a route if **at least one** `allow` rule matches and **no** `deny` rules match. + #### Logical Operators @@ -89,7 +113,9 @@ There are four logical operators: #### Criteria -Criteria in PPL are represented as an object where the key is the name and optional sub-path of the criterion, and the value changes depending on which criterion is used. +In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. + - Each criterion is an object where the key is the criterion name (optionally with a sub-path), and the value specifies what to match or compare. +- The exact format of the value depends on the type of criterion being used. #### Matchers From 1340516818dcbe5184e8a35e66a08f827b9f8b6f Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 12:22:19 -0400 Subject: [PATCH 3/7] add redirect for outdated data-storage-link --- static/_redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/static/_redirects b/static/_redirects index e1336bff6..9d78aea86 100644 --- a/static/_redirects +++ b/static/_redirects @@ -319,6 +319,7 @@ https://docs.pomerium.io/* https://docs.pomerium.com/:splat 301! /docs/topics/ppl /docs/internals/ppl /docs/topics/production-deployment.html /docs/deploy/upgrading /docs/topics/programmatic-access.html /docs/internals/programmatic-access +/docs/topics/data-storage.html /docs/internals/data-storage /docs/zero/billing /docs/deploy/cloud/billing /docs/zero/billing /docs/deploy/cloud/billing /docs/zero/import /docs/deploy/cloud/import From e2b14bdc23ccfee3e2acf4de3a8f3443d486418d Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 12:27:14 -0400 Subject: [PATCH 4/7] fix: native ssh 'ssh_user_ca_key_file' config.yaml --- content/docs/capabilities/native-ssh-access.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/docs/capabilities/native-ssh-access.mdx b/content/docs/capabilities/native-ssh-access.mdx index f4ce1fbd8..05f840aa3 100644 --- a/content/docs/capabilities/native-ssh-access.mdx +++ b/content/docs/capabilities/native-ssh-access.mdx @@ -131,8 +131,7 @@ Add SSH configuration to your `config.yaml`: ```yaml title="config.yaml" ssh_address: 0.0.0.0:22 # if port 22 is already in use by sshd, choose a different port -ssh_user_ca_key_file: - - '/path/to/pomerium_user_ca_key' +ssh_user_ca_key_file: '/path/to/pomerium_user_ca_key' ssh_host_key_files: - '/path/to/pomerium_ssh_host_ed25519_key' - '/path/to/pomerium_ssh_host_rsa_key' From df05f84ae6dc9b6c137257340532420fd217581b Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 13:36:52 -0400 Subject: [PATCH 5/7] run lint --- .../docs/get-started/fundamentals/core/build-policies.md | 9 +++++---- .../docs/get-started/fundamentals/core/build-routes.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/content/docs/get-started/fundamentals/core/build-policies.md b/content/docs/get-started/fundamentals/core/build-policies.md index 0dea142b4..02f2acd7b 100644 --- a/content/docs/get-started/fundamentals/core/build-policies.md +++ b/content/docs/get-started/fundamentals/core/build-policies.md @@ -64,14 +64,13 @@ PPL allows administrators to express authorization policy in a high-level, decla You can think of it as coded instructions to tell Pomerium how authorization decisions are made for capturing all niche and edge-case scenarios. It's as flexible as you want it to be! - - ### How does PPL work? PPL is made up of **Rules**, **Actions**, **Logical Operators**, **Criteria**, and **Matchers**. Below is a simple policy example in PPL format that allows access for the email example@domain.com. The following sections will break down each of these components in more detail. + ```yaml # PPL Example policy: @@ -81,6 +80,7 @@ policy: - email: # Criterion is: example@domain.com # Matcher ``` + #### Rules @@ -90,6 +90,7 @@ A rule is the basic building block of a PPL policy. Each rule says what action t - The conditions are expressed using logical operators, criteria, and matchers. A PPL document can contain: + - A single rule, or - An array of rules (evaluated together). @@ -99,7 +100,6 @@ Actions are one of the two values : `allow` or `deny`. `deny` always takes prece Users will have access to a route if **at least one** `allow` rule matches and **no** `deny` rules match. - #### Logical Operators A logical operator combines multiple criteria together for the evaluation of a rule. @@ -114,7 +114,8 @@ There are four logical operators: #### Criteria In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. - - Each criterion is an object where the key is the criterion name (optionally with a sub-path), and the value specifies what to match or compare. + +- Each criterion is an object where the key is the criterion name (optionally with a sub-path), and the value specifies what to match or compare. - The exact format of the value depends on the type of criterion being used. #### Matchers diff --git a/content/docs/get-started/fundamentals/core/build-routes.md b/content/docs/get-started/fundamentals/core/build-routes.md index a2f63e449..0cb616ea2 100644 --- a/content/docs/get-started/fundamentals/core/build-routes.md +++ b/content/docs/get-started/fundamentals/core/build-routes.md @@ -59,7 +59,7 @@ routes: - email: is: user@example.com pass_identity_headers: true -# Add Grafana route here: + # Add Grafana route here: - from: https://grafana.localhost.pomerium.io to: http://grafana:3000 allow_any_authenticated_user: true From a11064adcc3da26778e08cc4c19121d5045e3520 Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Wed, 24 Sep 2025 14:07:32 -0400 Subject: [PATCH 6/7] update other PPL page --- .../fundamentals/core/build-policies.md | 2 +- content/docs/internals/ppl.mdx | 19 ++++++++++++++++--- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/content/docs/get-started/fundamentals/core/build-policies.md b/content/docs/get-started/fundamentals/core/build-policies.md index 02f2acd7b..bc84db1db 100644 --- a/content/docs/get-started/fundamentals/core/build-policies.md +++ b/content/docs/get-started/fundamentals/core/build-policies.md @@ -115,7 +115,7 @@ There are four logical operators: In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. -- Each criterion is an object where the key is the criterion name (optionally with a sub-path), and the value specifies what to match or compare. +- Each criterion is an object where the key is the criterion name (optionally with a sub-path, delimited by `/`), and the value specifies what to match or compare. - The exact format of the value depends on the type of criterion being used. #### Matchers diff --git a/content/docs/internals/ppl.mdx b/content/docs/internals/ppl.mdx index 040ec08c1..d91db9caf 100644 --- a/content/docs/internals/ppl.mdx +++ b/content/docs/internals/ppl.mdx @@ -53,11 +53,21 @@ It will deny access to users with a `user2@example.com` **or** `user3@example.co ## Rules -A PPL document is either an object or an array of objects. The object represents a rule where the action is the key and the value is an object containing the logical operators. +A rule is the basic building block of a PPL policy. Each rule says what action to take (allow or deny) and under what conditions. + +- The action (allow or deny) is the outcome if the conditions are met. +- The conditions are expressed using logical operators, criteria, and matchers. + +A PPL document can contain: + +- A single rule, or +- An array of rules (evaluated together). ## 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. +Actions are one of the two values : `allow` or `deny`. `deny` always takes precedence over `allow`. + +Users will have access to a route if **at least one** `allow` rule matches and **no** `deny` rules match. ## Logical Operators @@ -123,7 +133,10 @@ Although these policies are equally effective, we recommend using just one opera ## Criteria -Criteria in PPL are represented as an object where the key is the name and optional sub-path of the criterion, and the value changes depending on which criterion is used. A sub-path is indicated with a `/` in the name: +In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. + +- Each criterion is an object where the key is the criterion name (optionally with a sub-path, delimited by `/`), and the value specifies what to match or compare. +- The exact format of the value depends on the type of criterion being used. ```yaml allow: From 6be08b19a34823a28906a2d66cd83ec923e28200 Mon Sep 17 00:00:00 2001 From: Alexandre Lamarre Date: Thu, 9 Oct 2025 12:34:32 -0400 Subject: [PATCH 7/7] update criterion definition & fix example policy --- .../fundamentals/core/build-policies.md | 18 ++++++++++-------- content/docs/internals/ppl.mdx | 6 ++++-- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/content/docs/get-started/fundamentals/core/build-policies.md b/content/docs/get-started/fundamentals/core/build-policies.md index bc84db1db..25e989f55 100644 --- a/content/docs/get-started/fundamentals/core/build-policies.md +++ b/content/docs/get-started/fundamentals/core/build-policies.md @@ -115,8 +115,10 @@ There are four logical operators: In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. -- Each criterion is an object where the key is the criterion name (optionally with a sub-path, delimited by `/`), and the value specifies what to match or compare. -- The exact format of the value depends on the type of criterion being used. +- Each criterion is represented by an object with a single key/value pair, where the key is the criterion type. +- For some criteria the key accepts a sub-path, delimited by /. For example: claim/family_name. +- The format of the criterion value varies depending on the criterion type. +- Some criteria do not use their value. For example: `accept`, `reject`, and `authenticated_user`. In this case, the value can be anything. #### Matchers @@ -140,11 +142,11 @@ Now that you've briefly covered PPL, let's jump into some simple examples: This example instructs Pomerium to only grant a user access if their email address is `example@domain.com`. ```yaml title="PPL rule" -policy: # Policy object starts here - allow: # At least one action - and: # Logical operator - - email: # Criterion - is: example@domain.com # Value +policy: + allow: + and: + - email: + is: example@domain.com ``` **Example 2**: Allow access based on the domain criterion @@ -218,7 +220,7 @@ policy: allow: and: - domain: - is: example.com + is: example.com ``` Now, access the route. diff --git a/content/docs/internals/ppl.mdx b/content/docs/internals/ppl.mdx index d91db9caf..344e9cf89 100644 --- a/content/docs/internals/ppl.mdx +++ b/content/docs/internals/ppl.mdx @@ -135,8 +135,10 @@ Although these policies are equally effective, we recommend using just one opera In PPL, a criterion defines a specific condition to evaluate, such as a user’s email or device type. -- Each criterion is an object where the key is the criterion name (optionally with a sub-path, delimited by `/`), and the value specifies what to match or compare. -- The exact format of the value depends on the type of criterion being used. +- Each criterion is represented by an object with a single key/value pair, where the key is the criterion type. +- For some criteria the key accepts a sub-path, delimited by /. For example: claim/family_name. +- The format of the criterion value varies depending on the criterion type. +- Some criteria do not use their value. For example: `accept`, `reject`, and `authenticated_user`. In this case, the value can be anything. ```yaml allow: