> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Device Management

> Enforce device security policies with MDM integration

## Overview

Formal's Mobile Device Management (MDM) integration allows you to enforce device-based security policies on user connections. By integrating with your organization's MDM solution, you can ensure that only compliant, managed devices can access protected resources through Formal.

<Warning>
  MDM-based policies require users to connect through the [Formal Desktop
  App](/docs/guides/client-apps/desktop-app), which collects and reports device
  information.
</Warning>

## How It Works

When users connect through the Formal Desktop App:

1. The app collects device information (hardware, software, security settings)
2. This information is sent to the Connector along with the connection request
3. Policies evaluate device attributes via `input.device`

## Device Information Available

Formal collects comprehensive device metadata that can be used in policies. When MDM integration is enabled, additional compliance data is available through `input.device.mdm`:

### Hardware Information

| Field                    | Description                               |
| ------------------------ | ----------------------------------------- |
| `model_name`             | Device model name (e.g., "MacBook Pro")   |
| `model_identifier`       | Model identifier (e.g., "MacBookPro18,1") |
| `serial_number`          | Hardware serial number                    |
| `hardware_uuid`          | Unique hardware identifier                |
| `activation_lock_status` | Activation lock status (macOS)            |

### Software Information

| Field                         | Description                     |
| ----------------------------- | ------------------------------- |
| `system_version`              | OS version (e.g., "14.2")       |
| `kernel_version`              | Kernel version                  |
| `computer_name`               | Computer/hostname               |
| `user_name`                   | Local user account name         |
| `system_integrity_protection` | SIP status (macOS)              |
| `secure_virtual_memory`       | Encrypted virtual memory status |
| `boot_mode`                   | Secure boot status              |

### MDM Information (When Integration Enabled)

| Field                    | Description                 |
| ------------------------ | --------------------------- |
| `enrolled`               | Device enrollment status    |
| `compliant`              | Overall compliance status   |
| `compliance_status`      | Detailed compliance state   |
| `installed_profiles`     | List of installed profiles  |
| `configuration_profiles` | MDM configuration profiles  |
| `last_checkin`           | Last MDM check-in timestamp |
| `management_status`      | Device management status    |

## MDM Platform Integration

Formal directly integrates with Kandji to automatically sync device compliance data and enforce policies based on real-time device status.

## Kandji Integration

Formal's native Kandji integration automatically syncs device compliance data and makes it available in policies through `data.mdm_devices` attributes.

#### Setup

**Option 1: UI Setup**

1. Go to [MDM Integrations](https://app.formal.ai/mdm-integrations) in the Formal console
2. Click **Connect** next to Kandji
3. Enter your Kandji API credentials:
   * **API URL**: `https://your-org.api.kandji.io`
   * **API Token**: Your Kandji API token
4. Click **Save** to enable the integration

**Option 2: Terraform Setup**
Use the `formal_integration_mdm` resource as shown in the [Terraform Configuration](#terraform-configuration) section above.

```hcl theme={null}
resource "formal_integration_mdm" "kandji" {
  name = "Kandji MDM Integration"

  kandji {
    api_key = var.kandji_api_key
    api_url = "https://your-org.api.kandji.io"
  }
}
```

## Example Policies

### Require Secure Boot

```rego theme={null}
package formal.v2

import future.keywords.if

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Device must have secure boot enabled",
  "reason": "Device security policy violation"
} if {
  not input.device.software.boot_mode == "secure"
}
```

### Block Jailbroken/Modified Devices

```rego theme={null}
package formal.v2

import future.keywords.if

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "System Integrity Protection must be enabled",
  "reason": "Device tampering detected"
} if {
  not input.device.software.system_integrity_protection == "enabled"
}
```

### Enforce Activation Lock (macOS)

```rego theme={null}
package formal.v2

import future.keywords.if

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Activation Lock must be enabled",
  "reason": "Device theft protection required"
} if {
  input.device.hardware.activation_lock_status == "disabled"
}
```

### Require Encrypted Virtual Memory

```rego theme={null}
package formal.v2

import future.keywords.if

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Encrypted virtual memory required",
  "reason": "Data protection policy"
} if {
  not input.device.software.secure_virtual_memory == "enabled"
}
```

### Allow Only Corporate Devices

```rego theme={null}
package formal.v2

import future.keywords.if

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Only corporate-issued devices allowed",
  "reason": "Device not in approved list"
} if {
  # Check against list of approved serial numbers (Policy Data Loader)
  approved_serials := data.mdm_devices

  not input.device.hardware.serial_number in approved_serials
}
```

### Conditional Access Based on Device

```rego theme={null}
package formal.v2

import future.keywords.if

# Require MFA if device is not fully compliant
session := {
  "action": "mfa",
  "reason": "MFA required for non-compliant devices"
} if {
  # Check multiple compliance factors
  version_parts := split(input.device.software.system_version, ".")
  major_version := to_number(version_parts[0])

  # Device is "marginally compliant" - allow with MFA
  major_version >= 13
  major_version < 14
  input.device.software.system_integrity_protection == "enabled"
}

# Block if device is completely non-compliant
session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Device does not meet minimum security requirements",
  "reason": "Critical compliance violations"
} if {
  # OS too old OR SIP disabled
  version_parts := split(input.device.software.system_version, ".")
  major_version := to_number(version_parts[0])

  major_version < 13
}

session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "Device does not meet minimum security requirements",
  "reason": "Critical compliance violations"
} if {
  not input.device.software.system_integrity_protection == "enabled"
}
```

## Monitoring Device Compliance

View device information in session logs:

1. Navigate to [Sessions](https://app.formal.ai/sessions)
2. Click on any session
3. Review device information in session details
4. Filter sessions by device attributes

This allows you to:

* Audit which devices are accessing resources
* Identify non-compliant devices attempting connections
* Track OS versions and security settings across your fleet

## Best Practices

<AccordionGroup>
  <Accordion title="Require Desktop App" icon="desktop">
    Enforce use of the Formal Desktop App for connections that require device
    compliance checks. Block direct connections that bypass device verification.
  </Accordion>

  <Accordion title="Layer Security" icon="layer-group">
    Combine device-based policies with user-based and resource-based policies for
    defense in depth.
  </Accordion>

  <Accordion title="Grace Periods" icon="clock">
    When implementing new device requirements, use dry-run mode first and give
    users time to update their devices.
  </Accordion>

  <Accordion title="Enable Kandji Integration" icon="arrows-rotate">
    Connect your Kandji platform to automatically sync device compliance data and
    enforce real-time policies.
  </Accordion>

  <Accordion title="Audit Regularly" icon="magnifying-glass">
    Review session logs to identify devices that frequently fail compliance
    checks.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Desktop App" icon="desktop" href="/docs/guides/client-apps/desktop-app">
    Install the Formal Desktop App
  </Card>

  <Card title="Write Policies" icon="shield-check" href="/docs/guides/policies/introduction">
    Create device-based policies
  </Card>

  <Card title="Terraform Provider" icon="code" href="/docs/guides/configuration/terraform">
    Configure Kandji integration with Terraform
  </Card>

  <Card title="Kandji Integration" icon="mobile" href="https://app.formal.ai/mdm-integrations">
    Set up Kandji integration in the Formal console
  </Card>
</CardGroup>