admin enrollment guide (#3061)

docs/.vuepress/config.js

@@ -224,6 +224,7 @@ module.exports = {
             "cloud-run",
             "mtls",
             "code-server",
+            "admin-enroll-device",
             "enroll-device",
             "grafana",
             "gitlab",

docs/enterprise/console-settings.yaml

@@ -179,7 +179,7 @@ settings:
               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.
+              - Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved. See our [Pre-Approved Device Enrollment](/guides/admin-enroll-device.md) guide for more information.
 
           - name: "Devices List"
             doc: |

docs/enterprise/reference/manage.md

@@ -399,7 +399,7 @@ Introduced in v0.16.0, the **Manage Devices** page lets administrators manage us
 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.
+- Administrators can use the **New Enrollment** button to create a link for the user to enroll a device as pre-approved. See our [Pre-Approved Device Enrollment](/guides/admin-enroll-device.md) guide for more information.
 
 
 ### Devices List

docs/guides/admin-enroll-device.md

@@ -0,0 +1,45 @@
+---
+title:  Admin Device Enrollment
+lang: en-US
+meta:
+  - name: keywords
+    content: >-
+      pomerium, identity access proxy, webauthn, device id, enroll, enrollment,
+      authentication, authorization, enterprise
+description: >-
+  This guide covers how Pomerium Enterprise admins can create pre-approved device registration links.
+---
+
+# Pre-Approved Device Enrollment
+
+If a Pomerium route is configured to [require device authentication](/docs/topics/ppl.md#device-matcher), then the user must register a [trusted execution environment](/docs/topics/device-identity.md#authenticated-device-types) (**TEE**) device before accessing the route. In Enterprise environments, policies can require that devices be approved in the Pomerium Enterprise Console.
+
+To make the management of approved devices easier, the Enterprise Console lets administrators create registration links that will allow users to register devices as pre-approved, following the [**TOFU**](https://en.wikipedia.org/wiki/Trust_on_first_use) authentication scheme.
+
+This guide instructs Pomerium Enterprise admins on how to create user-specific enrollment links.
+
+## Before You Begin
+
+- This guide is written for [Pomerium Enterprise](/enterprise/about.md) environments,
+- You must have the [Admin](/enterprise/concepts.md#admin) role in the Enterprise Console to perform these steps.
+
+## Create an Enrollment Link
+
+1. From the Pomerium Enterprise Console, select **Devices** from the left-hand menu.
+
+1. Click the **+ NEW ENROLLMENT** button at the top:
+
+   ![Visualization of the fist two steps in creating a device enrollment link](./img/admin-enroll-1.png)
+
+1. From the **New Enrollment** modal:
+
+    - search for and select the user this URL will be valid for,
+    - optionally provide a URL for the user to be redirected to after a successful enrollment,
+    - define if the user can enroll any [trusted execution environment](/docs/glossary.md#trusted-execution-environment), or restrict the user to [secure envlaves](/docs/glossary.md#secure-enclave):
+    ![Screenshot of the New Enrollment Modal](./img/new-enrollment.png)
+
+1. Click **Submit** to get the URL:
+
+    ![Screenshot of a new enrollment link](./img/enrollment-created.png)
+
+    Provide the URL to the user.

docs/guides/enroll-device.md

@@ -1,5 +1,5 @@
 ---
-title: Enroll a Device
+title: User Device Enrollment
 lang: en-US
 meta:
   - name: keywords
@@ -10,11 +10,11 @@ description: >-
   This guide covers how to enroll a trusted execution environment device as a Pomerium end-user.
 ---
 
-# Enroll a Device
+# Enroll a Device as a User
 
 If a Pomerium route is configured to [require device authentication](/docs/topics/ppl.md#device-matcher), then the user must register a [trusted execution environment](/docs/topics/device-identity.md#authenticated-device-types) (**TEE**) device before accessing the route. Registration is easy, but different depending on the device being used to provide ID.
 
-This guide covers enrollment of a device by a user. This is available for both open-source Pomerium and [Pomerium Enterprise](/enterprise) installations. However, Enterprise users may also receive registration links [generated by their administrators](/enterprise/reference/manage.md#new-enrollment), which will mark the newly enrolled device as approved in the Pomerium Enterprise Console.
+This guide covers enrollment of a device by a user. This is available for both open-source Pomerium and [Pomerium Enterprise](/enterprise) installations. However, Enterprise users may also receive registration links [generated by their administrators](/guides/admin-enroll-device.md), which will mark the newly enrolled device as approved in the Pomerium Enterprise Console.
 
 1. Users are prompted to register a new device when accessing a route that requires device authentication:
 

docs/guides/img/new-enrollment.png

@@ -0,0 +1 @@
+../../enterprise/img/new-enrollment.png

docs/guides/readme.md

@@ -7,7 +7,8 @@ This section contains applications, and scenario specific guides for Pomerium.
 - The [Client-Side mTLS](./mtls.md) guide demonstrates how Pomerium can be used to add mutual authentication to end-user connections using client certificates and a custom certificate authority.
 - The [Cloud Run](./cloud-run.md) recipe demonstrates deploying Pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints.
 - The [code-server](./code-server.md) guide demonstrates how Pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905). code-server is a tool to run Visual Studio code as a web application.
-- See [Enroll a Device](./enroll-device.md) to learn how to register a security device (TPM, Yubikey, etc) to access routes requiring a device ID.
+- See [Device Admin-Enrollment](./admin-enroll-device.md) to create pre-approved device enrollment links in the Pomerium Enterprise Console.
+- See [Device User-Enrollment](./enroll-device.md) to learn how to register a security device (TPM, Yubikey, etc) to access routes requiring a device ID.
 - The [GitLab](./gitlab.md) guide covers securing a self-hosted instance of GitLab using Pomerium.
 - Our [Grafana](./grafana.md) guide explains how to secure Grafana with Pomerium and integrate user sign-in using our JWT.
 - The [JWT Verification](./jwt-verification.md) guide demonstrates how to verify the Pomerium JWT assertion header using Envoy.