Automated Microsoft 365 tenant configuration export and migration using Microsoft365DSC. Captures security settings, application configurations, and admin console settings for backup or replication to a new tenant.
Microsoft365DSC is a PowerShell module that exports your entire M365 tenant configuration as infrastructure-as-code (PowerShell DSC). This enables:
- Full tenant backup — snapshot all configuration settings
- Tenant migration — replicate settings to a new tenant
- Drift detection — compare current state against a known baseline
- Documentation — generate HTML/Excel reports of tenant configuration
| Area | Examples |
|---|---|
| Entra ID / Security | Conditional Access policies, MFA settings, Named Locations, Authentication Methods, PIM roles |
| Exchange Online | Transport rules, anti-phish/spam/malware policies, Safe Links, Safe Attachments, mailbox settings |
| SharePoint / OneDrive | Sharing settings, site designs, tenant settings |
| Teams | Meeting policies, calling policies, messaging policies, app permission policies |
| Intune | Device compliance, configuration profiles, app protection policies |
| Purview / Compliance | DLP policies, retention policies, sensitivity labels |
| Defender | Threat policies, alert policies |
| Power Platform | Environment settings, DLP policies |
Microsoft365DSC supports 400+ resource types across these workloads.
- Windows PowerShell 5.1 or PowerShell 7+
- PowerShellGet 2.2.5+
The account or service principal used for export needs the following permissions depending on which workloads you are exporting.
The simplest approach — sign in as a Global Admin or an account with the roles below.
| Workload | Minimum Entra ID Role |
|---|---|
| Entra ID (Conditional Access, Groups, Apps) | Global Reader or Security Reader + Cloud Application Administrator |
| Exchange Online | Global Reader + Exchange Administrator (view-only requires Organization Management role group) |
| SharePoint / OneDrive | SharePoint Administrator |
| Teams | Teams Administrator |
| Intune | Intune Administrator or Endpoint Manager Read-Only role |
| Purview / Compliance | Compliance Administrator or Security Reader |
| Defender for Office 365 | Security Administrator or Security Reader |
| Power Platform | Power Platform Administrator |
Easiest path: A Global Administrator account can export all workloads. For least-privilege, assign the workload-specific roles above.
For automated/unattended exports, register an Entra ID application with the following Microsoft Graph application permissions:
# Core (required for all exports)
Organization.Read.All
Directory.Read.All
# Entra ID / Security
Policy.Read.All
Policy.ReadWrite.ConditionalAccess # Read-only not available; needed for CA export
Application.Read.All
RoleManagement.Read.All
IdentityRiskyUser.Read.All
UserAuthenticationMethod.Read.All
# Exchange Online
Exchange.ManageAsApp # Plus assign Exchange Administrator role to the app
# SharePoint
Sites.FullControl.All
# Teams
TeamSettings.Read.All
TeamsAppInstallation.ReadForUser.All
Channel.ReadBasic.All
# Intune
DeviceManagementConfiguration.Read.All
DeviceManagementApps.Read.All
DeviceManagementManagedDevices.Read.All
DeviceManagementServiceConfig.Read.All
# Compliance / Purview
InformationProtectionPolicy.Read
DelegatedPermissionGrant.Read.All
# Power Platform
(requires PowerApps connector — not covered by Graph permissions alone)
Important: After adding permissions, click Grant admin consent in the Azure portal. Some workloads (Exchange, Security & Compliance) also require assigning an Entra ID admin role to the service principal.
Microsoft365DSC can generate the exact permissions needed for your selected components:
# Show required permissions for specific components
Get-M365DSCCompiledPermissionList -ResourceNameList @(
"AADConditionalAccessPolicy",
"EXOAntiPhishPolicy",
"SPOSharingSettings"
) -PermissionType "Application"# Install the module
Install-Module Microsoft365DSC -Force
# Install all dependent modules (Graph SDK, EXO, PnP, etc.)
Update-M365DSCDependencies
# Verify installation
Get-Module Microsoft365DSC -ListAvailable# Export entire tenant configuration
Export-M365DSCConfiguration -Mode "Full" `
-GenerateInfo $true `
-Path "C:\M365Export\SourceTenant"Export-M365DSCConfiguration -Components @(
"AADConditionalAccessPolicy",
"AADGroup",
"AADApplication",
"AADServicePrincipal",
"EXOMailboxSettings",
"EXOTransportRule",
"EXOAntiPhishPolicy",
"EXOSafeAttachmentPolicy",
"EXOSafeLinksPolicy",
"IntuneDeviceCompliancePolicy",
"IntuneDeviceConfigurationPolicy",
"SCDLPCompliancePolicy",
"SPOSharingSettings",
"TeamsCallingPolicy",
"TeamsMeetingPolicy"
) -Path "C:\M365Export\SourceTenant"Export-M365DSCConfiguration -Mode "Full" `
-ApplicationId "your-app-id" `
-TenantId "your-tenant-id" `
-CertificateThumbprint "your-cert-thumbprint" `
-Path "C:\M365Export\SourceTenant"# HTML report
New-M365DSCReportFromConfiguration `
-Type HTML `
-ConfigurationPath "C:\M365Export\SourceTenant\M365TenantConfig.ps1" `
-OutputPath "C:\M365Export\SourceTenant\Report.html"
# Excel report
New-M365DSCReportFromConfiguration `
-Type Excel `
-ConfigurationPath "C:\M365Export\SourceTenant\M365TenantConfig.ps1" `
-OutputPath "C:\M365Export\SourceTenant\Report.xlsx"1. EXPORT from source tenant
└── Export-M365DSCConfiguration -Mode "Full"
2. REVIEW the exported configuration
└── New-M365DSCReportFromConfiguration -Type HTML
3. EDIT the config file
└── Update tenant ID, domain names, user/group references
4. VALIDATE before applying
└── Assert-M365DSCConfiguration (drift check)
5. APPLY to destination tenant
└── Start-DscConfiguration -Path "..." -Wait -Verbose
The exported .ps1 file will contain source-tenant-specific values that must be updated:
| Find | Replace With |
|---|---|
| Source Tenant ID | Destination Tenant ID |
Source domain (e.g., contoso.onmicrosoft.com) |
Destination domain |
| User ObjectIDs / UPNs | Corresponding users in destination tenant |
| Group ObjectIDs | Corresponding groups in destination tenant |
| App Registration IDs | New app registrations in destination tenant |
Compare your current tenant state against an exported baseline:
# Check for configuration drift
Assert-M365DSCConfiguration `
-ConfigurationPath "C:\M365Export\Baseline\M365TenantConfig.ps1"-
Credentials and secrets — App registration secrets, certificates, and service principal keys are not exported. Recreate these manually in the destination tenant.
-
User and group references — Policies referencing specific users or groups need remapping to the new tenant's object IDs.
-
License requirements — The destination tenant must have the same license SKUs (E3, E5, P1, P2, etc.) for the settings to apply successfully.
-
Data is not migrated — This tool handles configuration only, not mailbox data, files, or audit logs. For data migration, use tools like ShareGate, BitTitan, or Microsoft's native migration tools.
-
Test first — Always run
Assert-M365DSCConfigurationagainst the destination before applying changes. -
Some resources are read-only — A small number of M365 settings can be exported but not imported (e.g., certain audit configurations). Check the Microsoft365DSC resource documentation for details.
| Tool | Purpose |
|---|---|
Maester (Install-Module Maester) |
Security benchmark testing against CIS and Microsoft baselines |
| Microsoft Graph PowerShell SDK | Direct Graph API access for anything M365DSC doesn't cover |
| ShareGate / BitTitan | Data migration (mailboxes, files, sites) |
- Microsoft365DSC.com — Official documentation
- Microsoft365DSC GitHub — Source code and issues
- Resource List — Full list of 400+ exportable resource types
- Export Generator — Web-based tool to select components and generate export scripts
This project is licensed under the MIT License.