Entra Provisioning Log Export Scripts

⚠️ IMPORTANT NOTE:
KeyVault and Managed Identity authentication modes in DownloadEntraProvisioningLogs.ps1 have not been tested yet.
Please use these features with caution and validate in a non-production environment before relying on them for critical exports.

❗ CRITICAL NOTE ON -AppObjectId:
The -AppObjectId parameter requires the Object ID of the Enterprise Application (service principal), not the Application (client) ID or the Object ID from App registrations.
In the Entra portal, go to Enterprise applications > select your app > Overview. Use the value labeled Object ID (not Application ID).
Using the wrong ID will result in "not found" or empty results.

This repository contains two PowerShell scripts for exporting Microsoft Entra provisioning logs from Microsoft Graph:

• DownloadEntraProvisioningLogs.ps1
  (Automated, supports app/client secret, Key Vault, or managed identity authentication)
• DownloadEntraProvisioningLogs-Interactive.ps1
  (Interactive, uses Microsoft Graph PowerShell module and user login)

---

Overview

Both scripts download Microsoft Entra provisioning logs (auditLogs/provisioning) and write them as a single JSON array, streaming each page directly to disk for low memory usage. They are intended for downstream processing (e.g., reporting or CSV conversion).

---

Script Comparison

Feature/Mode	DownloadEntraProvisioningLogs.ps1	DownloadEntraProvisioningLogs-Interactive.ps1
Authentication	App/client secret, Key Vault, Managed Identity	Interactive user login (delegated)
Module Dependency	None (uses REST API)	Microsoft.Graph PowerShell module
Intended User	Automation, service accounts	Human/analyst/admin (interactive)
Permissions Required	Application (app) permissions	Delegated permissions
Filtering	Extensive (date, status, action, identities, systems, etc.)	Same
Output	JSON array, streamed to disk	JSON array, streamed to disk
Large File Handling	Streaming, auto file naming, truncation controls	Streaming, auto file naming, truncation controls
Retry Logic	Yes (throttling, transient)	Yes (throttling, transient)
Exit Codes	0: Success, 1: Truncated, 2: Error	0: Success, 1: Truncated, 2: Error

---

DownloadEntraProvisioningLogs.ps1

Features

• Authentication:
  • Client Secret
  • Azure Key Vault
  • Managed Identity
• Filtering: Date range, status, action, identities, systems, changeId, jobId, etc.
• Streaming: Writes each page directly to disk (no large in-memory accumulation)
• Retry Logic: Handles throttling (HTTP 429) and transient failures
• Truncation Controls: -MaxPages or -MaxEntries (exit code 1 if triggered after ≥1 entry)
• Auto File Naming: Service principal display name + timestamp
• Format: Pretty (default) or Compact (smaller file)
• Verbose Mode: Paging progress and runtime
• Exit Codes: For automation and scripting

Requirements

• PowerShell 5.1+ (Windows) or PowerShell 7+ (cross-platform)
• Microsoft Graph application permission: AuditLog.Read.All (admin consent)
• (Optional) Az.KeyVault module for Key Vault secret retrieval

Example Usage

Client Secret

.\DownloadEntraProvisioningLogs.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" `
  -ClientId "<app-id>" -ClientSecret "<secret>" -OutputFolder "C:\Logs"

Azure Key Vault

.\DownloadEntraProvisioningLogs.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" `
  -ClientId "<app-id>" -KeyVaultName "<vault>" -KeyVaultSecretName "<secret-name>" -OutputFolder "C:\Logs"

Managed Identity

.\DownloadEntraProvisioningLogs.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" -ManagedIdentity -OutputFolder "C:\Logs"

---

DownloadEntraProvisioningLogs-Interactive.ps1

Features

• Authentication:
  • Interactive user login via Microsoft Graph PowerShell module (Connect-MgGraph)
• Filtering: Same as above (date, status, action, identities, systems, etc.)
• Streaming: Writes each page directly to disk (no large in-memory accumulation)
• Retry Logic: Handles throttling (HTTP 429) and transient failures
• Truncation Controls: -MaxEntries (exit code 1 if triggered after ≥1 entry)
• Auto File Naming: App object ID + filters + timestamp
• Format: Pretty (default) or Compact (smaller file)
• Verbose Mode: Paging progress and runtime
• Exit Codes: For automation and scripting

Requirements

• PowerShell 5.1+ (Windows) or PowerShell 7+ (cross-platform)
• Microsoft.Graph PowerShell module (v2+)
• Delegated permission: AuditLog.Read.All (user must have access)
• User must authenticate interactively

Example Usage

Basic Interactive Export

.\DownloadEntraProvisioningLogs-Interactive.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" -OutputFolder "C:\Logs"

With Filters

.\DownloadEntraProvisioningLogs-Interactive.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" `
  -StartDate "2024-08-01" -EndDate "2024-08-31" -Status "success" -OutputFolder "C:\Logs"

With Pretty or Compact Output

.\DownloadEntraProvisioningLogs-Interactive.ps1 -TenantId "<tenant-id>" -AppObjectId "<sp-object-id>" `
  -PrettyPrint:$false -OutputFolder "C:\Logs"

---

Filtering Examples (Both Scripts)

• Date range:

  ... -StartDate "2024-08-01" -EndDate "2024-08-07" ...

• Status:

  ... -Status success ...

• Action:

  ... -ProvisioningAction update ...

• Target identity type (URN):

  ... -TargetIdentityType "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/DynamicElement" ...

• Source & target systems:

  ... -SourceSystemDisplayName "Workday" -TargetSystemDisplayName "Active Directory" ...

• Change & job:

  ... -ChangeId "abcd1234" -JobId "11111111-2222-3333-4444-555555555555" ...

• Truncate after first page (automated script only):

  ... -MaxPages 1 ...

• Limit total entries:

  ... -MaxEntries 1500 ...

Note: Filtering by service principal display name is intentionally not supported. Display names are not guaranteed unique; the script requires the unique -AppObjectId.

---

Output

• Output file is a JSON array of provisioning log entries (no wrapper object).
• Auto-generated file name example:

  EntraProvisioningLogs_API-driven-provisioning-to-on-premises-Active-Directory_20250904_120000.json
  

---

Exit Codes

Code	Meaning
0	Success (includes zero results)
1	Truncated (MaxPages or MaxEntries reached after at least one entry)
2	Failure / error

---

Typical Workflow

1. Run export (choose script, auth mode, and filters).
2. Check $LASTEXITCODE for truncation or failure.
3. Pass JSON file to reporting/analysis tool.

---

Troubleshooting

• Use -Verbose for paging progress, retries, and runtime.
• 403 with Managed Identity or interactive login + “Insufficient privileges” → assign AuditLog.Read.All & grant admin consent.
• Unexpected zero results? Recheck date range (UTC) / identity filters.
• Large Pretty file? Re-run with compact output.
• Network / transient errors: script retries throttling automatically.

---

Documentation Links

• Provisioning list API
• Provisioning object summary

---

License

MIT License

---

Additional Help

For full parameter documentation:

Get-Help .\DownloadEntraProvisioningLogs.ps1 -Full
Get-Help .\DownloadEntraProvisioningLogs-Interactive.ps1 -Full