Skip to main content

Device Identity

tip

This article describes a use case available to Pomerium Enterprise customers.

Overview​

One of the core components of the zero trust security model is device identity, which is the ability for a device to have a unique, unclonable identity string that can be authenticated and factored into access control decisions. This topic page covers the concept of device identity, and how it applies to the zero trust model.

Implement Device Identity with Pomerium​

Pomerium supports policies that use device identity since version 0.16.0. We use the Web Authentication (WebAuthN) API to bring authentication and authorization based on device identity into your security framework. Pomerium's device identity support enables users to register their devices, and administrators to enforce access to applications and services to a particular set of trusted devices.

To get started, review the following pages:

  • Pomerium Policy Language to learn how to build policies that use device ID.
  • End Users should review Enroll a Device 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 reference material to create pre-approved enrollment links for users.
  • pomerium/webauthn on GitHub, our implementation of the WebAuthn specification.

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).

Example device enrollment

Search Users​

New Enrollment URLs are only valid for the specified user.

Redirect URL​

Optional: 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.

User Initiated Device Enrollment​

If a Pomerium route is configured to require device authentication, then the user must register a trusted execution environment (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 installations. However, Enterprise users may also receive registration links generated by their administrators, 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:

    The WebAuthn Registration page with no devices registered

    Users can also get to the registration page from the special .pomerium endpoint available on any route, at the bottom of the page:

    The Device Credentials section of the .pomerium endpoint with the WebAuthn link highlighted

  2. Click on Register New Device. Your browser will prompt you to provide access to a device. This will look different depending on the browser, operating system, and device type:

    The device authentication prompt on Windows

    The device authentication prompt in Google Chrome

    The device authentication prompt in Firefox

    The device authentication prompt on ChromeOS

Find Device ID​

If a route's policy is configured to only allow specific device IDs you will see a 450 error even after registering:

450 device not authorized error screen

From the .pomerium endpoint you can copy your device ID to provide to your Pomerium administrator.

Device ID list at /.pomerium

From here you can also delete the ID for devices that should no longer be associated with your account.

Admin Initiated (Pre-Approved) Device Enrollment​

If a Pomerium route is configured to require device authentication, then the user must register a trusted execution environment (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 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 environments,
  • You must have the Admin role in the Enterprise Console to perform these steps.

  1. From the Pomerium Enterprise Console, select Devices from the left-hand menu.

  2. Click the + NEW ENROLLMENT button at the top:

    Visualization of the fist two steps in creating a device enrollment link

  3. 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, or restrict the user to secure enclaves: Screenshot of the New Enrollment Modal

  4. Click Submit to get the URL:

    Screenshot of a new enrollment link

    Provide the URL to the user.