diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 7fd44248d..34673515b 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -224,6 +224,7 @@ module.exports = { "cloud-run", "mtls", "code-server", + "admin-enroll-device", "enroll-device", "grafana", "gitlab", diff --git a/docs/enterprise/console-settings.yaml b/docs/enterprise/console-settings.yaml index 546c2bb46..41039e9af 100644 --- a/docs/enterprise/console-settings.yaml +++ b/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: | diff --git a/docs/enterprise/reference/manage.md b/docs/enterprise/reference/manage.md index 8f542b41e..922e5b05a 100644 --- a/docs/enterprise/reference/manage.md +++ b/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 diff --git a/docs/guides/admin-enroll-device.md b/docs/guides/admin-enroll-device.md new file mode 100644 index 000000000..1440053dd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/guides/enroll-device.md b/docs/guides/enroll-device.md index 7d00ed69c..6a3cfc9ab 100644 --- a/docs/guides/enroll-device.md +++ b/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: diff --git a/docs/guides/img/admin-enroll-1.png b/docs/guides/img/admin-enroll-1.png new file mode 100644 index 000000000..7cdc2e80b Binary files /dev/null and b/docs/guides/img/admin-enroll-1.png differ diff --git a/docs/guides/img/enrollment-created.png b/docs/guides/img/enrollment-created.png new file mode 100644 index 000000000..1c48bd11a Binary files /dev/null and b/docs/guides/img/enrollment-created.png differ diff --git a/docs/guides/img/new-enrollment.png b/docs/guides/img/new-enrollment.png new file mode 120000 index 000000000..c879e1d8f --- /dev/null +++ b/docs/guides/img/new-enrollment.png @@ -0,0 +1 @@ +../../enterprise/img/new-enrollment.png \ No newline at end of file diff --git a/docs/guides/readme.md b/docs/guides/readme.md index ff76010b4..69de6051a 100644 --- a/docs/guides/readme.md +++ b/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.