# Intune Connector — Configuration Guide

## Azure AD App Permissions

Register an Azure AD application with the following Microsoft Graph API permissions (Application type, not Delegated):

| Permission | Type | Required For |
|------------|------|-------------|
| `DeviceManagementManagedDevices.Read.All` | Application | list_devices, get_device, get_compliance |
| `DeviceManagementManagedDevices.ReadWrite.All` | Application | sync_device, remote_lock, retire_device, wipe_device |

Grant admin consent for your tenant after adding the permissions.

## Environment Variables

```bash
# Enable the Intune connector
INTUNE_ENABLED=true

# Entra credentials (shared with the Entra registrar)
ENTRA_TENANT_ID=your-tenant-id
ENTRA_CLIENT_ID=your-app-client-id
ENTRA_CLIENT_SECRET=your-app-client-secret

# Compliance gating (optional)
INTUNE_COMPLIANCE_REQUIRED=false   # Global default for all accord templates
INTUNE_COMPLIANCE_STRICT=false     # Reject if no device_id in token
INTUNE_COMPLIANCE_CACHE_TTL=300    # Cache compliance state for 5 minutes
```

## Compliance-Gated AC Issuance

When `INTUNE_ENABLED=true`, the authorize endpoint can gate AC issuance on device compliance.

### Global Default

Set `INTUNE_COMPLIANCE_REQUIRED=true` to require compliance for all accord templates.

### Per-Accord Override

Accord templates can override the global default. Currently configured in `routers/authorize.py`:

```python
_ACCORD_COMPLIANCE = {
    "infrastructure-operations": {"device_compliance_required": True},
    "device-management": {"device_compliance_required": True},
}
```

### Strict vs Permissive Mode

- **Strict** (`INTUNE_COMPLIANCE_STRICT=true`): Rejects AC issuance if the token does not contain a device ID (e.g., Keycloak tokens without device claims). Use for environments where every operator must be on a managed device.

- **Permissive** (`INTUNE_COMPLIANCE_STRICT=false`, default): Allows AC issuance without device compliance fields when no device ID is present. Compliance is only checked when a device ID is available.

## Connector Operations

| Operation | Capability | Description |
|-----------|-----------|-------------|
| `list_devices` | READ | List managed devices |
| `get_device` | READ | Get device details |
| `get_compliance` | READ | Check compliance state (cached) |
| `sync_device` | PROPOSE | Trigger Intune device sync |
| `remote_lock` | MUTATE | Remote lock a device |
| `retire_device` | MUTATE | Retire from management |
| `wipe_device` | MUTATE | Factory reset device |

MUTATE operations (lock, retire, wipe) should be gated by ceremony approval in production accord templates via `ceremony_required_for` in the delegation scope.

## MCP Tools

When Intune is enabled, the MCP endpoint exposes:

- `list_devices` — List managed devices
- `get_device_compliance` — Check device compliance
- `sync_device` — Trigger device sync
- `remote_lock` — Remote lock (requires MUTATE)

All MCP tool calls route through the governed `IntuneConnector`, ensuring Chronicle audit trails.

## Chronicle Events

| Event | Code | Emitted When |
|-------|------|-------------|
| `CONNECTOR_INVOKED` | — | Every Intune connector invocation |
| `DEVICE_COMPLIANCE_CHECKED` | `0x2801` | Compliance gate evaluated during AC issuance |