update Enterprise docs for 0.16.0 (#2993)

* update Enterprise docs for 0.16.0

* Update docs/enterprise/upgrading.md

Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com>

* more docs, plus cross-links

Co-authored-by: Travis Groth <travisgroth@users.noreply.github.com>

docs/docs/topics/device-identity.md

@@ -58,7 +58,8 @@ Pomerium supports policies that use device identity since version [0.16.0](/docs
 To get started, review the following pages:
 
 - [Pomerium Policy Language](/docs/topics/ppl.md) to learn how to build policies that use device ID.
-- [Enroll a Device](/guides/enroll-device.md) to teach end-users how to enroll devices on Pomerium.
+- **End Users** should review [Enroll a Device](/guides/enroll-device.md) to learn how to enroll devices on Pomerium. In Enterprise environments, self-enrollments must be approved by an admin in the Enterprise Console.
+- **Enterprise Administrators** can review the [Devices](/enterprise/reference/manage.html#devices) reference material to create pre-approved enrollment links for users.
 - [pomerium/webauthn](https://github.com/pomerium/webauthn) on GitHub, our implementation of the WebAuthn specification.
 
 ## Looking Ahead: Device Posture

docs/enterprise/console-settings.yaml

@@ -170,6 +170,36 @@ settings:
           - **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.
       - name: "Certificates"
+      - name: "Devices"
+        doc: |
+          Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
+        settings:
+          - name: "Manage Devices"
+            doc: |
+              From this page, administrators can manage new and existing device enrollments.
+              Device enrollment let's you create [policies](/docs/topics/ppl.html#device-matcher) that use [device identity](/docs/topics/device-identity.md).
+              - Users can [self-enroll](/guides/enroll-device.md) devices, which must then be approved in the **Devices List** for policies requiring approved devices.
+              - Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved.
+
+          - name: "Devices List"
+            doc: |
+              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/console-devices.png)
+          - name: "New Enrollment"
+            doc: |
+              The **New Enrollment** button allows administrators to create a custom link for a specific user to use to register a new device, which will automatically be approved.
+              This scheme is known as [Trust on First Use (TOFU)](https://en.wikipedia.org/wiki/Trust_on_first_use).
+
+              ![Example device enrollment](../img/new-enrollment.png)
+            settings:
+              - name: "Search Users"
+                doc: "New Enrollment URLs are only valid for the specified user."
+              - name: "Redirect URL"
+                doc: "**Required**: The URL the user will be taken to after device enrollment is successful."
+              - name: "Enrollment Type"
+                doc: "Specify if the user can enroll any device identity, or restrict it to a [secure enclave](/docs/topics/device-identity.md#secure-enclaves)."
   - name: "Configure"
     settings:
       - name: "Settings"

docs/enterprise/pomerium-console_serve.yaml

@@ -7,6 +7,8 @@ options:
 - name: audience
   default_value: '[]'
   usage: A list of audiences for verifying signing key
+- name: authenticate-service-url
+  usage: URL for the authenticate service
 - name: bind-addr
   default_value: :8701
   usage: the address to listen on
@@ -22,6 +24,9 @@ options:
 - name: databroker-service-url
   default_value: http://localhost:5443
   usage: the databroker service url
+- name: debug-config-dump
+  default_value: "false"
+  usage: dump databroker configuration
 - name: disable-validation
   default_value: "false"
   usage: disable config validation

docs/enterprise/reference/config.md

@@ -23,6 +23,12 @@ A list of audiences for verifying signing key
 
 **Default value:** `[]`
 
+## authenticate-service-url
+
+URL for the authenticate service
+
+**Default value:** `none`
+
 ## bind-addr
 
 the address to listen on
@@ -55,6 +61,12 @@ the databroker service url
 
 **Default value:** `http://localhost:5443`
 
+## debug-config-dump
+
+dump databroker configuration
+
+**Default value:** `false`
+
 ## disable-validation
 
 disable config validation

docs/enterprise/reference/manage.md

@@ -389,6 +389,47 @@ certificate_key:  "$HOME/.acme.sh/*.example.com/*.example.com.key"
 
 **Note:** Pomerium will check your system's trust/key store for valid certificates first. If your certificate solution imports into the system store, you don't need to also specify them with these configuration keys.
 
+## Devices
+
+Introduced in v0.16.0, the **Manage Devices** page lets administrators manage user devices for policy-based authorization.
+
+
+### Manage Devices
+
+From this page, administrators can manage new and existing device enrollments.
+Device enrollment let's you create [policies](/docs/topics/ppl.html#device-matcher) that use [device identity](/docs/topics/device-identity.md).
+- Users can [self-enroll](/guides/enroll-device.md) devices, which must then be approved in the **Devices List** for policies requiring approved devices.
+- Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved.
+
+
+### 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/console-devices.png)
+
+
+### New Enrollment
+
+The **New Enrollment** button allows administrators to create a custom link for a specific user to use to register a new device, which will automatically be approved.
+This scheme is known as [Trust on First Use (TOFU)](https://en.wikipedia.org/wiki/Trust_on_first_use).
+
+![Example device enrollment](../img/new-enrollment.png)
+
+
+#### Search Users
+
+New Enrollment URLs are only valid for the specified user.
+
+#### Redirect URL
+
+**Required**: The URL the user will be taken to after device enrollment is successful.
+
+#### Enrollment Type
+
+Specify if the user can enroll any device identity, or restrict it to a [secure enclave](/docs/topics/device-identity.md#secure-enclaves).
+
 [route-concept]: /enterprise/concepts.md#routes
 [route-reference]: /enterprise/reference/manage.md#routes
 [namespace-concept]: /enterprise/concepts.md#namespaces

docs/enterprise/upgrading.md

@@ -14,7 +14,9 @@ When new version of Pomerium Enterprise are released, check back to this page be
 
 ## Before You Upgrade
 
-- Configuring `signing-key` has been replaced by setting `authenticate-service-url`.  The [signing key] will be automatically retrieved by Pomerium Enterprise Console.  `signing-key` will continue to work, however `authenticate-service-url` is required for device enrollment.
+- The [`signing-key`](/enterprise/reference/config.md#signing-key) has been replaced with [`authenticate-service-url`](/enterprise/reference/config.md#authenticate-service-url). Instead of manually setting the signing key in the Enterprise Console to match the Authenticate Service, we specify the trusted URL of the Authenticate Service to pull the signing key from.
+
+  The `signing-key` key will continue to work for existing configurations, but [device enrollment](/enterprise/reference/manage.md#new-enrollment) will not work until it is replaced by `authenticate-service-url`.
 
 ## 0.15.0