Managing a single Microsoft 365 tenant is challenging. Managing multiple tenants, or keeping Development, Testing, and Production tenants perfectly synced, is a nightmare without automation.
Over time, administrators make ad-hoc changes through the M365 Admin Center—adjusting sharing settings, tweaking Teams policies, or changing SharePoint storage limits. This leads to Configuration Drift, where the actual state of your tenant no longer matches your documented baseline.
Enter Microsoft365DSC. Microsoft365DSC is an open-source Configuration-as-Code framework for Microsoft 365 built on top of PowerShell Desired State Configuration (DSC). It allows you to export existing configurations, track baselines, detect drift, and integrate tenant management into a CI/CD pipeline.
Recommended Prerequisites
Before starting, ensure your environment meets the core requirements for Microsoft365DSC:
- Windows PowerShell 5.1
- Microsoft365DSC module installed
- Microsoft Graph PowerShell SDK installed
- An Entra ID App Registration configured for Certificate authentication
- Appropriate admin roles (e.g., Global Reader for exporting, or specific workload admins like SharePoint Administrator for applying settings)
1. Installing Microsoft365DSC
To install the framework, open Windows PowerShell 5.1 as an Administrator:
# Install the Microsoft365DSC module
Install-Module Microsoft365DSC -Force
# Update the module and its dependencies to the latest version
Update-M365DSCModule
2. Extracting Existing Configuration (Reverse Engineering)
One of the most powerful features of Microsoft365DSC is the ability to reverse-engineer your current tenant. If you aren’t sure where to start with Configuration as Code, export your existing settings first to establish a baseline.
# Export SharePoint and Teams configurations
Export-M365DSCConfiguration `
-Components @("SPOSite", "TeamsCallingPolicy") `
-TenantId "contoso.onmicrosoft.com" `
-ApplicationId "Your-Entra-App-Id" `
-CertificateThumbprint "Your-Cert-Thumbprint" `
-Path "C:\DSC\TenantConfig"
Note on Permissions: Exporting a full tenant configuration may require granting hundreds of Microsoft Graph, Exchange Online, SharePoint Online, and Teams permissions to your App Registration. Start with a limited workload export before attempting a full tenant snapshot.
3. Detecting Configuration Drift
Once you have a baseline configuration exported, Microsoft365DSC excels at monitoring your tenant for unauthorized changes. You can run compliance checks to detect and report on configuration drift without actually altering the environment.
# Test the current tenant state against your baseline
Test-M365DSCConfiguration -ReferenceConfigurationPath "C:\DSC\TenantConfig\TenantConfig.ps1"
This generates a drift report, alerting administrators to any settings that have deviated from the approved baseline.
4. Comparing Development and Production Tenants
For organizations with multiple environments, validating promotions from Development to Production is critical. Microsoft365DSC can generate detailed HTML or Excel reports that compare two tenant configurations side-by-side, highlighting the exact differences in policies, making pre-deployment validation much simpler.
5. Defining and Remediating the Desired State
A DSC configuration script defines exactly how a workload should be configured. Here is an example defining a SharePoint Online tenant-level sharing policy:
Configuration M365TenantBaseline {
Import-DscResource -ModuleName Microsoft365DSC
Node localhost {
SPOTenant SharePointSharingPolicy {
IsSingleInstance = 'Yes'
SharingCapability = 'ExistingExternalUserSharingOnly'
ApplicationId = "Your-Entra-App-Id"
TenantId = "contoso.onmicrosoft.com"
CertificateThumbprint = "Your-Cert-Thumbprint"
}
}
}
# Compile the configuration into a MOF (Managed Object Format) file
M365TenantBaseline -OutputPath "C:\DSC\Compiled"
After compiling your script into a .mof file, use the standard PowerShell DSC engine to apply it:
# Apply the configuration to remediate drift
Start-DscConfiguration -Path "C:\DSC\Compiled" -Wait -Verbose -Force
If the configuration does not match the defined state, DSC will remediate the setting and bring it back into compliance during the deployment cycle.
6. Configuration as Code via Azure DevOps and GitHub Actions
The ultimate goal of Microsoft365DSC is to integrate it with CI/CD platforms like Azure DevOps or GitHub Actions.
By storing your .ps1 configuration files in a Git repository, any changes to M365 policies must be proposed via a Pull Request (PR). Once approved, your pipeline automatically compiles the MOF file and deploys it to your tenant. This guarantees that all tenant modifications are peer-reviewed, documented, and fully automated.
Future Consideration: Microsoft Graph Configuration APIs
As of January 2026, Microsoft introduced the Tenant Configuration Management APIs in Microsoft Graph Public Preview. Organizations adopting Microsoft365DSC today should closely monitor the evolution of these native Graph APIs, as they will likely become a strategic, first-party alternative for configuration governance and drift management in the future.
Proactive Tip: Clean Your Tenant Before Applying Baselines
When you use DSC to lock down role assignments, admin groups, and M365 structures, you assume your current directory is clean. However, legacy environments are often littered with disabled accounts still assigned to admin roles, or orphaned users clinging to SharePoint Site Collections.
Before implementing a strict DSC baseline, use SPClean to audit and sanitize your environment. SPClean helps you identify orphaned users, clear out dead administrative assignments, and ensure your tenant is pristine. Applying Microsoft365DSC on top of a clean tenant prevents unexpected deployment errors and solidifies your security posture.
Conclusion
Microsoft365DSC helps organizations standardize Microsoft 365 administration through Configuration as Code, enabling repeatable deployments, tenant comparisons, drift detection, and governance automation across environments. By establishing baselines and remediating drift, you can transform reactive M365 management into a secure, predictable engineering process.
