Microsoft Intune Connector

Overview

Connects to Microsoft Entra ID and Microsoft Intune via the Microsoft Graph API to read groups, group members, and managed devices into Xurrent.

Prerequisites

• A Microsoft Entra ID (formerly Azure AD) tenant.
• An app registration in Microsoft Entra. Obtain:
• Tenant ID: GUID visible in Microsoft Entra → Overview → Tenant ID.
• Client ID: visible on the app registration's Overview page.
• Client Secret: created under the app registration's Certificates & secrets. Copy the value at creation time; it is not shown again.
• API permissions granted on the app registration (type: Application):
• Device.Read.All (Microsoft Graph API) With API Permission type : Application.
• GroupMember.Read.All: used by the group lookup and group members actions.
• DeviceManagementManagedDevices.Read.All: used by the Intune managed devices action.

Authentication

The connector uses the OAuth 2.0 client credentials flow against https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token and requests the https://graph.microsoft.com/.default scope. The Tenant ID, Client ID, and Client Secret obtained in Prerequisites are passed as:

• tenant_id: substituted into the OAuth2 token endpoint URL.
• client_id and client_secret: sent in the token request body as form-encoded credentials.

Triggers

None. This connector is outbound only.

Actions

Entra group ID from name

Retrieves Microsoft Entra group IDs for a list of display names in a single request via Microsoft Graph's group list API.

Use case: convert human-readable group names to their IDs before calling other actions (e.g. Retrieve Entra group members). Also useful to validate that a group exists in the tenant.

Permissions required: GroupMember.Read.All

Input Parameters

Example Input

{
"group_names": ["IT Administrators", "Sales Team", "Marketing Department"]
}

Output

Result object fields

Example Output

{
"results": [
  {
    "display_name": "IT Administrators",
    "group_id": "12345678-1234-1234-1234-123456789012"
  }
]
}

Error Handling

The job fails without retry on 400 / 401 / 403 responses (invalid input or credential / permission issue). On 429 (rate limited) or 503 (service unavailable), the connector waits for the time in Retry-After and retries the request.

Operational notes

• Call at the start of runbooks that operate on groups by name. Pass the returned IDs to Retrieve Entra group members or other group actions.
• Group display names are case-sensitive and must match the value stored in Entra (e.g. it administrators will not match a group named IT Administrators).
• The connector deduplicates group_names before calling Microsoft Graph, so input length minus distinct-output length is the count of misses.
• Groups not found in Entra are omitted from the results.

Retrieve Entra group members

Retrieves all members of a Microsoft Entra ID group with pagination support via Microsoft Graph's group members API. Members may be users, devices, or other directory objects.

Use case: audit group memberships, synchronize group data with other systems, or process group members in workflows that need user or device information. Pair with Entra group ID from name to resolve the group_id from a friendly name first.

Permissions required: GroupMember.Read.All

Input Parameters

Example Input

{
"group_id": "12345678-1234-1234-1234-123456789012",
"page_size": 50
}

Output

Member object fields

Example Output

{
"members": [
  {
    "member_id": "87654321-4321-4321-4321-210987654321",
    "device_id": null,
    "odata_type": "#microsoft.graph.user"
  },
  {
    "member_id": "98765432-5432-5432-5432-321098765432",
    "device_id": "device123",
    "odata_type": "#microsoft.graph.device"
  }
]
}

Error Handling

The job fails without retry on 400 / 401 / 403 responses (invalid input or credential / permission issue), or when a member's required fields are missing. On 429 (rate limited) or 503 (service unavailable), the connector waits for the time in Retry-After and retries the request.

Limitations

• Microsoft Graph v1.0 does not return service principals as members (known issue). If your runbook depends on service principal membership, follow the workaround in the linked doc.

Operational notes

• Pair with Entra group ID from name to resolve group_id from a friendly group name.
• Paginate to completion: call until has_next_page is false.
• Branch on odata_type to detect member kind, not on device_id presence (#microsoft.graph.user vs. #microsoft.graph.device).
• For large groups, raise page_size toward the max (999) to reduce round-trips.

Managed devices from Intune

Retrieves devices managed through Microsoft Intune with pagination support via Microsoft Graph's managed devices API. Returns device identity, hardware, operating system, user association, compliance, and enrollment details.

Use case: populate or refresh the list of Intune-managed devices in Xurrent's CMDB for inventory, compliance monitoring, user-device mapping, or security audits. For incremental updates, set Last sync to fetch only devices whose lastSyncDateTime is at or after the given time.

Permissions required: DeviceManagementManagedDevices.Read.All

Input Parameters

Example Input

{
"last_sync": "2024-01-01T00:00:00Z",
"page_size": 50
}

Output

Device object fields

Example Output

{
"has_next_page": true,
"devices": [
  {
    "device_id": "12345678-1234-1234-1234-123456789012",
    "manufacturer": "Microsoft",
    "model": "Surface Pro 8",
    "device_name": "SURFACE-JOHN-01",
    "serial_number": "X123456789",
    "last_sync_date_time": "2024-01-15T10:30:00Z",
    "operating_system": "Windows",
    "os_version": "10.0.19045.3803",
    "user_id": "98765432-9876-9876-9876-987654321098",
    "email_address": "[REDACTED]",
    "physical_memory_in_bytes": 17179869184,
    "azure_ad_registered": true,
    "azure_ad_device_id": "87654321-8765-8765-8765-876543210987",
    "jail_broken": "Unknown",
    "enrolled_date_time": "2023-01-01T00:00:00Z",
    "device_enrollment_type": "windowsAzureADJoin",
    "managed_device_owner_type": "company",
    "is_encrypted": true,
    "compliance_state": "compliant",
    "user_principal_name": "[REDACTED]",
    "phone_number": "+********4703",
    "wi_fi_mac_address": "00:1F:5A:9D:44:21",
    "ethernet_mac_address": "A4:9C:3F:12:6B:8E",
    "total_storage_space_in_bytes": 256000000000,
    "free_storage_space_in_bytes": 68021125120
  }
]
}

Error Handling

The job fails without retry on 400 / 401 / 403 responses (invalid input or credential / permission issue). On 429 (rate limited) or 503 (service unavailable), the connector waits for the time in Retry-After and retries the request.

Operational notes

• Incremental syncs: Set last_sync to the start time (UTC) of your previous run. Storing the max last_sync_date_time observed in this run can miss devices whose timestamp advances between page fetches.
• Filter downstream: Branch on compliance_state for security audits, or on managed_device_owner_type for BYOD vs. corporate fleets.
• Paginate to completion: call until has_next_page is false.
• Treat user fields as PII: email_address and user_principal_name are secret strings. Don't log them in plain text.

Rate Limiting

Microsoft Graph throttles requests per tenant and per app and returns 429 Too Many Requests with a Retry-After header when the threshold is exceeded (reference). The connector retries on 429 and 503 responses.

Notes:

• Microsoft's throttling guidance recommends exponential backoff when Retry-After is absent.
• 503 is treated as a transient error; it is not part of Microsoft Graph's documented throttling contract.

Best Practices

• Resolve IDs at runbook start: Call Entra group ID from name to convert friendly group names into IDs. Don't hard-code GUIDs that may change.
• Incremental device syncs: Use last_sync on Managed devices from Intune with the timestamp of your last successful sync. Store the max last_sync_date_time to use next time.
• Paginate to completion: Retrieve Entra group members and Managed devices from Intune are iterator actions. Call until has_next_page is false.
• Scope permissions minimally: Grant only GroupMember.Read.All and DeviceManagementManagedDevices.Read.All on the app registration. Don't grant broader scopes.
• Protect PII: Device records include user email and UPN as secret strings. Don't log them in plain text.

Common Use Cases

• CMDB sync: Managed devices from Intune → upsert into Xurrent's CMDB keyed on device_id. Use last_sync for incremental runs.
• Security compliance: Managed devices from Intune → branch on compliance_state → route non-compliant devices into remediation workflows.
• Group-based access workflows: Entra group ID from name → Retrieve Entra group members → provision or revoke Xurrent access based on membership changes.
• BYOD vs. corporate inventory: Managed devices from Intune → segment by managed_device_owner_type for separate reporting pipelines.
• Lifecycle management: Managed devices from Intune → filter by enrolled_date_time and device_enrollment_type to identify devices due for refresh or compliance review.

References

API Reference

• Microsoft Graph REST API (v1.0)
• List groups (Microsoft Graph API)
• List group members (Microsoft Graph API)
• List managedDevices (Microsoft Graph Intune API)
• managedDevice resource type

Concepts

• Advanced query capabilities on directory objects
• Microsoft Graph throttling
• OAuth 2.0 client credentials flow
• Microsoft Graph permissions reference

Setup

• Register an application with Microsoft Entra