docs: restructure around concepts, capabilities, releases, internals, and integrations (#170)

Signed-off-by: Bobby DeSimone <[email protected]>
Signed-off-by: Bobby DeSimone <[email protected]>
Co-authored-by: zachary painter <[email protected]>

Author: desimone

.github/ISSUE_TEMPLATE/doc-error.md

@@ -14,4 +14,4 @@ Page: https://www.pomerium.com/docs/${page}
 
 ## What's the resolution?
 
-<!-- If you don't know the correct information, that's fine. Just knowing we need to fix something is usually enough. -->
+<!-- If you don't know the correct information, that's fine. Just knowing we need to fix something is usually enough. -->

.github/workflows/backport.yaml

@@ -0,0 +1,27 @@
+name: Backport
+permissions:
+  contents: read
+on:
+  pull_request_target:
+    types:
+      - closed
+      - labeled
+
+jobs:
+  backport:
+    runs-on: ubuntu-latest
+    name: Backport
+    steps:
+      - name: Generate token
+        id: generate_token
+        uses: tibdex/github-app-token@f717b5ecd4534d3c4df4ce9b5c1c2214f0f7cd06
+        with:
+          app_id: ${{ secrets.BACKPORT_APP_APPID }}
+          private_key: ${{ secrets.BACKPORT_APP_PRIVATE_KEY }}
+
+      - name: Backport
+        uses: pomerium/backport@e2ffd4c5a70730dfd19046859dfaf366e3de6466
+        with:
+          github_token: ${{ steps.generate_token.outputs.token }}
+          title_template: '{{originalTitle}}'
+          copy_original_labels: true

.github/workflows/pre-commit.yml

@@ -0,0 +1,15 @@
+name: pre-commit
+
+on:
+  pull_request:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b
+        with:
+          fetch-depth: 0
+      - uses: pre-commit/action@646c83fcd040023954eafda54b4db0192ce70507
+        with:
+          extra_args: --show-diff-on-failure --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }}

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v2.4.1
+    hooks:
+      - id: prettier
+        additional_dependencies:
+          - '[email protected]'
+        files: ^content\/.*$

LICENSE.md

@@ -4,14 +4,16 @@ In the event that you lose access to the console via delegated access (the polic
 
 To generate a token, run the `pomerium-console generate-recovery token` command with the following flags:
 
-| Flag                        | Description |
-| --------------------------- | ----------- |
+| Flag | Description |
+| --- | --- |
 | `--database-encryption-key` | base64-encoded encryption key for encrypting sensitive data in the database. |
-| `--database-url`            | The database to connect to (default "`postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable`"). |
-| `--namespace`               | The namespace to use (default "`9d8dbd2c-8cce-4e66-9c1f-c490b4a07243`" for Global). |
-| `--out`                     | Where to save the JWT. If not specified, it will be printed to stdout. |
-| `--ttl`                     | The amount of time before the recovery token expires. Requires a unit (example: `30s`, `5m`).|
+| `--database-url` | The database to connect to (default "`postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable`"). |
+| `--namespace` | The namespace to use (default "`9d8dbd2c-8cce-4e66-9c1f-c490b4a07243`" for Global). |
+| `--out` | Where to save the JWT. If not specified, it will be printed to stdout. |
+| `--ttl` | The amount of time before the recovery token expires. Requires a unit (example: `30s`, `5m`). |
 
 :::tip
+
 You can run the `pomerium-console` binary from any device with access to the database.
+
 :::

content/_generate-recovery-token.md

@@ -11,4 +11,4 @@ rootCA-key.pem  rootCA.pem
 
 The output of `mkcert -install` may vary depending on your operating system.
 
-[installing mkcert]: https://github.com/FiloSottile/mkcert#installation
+[installing mkcert]: https://github.com/FiloSottile/mkcert#installation

content/_install-mkcert.md

@@ -1,15 +1,18 @@
 ---
-title: Authorization Logs
+title: Audit Logs
 description: Learn how to read Pomerium authorization logs.
-pagination_prev: null
 lang: en-US
+sidebar_label: Audit logs
 keywords: [pomerium, troubleshooting, auth, authorization, logs]
+sidebar_class_name: enterprise
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Pomerium provides verbose logging to help users manage and troubleshoot their configurations. The amount of logs output can be overwhelming, so on this page we'll cover how to sort for and understand logs from the authorization service. These logs often provide the most helpful information when first configuring Pomerium.
+# Audit logs
+
+Pomerium provides verbose logging to help users audit, manage, and troubleshoot their configurations. The amount of logs output can be overwhelming, so on this page we'll cover how to sort for and understand logs from the authorization service. These logs often provide the most helpful information when first configuring Pomerium.
 
 ## Find Logs
 
@@ -106,16 +109,16 @@ kubectl logs -f deploy/pomerium-authorize | grep '"service":"authorize"' | jq
 
 The keys described below usually contain the relevant information when debugging an authorization issue:
 
-| Key                                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a className="entRef-anchor" id="allow">#</a><a href='#allow'>`allow`</a>                                                             | If true, at least one allow rule passed. As long as `deny` is false, the request will be allowed.                                                                                                                                                                                                                                                  |
-| <a className="entRef-anchor" id="allow-why-false">#</a><a href='#allow-why-false'>`allow-why-false` & `allow-why-true`</a>            | The short reason strings why access was allowed (or not allowed). <br/> <br/> In the example output above, `claim-unauthorized` means that there was a policy rule on a claim that didn't pass.<br/><br/>`non-pomerium-route` means that it was not a request to `/.pomerium/`, which is  allowed for any authenticated user.                      |
-| <a className="entRef-anchor" id="deny">#</a><a href='#deny'>`deny`</a>                                                                | If true it means that at least one deny rule passed, and the request will be denied.                                                                                                                                                                                                                                                               |
-| <a className="entRef-anchor" id="deny-why-false">#</a><a href='#deny-why-false'>`deny-why-false` & `deny-why-true`</a>                | The short reason strings why access was denied (or not denied). <br/><br/>In the example above, `valid-client-certificate-or-none-required` means that either a valid client certificate was provided, or the policy didn't require one. By default pomerium policies have this PPL rule added to them. It's how we implement client certificates. |
-| <a className="entRef-anchor" id="databroker">#</a><a href='#databroker'>`databroker_server_version` & `databroker_record_version`</a> | These values are used for auditing. With these version numbers and a complete history of all changes in the databroker, you can determine what data was used for policy evaluation.                                                                                                                                                                |
+| Key | Description |
+| --- | --- |
+| <a className="entRef-anchor" id="allow">#</a><a href='#allow'>`allow`</a> | If true, at least one allow rule passed. As long as `deny` is false, the request will be allowed. |
+| <a className="entRef-anchor" id="allow-why-false">#</a><a href='#allow-why-false'>`allow-why-false` & `allow-why-true`</a> | The short reason strings why access was allowed (or not allowed). <br/> <br/> In the example output above, `claim-unauthorized` means that there was a policy rule on a claim that didn't pass.<br/><br/>`non-pomerium-route` means that it was not a request to `/.pomerium/`, which is allowed for any authenticated user. |
+| <a className="entRef-anchor" id="deny">#</a><a href='#deny'>`deny`</a> | If true it means that at least one deny rule passed, and the request will be denied. |
+| <a className="entRef-anchor" id="deny-why-false">#</a><a href='#deny-why-false'>`deny-why-false` & `deny-why-true`</a> | The short reason strings why access was denied (or not denied). <br/><br/>In the example above, `valid-client-certificate-or-none-required` means that either a valid client certificate was provided, or the policy didn't require one. By default pomerium policies have this PPL rule added to them. It's how we implement client certificates. |
+| <a className="entRef-anchor" id="databroker">#</a><a href='#databroker'>`databroker_server_version` & `databroker_record_version`</a> | These values are used for auditing. With these version numbers and a complete history of all changes in the databroker, you can determine what data was used for policy evaluation. |
 
 ## Understanding Authorization Logs
 
 The most confusing keys for new users to understand are likely `allow-why-false` and `deny-why-false`. To better understand them, we should first discuss how Pomerium Policy Language (**PPL**) works.
 
-PPL allows a request to a route if the claim matches at least one **allow** policy rule, and matches zero **deny** policy rules. With that in mind, `allow-why-false` and `allow-why-true` will describe a situation where the request either does or not not meet the requirements of an **allow** block a policy applied to that route. Conversely, `deny-why-true` and `deny-why-false` will describe why a request did or did not match a **deny** block for a policy assigned to the route.
+PPL allows a request to a route if the claim matches at least one **allow** policy rule, and matches zero **deny** policy rules. With that in mind, `allow-why-false` and `allow-why-true` will describe a situation where the request either does or not not meet the requirements of an **allow** block a policy applied to that route. Conversely, `deny-why-true` and `deny-why-false` will describe why a request did or did not match a **deny** block for a policy assigned to the route.

content/docs/topics/auth-logs.md content/docs/capabilities/audit-logs.mdx

@@ -0,0 +1,12 @@
+---
+sidebar_label: Authentication
+description: This article describes how Pomerium provides a single source of authentication and identity to all services it manages.
+---
+
+# Authentication / SSO
+
+While Pomerium itself is not an identity provider, Pomerium does integrate with your existing single-sign-on Identity Provider (**IdP**) of choice. Pomerium uses your IdP to add authentication, single-sign-on, and identity context to all upstream applications even if the app itself doesn't directly support single-sign-on, which is great for legacy apps.
+
+Pomerium supports any identity provider that uses the open standard [OpenID Connect][openid connect] (**OIDC**). In addition to (OIDC), Pomerium supports most well known identity providers specifically, and Pomerium Enterprise users are able to leverage full directory sync for even more context around things like roles, groups, and whatever other relevant user identity context which exists in your directory.
+
+[openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect

content/docs/capabilities/authentication.mdx

@@ -0,0 +1,174 @@
+---
+title: Authorization & Policy
+lang: en-US
+sidebar_label: Authorization
+description: How to get Pomerium's CLI which be used to proxy TCP services and kubernetes commands
+keywords:
+  [
+    pomerium,
+    context-aware proxy,
+    authorization proxy,
+    access decision point,
+    rbac,
+    abac,
+    dynamic access,
+  ]
+---
+
+# Authorization
+
+## Policy
+
+A [Policy](/docs/capabilities/authorization.mdx) defines what permissions a set of users or groups has. Policies are applied to Namespaces or Routes to associate the set of permissions with a service or set of service, completing the authentication model.
+
+Policies can be constructed three ways:
+
+### Web UI
+
+From the **BUILDER** tab, users can add allow or deny blocks to a policy, containing and/or/not/nor logic to allow or deny sets of users and groups.
+
+![A policy being constructed in Pomerium Enterprise allowing a single user access](./img/authorization/example-policy-single-user.png)
+
+Policies can be constructed three ways:
+
+### Pomerium Policy Language
+
+From the **EDITOR** tab users can write policies in Pomerium Policy Language (**PPL**), a YAML-based notation.
+
+![A policy as viewed from the editor tab](./img/authorization/example-policy-editor.png)
+
+PPL documents contain one or more rules. Each rule has a corresponding action and one or more logical operators. Each logical operator contains criteria and each criterion has a name and corresponding data.
+
+PPL documents are defined via YAML:
+
+```yaml
+- allow:
+    or:
+      - email:
+          is: [email protected]
+      - email:
+          is: [email protected]
+```
+
+The available rule actions are:
+
+- `allow`
+- `deny`
+
+The available logical operators are:
+
+- `and`
+- `or`
+- `not`
+- `nor`
+
+The available criteria types are:
+
+- `accept`
+- `authenticated_user`
+- `claim`
+- `date`
+- `day_of_week`
+- `domain`
+- `email`
+- `groups`
+- `http_method`
+- `http_path`
+- `record`
+- `reject`
+- `time_of_day`
+- `user`
+
+Some criteria also support a sub-path as part of the criterion name:
+
+```yaml
+- allow:
+    or:
+      - claim/family_name: Smith
+```
+
+See [Pomerium Policy Language](/docs/capabilities/ppl) for more details.
+
+### Rego
+
+For those using [OPA](https://www.openpolicyagent.org/), the **REGO** tab will accept policies written in Rego.
+
+:::tip
+
+A policy can only support PPL or Rego. Once one is set, the other tab is disabled.
+
+:::
+
+<details>
+<summary>Example Rego Policy</summary>
+<div>
+
+This example policy compares the `given_name` claim from a user's session against a list of popular first names, and only allows the 100 most popular first names.
+
+```rego
+package pomerium.policy
+session = s {
+  s = gset_databroker_record("type.googleapis.com/user.ServiceAccount", input.session.id)
+  s != null
+} else = s {
+  s = get_databroker_record("type.googleapis.com/session.Session", input.session.id)
+  s != null
+} else = {} {
+  true
+}
+user = u {
+  u = get_databroker_record("type.googleapis.com/user.User", session.user_id)
+} else = {} {
+  true
+}
+allow = [true, {"custom-rego-authorized"}] {
+  # grab all the claims from the user and session objects
+  session_claims := object.get(session, "claims", {})
+  user_claims := object.get(user, "claims", {})
+  all_claims := object.union(session_claims, user_claims)
+  # get the given_name claim. claim values are always an array of strings
+  given_names := object.get(all_claims, "given_name", [])
+  # query a JSON dump of the most popular baby names from 2020
+  response := http.send({
+    "method": "GET",
+    "url": "https://raw.githubusercontent.com/aruljohn/popular-baby-names/master/2020/boy_names_2020.json",
+    "force_json_decode": true,
+  })
+  # only include the top 100 names
+  all_names := response.body.names
+  popular_names := array.slice(all_names, 0, 99)
+  # check that there's a given name in the popular names
+  some i
+  some j
+  popular_names[i] == given_names[j]
+} else = [false, {"custom-rego-unauthorized"}] {
+  session.id != ""
+} else = [false, {"user-unauthenticated"}] {
+  true
+}
+```
+
+This example pulls session data from the Databroker service using `type.googleapis.com/session.Session` for users and `type.googleapis.com/user.ServiceAccount` for service accounts.
+
+</div>
+</details>
+
+### Overrides
+
+- **Any Authenticated User**: This setting will allow access to a route with this policy attached to any user who can authenticate to your Identity Provider (**IdP**).
+- **CORS Preflight**: Allow unauthenticated HTTP OPTIONS requests as per the CORS spec.
+- **Public Access**: This setting allows complete, unrestricted access to an associated route. Use this setting with caution.
+
+## Devices
+
+Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
+
+### Manage Devices
+
+<ManageDevices />
+
+### Devices List
+
+Displays the currently enrolled devices for each user, along with their current approval status. Administrators can inspect, approve, or delete registered devices from this table.
+
+![List of user devices](./img/authorization/console-devices.png)