diff --git a/docs/docs/topics/device-identity.md b/docs/docs/topics/device-identity.md index e57e8e9a8..c288fb263 100644 --- a/docs/docs/topics/device-identity.md +++ b/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 diff --git a/docs/enterprise/console-settings.yaml b/docs/enterprise/console-settings.yaml index a585d1257..14ce40cbf 100644 --- a/docs/enterprise/console-settings.yaml +++ b/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" diff --git a/docs/enterprise/img/console-devices.png b/docs/enterprise/img/console-devices.png new file mode 100644 index 000000000..3e9de4bae Binary files /dev/null and b/docs/enterprise/img/console-devices.png differ diff --git a/docs/enterprise/img/new-enrollment.png b/docs/enterprise/img/new-enrollment.png new file mode 100644 index 000000000..99de9ce65 Binary files /dev/null and b/docs/enterprise/img/new-enrollment.png differ diff --git a/docs/enterprise/pomerium-console_serve.yaml b/docs/enterprise/pomerium-console_serve.yaml index 78439c0ea..b2f117c74 100644 --- a/docs/enterprise/pomerium-console_serve.yaml +++ b/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 diff --git a/docs/enterprise/reference/config.md b/docs/enterprise/reference/config.md index fda89f07f..e1335a9bb 100644 --- a/docs/enterprise/reference/config.md +++ b/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 diff --git a/docs/enterprise/reference/manage.md b/docs/enterprise/reference/manage.md index 30f7fc4f7..01bc4d62c 100644 --- a/docs/enterprise/reference/manage.md +++ b/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 diff --git a/docs/enterprise/upgrading.md b/docs/enterprise/upgrading.md index dda1a8c8a..26e342a87 100644 --- a/docs/enterprise/upgrading.md +++ b/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