FleetDM provides an open-source, scalable device management (MDM) solution that supports all major operating systems, including macOS, Linux, and Windows.

The FleetDM integration with Pomerium Enterprise enables you to build policies in Pomerium that express Fleet conditions as Pomerium policy language (PPL).

When Pomerium receives a request from a Fleet-managed device, Pomerium will make an authorization decision based on the device's state and the applied policy criteria.

## Video Demo

## How Pomerium works with FleetDM

FleetDM provides a dedicated web service (Fleet UI) where administrators can manage teams, issued devices (”enrolled hosts”), Fleet policies, and more.

The Fleet agents periodically query hosts to gather updated host data, and push the information to Fleet servers. Administrators can view host data in Fleet UI.

Pomerium can integrate your Fleet instance as an external data source (the “FleetDM plugin”) in the Enterprise Console. You can use custom PPL criteria to build policies in Pomerium that enforce Fleet conditions before authorizing or denying access to services behind Pomerium. For example, Pomerium can deny access if:

- A device fails a [policy](https://fleetdm.com/securing/what-are-fleet-policies) defined in Fleet.
- A device is affected by a [vulnerability](https://fleetdm.com/guides/vulnerability-processing).

### Host matching with client certificates

Integrating the FleetDM plugin returns the following records in the Enterprise Console:

- `fleetdm.com/CertificateSHA1Fingerprint`: represents a client certificate SHA-1 fingerprint that maps to a Fleet host ID
- `fleetdm.com/Host`: represents the state of a Fleet host
- `fleetdm.com/Policy`: represents a Fleet policy

Pomerium matches an incoming request with a Fleet-managed host by requiring the user to present a valid client certificate in the browser.

Pomerium receives the client certificate, generates its SHA-1 fingerprint, and matches it with the host ID stored in the FleetDM plugin.

Pomerium Enterprise continuously syncs [host](https://fleetdm.com/docs/rest-api/rest-api#example33) data from FleetDM. The host data represents its compliance to Fleet policies and exposure to vulnerabilities.

### FleetDM PPL criteria

Pomerium provides a custom FleetDM criterion that points to records collected from the FleetDM plugin.

Custom FleetDM operators enable you to build policies that enforce Fleet conditions. Only [deny](https://www.pomerium.com/docs/internals/ppl.md#actions) actions are supported.

Custom FleetDM operators include:

| **Key name** | **Value type** | **Description** |
| --- | --- | --- |
| `last_seen_over` | string | Denies access if a Fleet agent hasn't updated host data in the specified time. |
| `vulnerabilities` | array(string) | Denies access if a host is affected by a specific CVE. |
| `failing_policies` | array(int) | Denies access if a host fails a specific Fleet policy. |
| `failing_critical_policy` | boolean | Denies access if a host fails any critical Fleet policies. |
| `failing_any_policy` | boolean | Denies access if a host fails any Fleet policy. |

## Configure FleetDM

This guide shows you how to configure FleetDM to work with the FleetDM plugin in Pomerium Enterprise. After integrating the plugin, you'll build authorization policies in the PPL builder with custom FleetDM criteria.

To complete this guide, you need:

- [Pomerium Enterprise](https://www.pomerium.com/docs/deploy/enterprise.md)
- [Pomerium Core](https://www.pomerium.com/docs/deploy/core.md)
- A deployed [Fleet instance](https://github.com/fleetdm/fleet/tree/main/infrastructure/render)
- A configured certificate authority (CA) and client certificate
- A test environment to install a Fleet agent

For the purposes of this guide, we recommend that you:

- Install the Fleet agent in a VM running macOS. You can install and run a macOS VM for free with Tart. See the [**Tart Quickstart**](https://tart.run/quick-start/) for more information.

- Use locally trusted certificates to test this implementation. This guide uses [**mkcert**](https://github.com/FiloSottile/mkcert) to install a local CA that issues self-signed client certificates. However, this option is **not suitable for production environments**.

Lastly, this is not a production configuration. A production configuration requires a private CA integration with FleetDM, which is out of scope for this guide.

### Enroll a host

After you [deploy Fleet](https://github.com/fleetdm/fleet/tree/main/infrastructure/render), you can access the Fleet dashboard. This is where you can enroll and manage hosts, build queries, and more.

\[The FleetDM dashboard and management web console]

Fleet [gathers host information](https://fleetdm.com/guides/enroll-hosts) by installing an [osquery](https://github.com/osquery/osquery) agent (”Fleet agent”) on each host.

To enroll a host, download the Fleet agent:

1. In the navigation bar, select **Hosts.**

2. Select **Add hosts**.

3. Select the operating system of the host you want to add. (This guide assumes **macOS.**)

4. Enter the provided command with the [Fleet command-line tool](https://fleetdm.com/guides/fleetctl).

   \[Adding a Fleet host in the Fleet dashboard]

   Running this command generates a `fleetd` installation package:

   ```bash
   Generating your fleetd agent...

   Success! You generated fleetd at /Users/<username>/fleet-osquery.pkg

   To add this device to Fleet, double-click to install fleetd.

   To add other devices to Fleet, distribute fleetd using Chef, Ansible, Jamf, or Puppet. Learn how: https://fleetdm.com/learn-more-about/enrolling-hosts
   ```

5. Run your macOS VM and install the `fleet-osquery.pkg`.

   If you check your Fleet dashboard, you should see the VM listed as an enrolled host:

   \[Reviewing the enrolled host in the Fleet dashboard]

6. Install your client certificate on the VM where you installed the Fleet agent (see the mkcert [Advanced options](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#advanced-options) if you don't know how to generate a client certificate). Once you've installed the client certificate, you must import it into the VM's local Keychain.

   To import the client certificate, run the [security import](https://ss64.com/mac/security.html) command below inside the VM. Make sure you replace the `client-cert-location` parameter with the location of the client certificate in the VM.

   ```bash
   security import <client-cert-location>  -A -P changeit -k ~/Library/Keychains/login.keychain-db
   ```

### Configure certificate query

Fleet agents provide a [certificates](https://fleetdm.com/tables/certificates) query that scans a device's local key store for installed certificates. This query exposes certificates data, including the client certificate SHA-1 fingerprint installed on an enrolled host.

To configure the certificate query, in the Fleet dashboard:

1. Select **Queries.**

2. Select **Add query.**

3. Enter the following SQL command in the query field:

   ```sql
   SELECT * FROM certificates where ca != 1;
   ```

4. Select **Save** and enter a **Name**, **Description**, and **Frequency**.

   \[Entering a certificate query SQL command in the Fleet dashboard]

In the Fleet dashboard, you can review a host's certificate details on the **Queries** page:

1. Select **Queries**.
2. Select the certificate query.
3. Find a host to review its certificate data.

   \[Reviewing the client certificate SHA-1 fingerprint in the Fleet dashboard]

### Create a Fleet policy

In the Fleet dashboard:

1. Select **Policies**.
2. Select **Add policy**.
3. Select a policy template, like **Gatekeeper enabled (macOS).**
4. Save your policy.

At this point, you can add as many policies as you like. You can also mark a policy as critical by selecting the **Critical** checkbox.

\[Creating a Fleet policy in the Fleet dashboard]

See the Fleet [policies](https://fleetdm.com/docs/rest-api/rest-api#policies) documentation to learn about how policies work.

## Configure the FleetDM plugin

The following sections show you how to configure the FleetDM plugin in the Enterprise Console.

### Configure the external data source

Next, add the FleetDM plugin as an external data source in the Enterprise Console.

This step requires you to run the [FleetDM plugin](https://github.com/pomerium/datasource/tree/main) with its Docker image.

These instructions assume a local testing environment using [Docker Compose](https://docs.docker.com/compose/). Adjust as needed for your deployment environment.

1. Add the FleetDM plugin Docker image to Docker Compose:

   ```yaml
   services:
     fleetdm:
       image: docker.cloudsmith.io/pomerium/datasource/datasource:main
       command:
         - fleetdm
         - --api-url=https://pomerium.cloud.fleetdm.com/
         - --api-token=<YOUR_FLEETDM_API_TOKEN>
         - --cert-query-id=<YOUR_FLEETDM_CERT_QUERY_ID>
         - --address=:8080
       container_name: fleetdm
       restart: always
       expose:
         - 8080
   ```

2. Run the container:

   ```bash
   docker compose up
   ```

In the Enterprise Console:

1. Select **External Data**.
2. Select **ADD EXTERNAL DATA SOURCE**.
3. In the **URL** field, enter the URL to the external data source.
4. Select **SAVE EXTERNAL DATA SOURCE**.

### Import Certificate Authority (CA)

In the Enterprise Console:

1. Select **Certificates**.
2. Select **ADD CERTIFICATE**.
3. Add the root CA file (`rootCA.pem`). \[Importing the mkcert root CA into the Enterprise Console]

### Create a route

Next, create a route you want to protect. This guide will use Pomerium's [Verify](https://github.com/pomerium/verify) service as an example.

In the Enterprise Console:

1. Select **Routes**.
2. Select **New Route** and name it.
3. In **From:**, enter the externally accessible URL.
4. In the **To:** field, enter the destination URL.

   \[Build a route in the Enterprise Console]

Now, configure the route to require a client certificate issued by a CA:

1. Under route settings, select **TLS Settings**.
2. In the field [**TLS Downstream Client Certificate Authority**](https://www.pomerium.com/docs/reference/routes/tls.md#tls-downstream-client-certificate-authority), select **Downstream CA**.

   \[Adding the Downstream CA setting to the route]

### Create policies in Pomerium

Create policies that deny access based on FleetDM criteria:

1. Select **Policies,** create a **New Policy**, and name it.
2. Select the **Builder** tab.
3. Select **Add Deny Block**.
4. In the **Criteria** field, select **FleetDM**.
5. In the **Operator** field, select **Failing Policies**.
6. In the **Search Policies** bar, Pomerium will list Fleet policies. Select the policy you want to apply.

   \[Building a policy in the PPL builder using FleetDM criteria]

You can also deny access based on vulnerabilities:

1. In the **Operator** field, select **Vulnerabilities**.
2. Enter the vulnerability by its CVE ID. For example, `CVE-2020-10735`.

   \[Building a policy in the PPL builder using FleetDM criteria]

Save your policies.

### Attach policies

Next, attach these policies to your route:

1. Select the route.
2. In the **Policies** field, select your policies.

   \[Attaching policies to route]

Save your changes. When you access a Pomerium route with a Fleet-managed host, Pomerium will authorize access based on the host's compliance to Fleet policies and vulnerability status.