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' diff --git a/content/docs/get-started/fundamentals/core/build-policies.md b/content/docs/get-started/fundamentals/core/build-policies.md index cc5d5e301..25e989f55 100644 --- a/content/docs/get-started/fundamentals/core/build-policies.md +++ b/content/docs/get-started/fundamentals/core/build-policies.md @@ -66,15 +66,39 @@ You can think of it as coded instructions to tell Pomerium how authorization dec ### 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,12 @@ 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 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 @@ -113,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 @@ -191,7 +220,7 @@ policy: allow: and: - domain: - is: example.com + is: example.com ``` Now, access the route. diff --git a/content/docs/get-started/fundamentals/core/build-routes.md b/content/docs/get-started/fundamentals/core/build-routes.md index 93aabc4be..0cb616ea2 100644 --- a/content/docs/get-started/fundamentals/core/build-routes.md +++ b/content/docs/get-started/fundamentals/core/build-routes.md @@ -59,10 +59,10 @@ routes: - email: 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 + # Add Grafana route here: + - 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: diff --git a/content/docs/internals/ppl.mdx b/content/docs/internals/ppl.mdx index 040ec08c1..344e9cf89 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,12 @@ 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 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: 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