fastapi-gsap/INTUNE.md

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

# 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:

_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