Merge branch 'main' into kenjenkins/cli-client-certs

Author: kenjenkins

content/docs/admonitions/_handle-self-signed-certificate-warning.mdx

@@ -1 +1 @@
-If you notice a self-signed certificate warning, see [Handle Self-Signed Certificate Warning](/docs/internals/troubleshooting#handle-self-signed-certificate-warning) to bypass it.
+If you notice a self-signed certificate warning, see [Handle Self-Signed Certificate Warning](/docs/troubleshooting#handle-self-signed-certificate-warning) to bypass it.

content/docs/capabilities/authentication.mdx

@@ -54,6 +54,10 @@ By configuring your applications to route requests to Pomerium’s Proxy service
 
 ## External data sources (Enterprise)
 
+:::enterprise
+
 [Enterprise customers](https://www.pomerium.com/enterprise-sales/) can enforce context-aware access with Pomerium’s [external data sources](/docs/integrations) feature (directory sync).
 
+:::
+
 From the Enterprise Console, you can import external data from sources other than your IdP. User identity context such as users, groups, roles, language, time zones, location, and more can be included into your authorization policy so you can make granular access control decisions.

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
@@ -34,9 +34,13 @@ You can apply policies in Pomerium to [Namespaces](/docs/capabilities/namespacin
 
 ### Namespaces
 
-Administrators can create a namespace, add users, groups, and routes to it, and configure a policy that applies to that specific namespace.
+:::enterprise
+
+Namespace support is available only for [Enterprise customers](https://www.pomerium.com/enterprise-sales/).
 
-Namespace support is only available for [Enterprise customers](https://www.pomerium.com/enterprise-sales/).
+:::
+
+Administrators can create a namespace, add users, groups, and routes to it, and configure a policy that applies to that specific namespace.
 
 ### Routes
 
@@ -102,7 +106,11 @@ In this example, Pomerium will grant a user access if their email address ends i
 
 ### Enterprise Console GUI
 
-The Enterprise Console provides a policy builder GUI so you can build policies and reapply them to multiple routes and namespaces.
+:::enterprise
+
+The Enterprise Console provides a policy builder GUI so you can build policies and reapply them to multiple routes and namespaces. See our [**Enterprise**](/docs/deploy/enterprise) page to learn more.
+
+:::
 
 Use the **BUILDER** tab to build your policy:
 
@@ -118,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](#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)
+```
 
 <details>
 <summary>Example Rego Policy</summary>
@@ -184,6 +272,20 @@ This example pulls session data from the Databroker service using `type.googleap
 </div>
 </details>
 
+::::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:
@@ -192,14 +294,31 @@ Pomerium Core and Enterprise offer the following options for overriding your aut
 - **CORS Preflight**: Allows unauthenticated HTTP OPTIONS requests as per the CORS spec
 - **Public Access**: Allows complete, unrestricted access to an associated route (use this setting with caution)
 
+:::note robots.txt behavior
+
+By default, Pomerium serves a **robots.txt** response directly, instructing search engines _not_ to crawl the route domain:
+
+```txt
+User-agent: *
+Disallow: /
+```
+
+For routes with policies that allow public, unauthenticated access, Pomerium _will not_ serve **robots.txt** directly. Instead, Pomerium will proxy requests for `/robots.txt` to the upstream service.
+
+:::
+
 ## Manage devices
 
+:::enterprise
+
+[Device identity](/docs/capabilities/device-identity) is an Enterprise feature. Check out our [Enterprise](/docs/deploy/enterprise) page to learn more.
+
+:::
+
 The **Manage Devices** feature in the Enterprise Console allows you to enroll and manage user devices for policy-based authorization.
 
 ![Enroll devices](./img/authorization/enroll-device.png)
 
 The **Devices List** displays enrolled devices for each user and the approval status. Administrators can inspect, approve, or delete registered devices from this table.
 
 ![List of user devices](./img/authorization/console-devices.png)
-
-See [Device Identity](docs/capabilities/device-identity) for more information.

content/docs/capabilities/branding.md

@@ -5,7 +5,7 @@ description: Add custom colors, logos, and error messages.
 
 # Custom Branding / White Labeling
 
-:::tip
+:::enterprise
 
 This article describes a use case available to [Pomerium Enterprise](/docs/deploy/enterprise/install) customers.
 

content/docs/capabilities/custom-domains.mdx

@@ -0,0 +1,85 @@
+---
+# cSpell:ignore mycorp
+id: custom-domains
+title: Custom Domains
+sidebar_label: Custom Domains
+description: The Custom Domains page teaches you how to add your own domain in Pomerium Zero and how to use it to build routes to your services.
+---
+
+# Custom Domains in Pomerium Zero
+
+<iframe
+  width="100%"
+  height="500"
+  src="https://www.youtube.com/embed/qj1D5Rgziz0?si=hXM8itfRJ_2lXztP"
+  title="YouTube video player"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  referrerpolicy="strict-origin-when-cross-origin"
+  allowfullscreen></iframe>
+
+This document describes **Custom Domains** in Pomerium Zero.
+
+## Overview
+
+When you deploy a cluster in Pomerium Zero, we provision a randomly generated starter subdomain under `pomerium.app` that's assigned to that cluster (for example, `unique-jellyfish-3578.pomerium.app`).
+
+Each starter subdomain comes with its own DNS records and TLS certificates, which makes it easier for new users to quickly build and test routes and policies in Pomerium Zero.
+
+After testing Pomerium Zero with your starter domain, you may want to add a custom domain for use by your cluster's routes to secure your apps and services.
+
+:::info
+
+See the Clusters Concepts page for more information about clusters in Pomerium Zero.
+
+:::
+
+## Custom Domains
+
+In Pomerium Zero, a **Custom Domain** is a wildcard subdomain you can use to build routes in Pomerium. After adding the appropriate record to your DNS provider, Pomerium will automatically provision and renew a TLS certificate for this subdomain.
+
+For example, if you added a custom domain like `mycorp.example.com` to Pomerium Zero, you could build routes like:
+
+- `verify.mycorp.example.com`
+- `internal-tool.mycorp.example.com`
+- `authenticate.mycorp.example.com`
+
+## How to add a custom domain
+
+Add a **wildcard CNAME record** that points to your starter domain. For example:
+
+```bash
+*.mycorp.example.com CNAME unique-jellyfish-3578.pomerium.app
+```
+
+If you're using a DNS provider like Google's Cloud DNS, you can add the wildcard CNAME record without code:
+
+![Add a CNAME record in GCP](../capabilities/img/custom-domains/gcp-cname-record.png)
+
+Add the custom domain in the Zero Console:
+
+1. Select **Settings**
+1. In the **Editing Clusters Settings** dashboard, select **Domains**
+1. In the **Custom Domains** field, select the **+** icon to add a domain name
+1. Enter your custom domain
+
+![Entering the fully qualified domain name in the Zero Console](../capabilities/img/custom-domains/add-custom-domain.gif)
+
+If added successfully, you will be able to build routes with your custom domain instead of the starter domain. Pomerium will automatically issue and renew X.509 certificates for this custom domain, which you can verify by the Common Name found in the certificate:
+
+![Reviewing the Let's Encrypt certificate for a custom domain](../capabilities/img/custom-domains/custom-domain-certificates.png)
+
+You can also review the certificate in the **Certificates** dashboard:
+
+![Review certificate details in the Certificate dashboard in the Zero Console](../capabilities/img/custom-domains/certificate-details.gif)
+
+### How custom domains work
+
+In order for Pomerium to provision certificates on behalf of a custom domain, you must prove that you control the domain name specified in the certificate through DNS validation. Per the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555#section-2), Pomerium uses its own ACME client to communicate with Let's Encrypt, a free Certificate Authority, to validate a domain's DNS records.
+
+Let's Encrypt provides several [challenge types](https://letsencrypt.org/docs/challenge-types/) to validate a domain, including the [DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). At a high level, this challenge requires that either:
+
+- A `TXT` record must be placed at `_acme-challenge.<YOUR_DOMAIN>`
+- Or, a `CNAME` record must be placed at `_acme-challenge.<YOUR_DOMAIN>` that points to another domain with the `TXT` record
+
+Because Pomerium owns the `pomerium.app` subdomain, we can write the `TXT` record for you. All you need to do is point a wildcard CNAME record to your cluster's starter domain.

content/docs/capabilities/device-identity.mdx

@@ -67,6 +67,14 @@ Enterprise users can build policies that only grant access to a route if a user
 
 The Enterprise Console’s **Manage Devices** GUI provides a dashboard where administrators can enroll devices and generate custom registration links for users in their directory.
 
+:::enterprise
+
+Before you can generate device registration links for users within your directory, you must sync your directory data first.
+
+See [**Directory Sync**](/docs/capabilities/directory-sync) for more information.
+
+:::
+
 To enroll a new device:
 
 1. In the Console sidebar, select **Devices**

content/docs/capabilities/directory-sync.mdx

@@ -0,0 +1,70 @@
+---
+id: directory-sync
+title: Directory Sync
+description: Directory Sync in Pomerium Enterprise allows you to import organizational directory data and external data sources you can use in authorization policies.
+keywords: [directory sync, idp, identity provider, groups, directory]
+---
+
+# Directory Sync
+
+**Directory Sync** is the process of synchronizing external directory data from your identity provider into the Enterprise Console. This document discusses how directory sync works in Pomerium and its use cases.
+
+:::enterprise
+
+**Directory Sync** is a Pomerium Enterprise feature. [Contact us](https://www.pomerium.com/enterprise-sales/) to upgrade today.
+
+:::
+
+:::note
+
+**Directory Sync** integrations in the Enterprise Console are only available for certain identity providers. See [**IdP Options**](#idp-options) below for more information.
+
+:::
+
+## Directory sync in the Enterprise Console
+
+To start a directory sync in the Enterprise Console:
+
+1. Go to the **Identity Providers** tab
+1. Select your **Identity Provider**
+1. Next to **IDP Options**, fill out the required fields (see [**IdP Options**](#idp-options) below for more information)
+1. In the [**Polling Min Delay**](/docs/reference/identity-provider-settings#identity-provider-polling-minmax-delay) and [**Polling Max Delay**](/docs/reference/identity-provider-settings#identity-provider-polling-minmax-delay) fields, keep the default durations
+1. Select **SAVE SETTINGS** ![Selecting the Identity Providers tab in Enterprise Console for a directory sync](./img/directory-sync/directory-sync-idp-tab.gif)
+
+Once you save your settings, it may take awhile for the sync to complete. Go to [**Monitor directory sync**](#monitor-directory-sync) for more information.
+
+### Monitor directory sync
+
+The Enterprise Console polls the identity provider data source based on the durations defined in the **Polling Min Delay** and **Polling Max Delay** fields.
+
+See [**Identity Provider Min/Max Delay**](/docs/reference/identity-provider-settings#identity-provider-polling-minmax-delay) for more information on how to monitor directory sync.
+
+### IdP Options
+
+The requirements and instructions for directory sync vary depending on the identity provider. You can view the **IDP Options** for an identity provider in the Enterprise Console, or refer to the relevant identity provider guide for vendor-specific steps:
+
+- [Auth0](/docs/identity-providers/auth0)
+- [Cognito](/docs/identity-providers/cognito)
+- [Microsoft Entra ID (Azure AD)](/docs/identity-providers/azure)
+- [GitHub](/docs/identity-providers/github)
+- [GitLab](/docs/identity-providers/gitlab)
+- [Google](/docs/identity-providers/google)
+- [Okta](/docs/identity-providers/okta)
+- [OneLogin](/docs/identity-providers/one-login)
+- [Ping](/docs/identity-providers/ping)
+
+## How to use directory sync
+
+### Directory data as policy criteria
+
+After a successful sync, directory data sourced from your identity provider will be available in the Enterprise Console. You can use this data as context in your authorization policies to control which users and groups can access upstream applications and services: ![Using directory sync group data as criteria in the Enterprise Console PPL builder](./img/directory-sync/directory-sync-group-criteria.png)
+
+### Device enrollment
+
+Administrators can generate custom device registration links for users within their directory: ![Generating device registration links for users in the Enterprise Console](./img/directory-sync/device-enrollment.png)
+
+:::enterprise
+
+See [**Device Identity**](/docs/capabilities/device-identity) for more information on how to enroll and manage devices in the Enterprise Console.
+
+:::