From 1d24019544f4b8b9317d435d916aa4c9ee6f266fe5f25a127dc6eca98813ddfe Mon Sep 17 00:00:00 2001
From: Tyler J King <tking727@gmail.com>
Date: Tue, 14 Apr 2026 05:30:06 -0400
Subject: [PATCH] docs: add Intune connector configuration guide

Signed-off-by: Tyler King <tking@guildhouse.dev>
---
 INTUNE.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 INTUNE.md

diff --git a/INTUNE.md b/INTUNE.md
new file mode 100644
index 0000000..cf54471
--- /dev/null
+++ b/INTUNE.md
@@ -0,0 +1,86 @@
+# 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 |