Take a snapshot of your Microsoft 365 tenant configuration
As a vast platform, Microsoft 365 can be challenging to implement for engineering change management. The number of configuration options available is staggering, not to mention settings that impact multiple applications. For example, SharePoint’s configuration impacts Teams’ functionality. It’s also made worse by the fact that there’s no true configuration-level backup service for Microsoft 365.
Therefore, it can be difficult to test changes to any configuration item in Microsoft 365. Alerts like Microsoft Defender for Office 365’s Configuration Analyzer can help detect configuration changes. However, this doesn’t extend to the rest of the platform.
Microsoft 365 Desired State Configuration
To address the lack of an effective “snapshot” of Microsoft 365 configuration, however, there is a solution. Many organizations have turned to Configuration as Code. The basic principle is that the Desired State Configuration (DSC) of the configuration is a script. This ensures that we can restore the configuration to an agreed-upon baseline by re-running the script in the environment. DSC is not a new concept and has been useful in many other technologies over the years. However, Microsoft 365 DSC builds on DSC to help solve the tenant configuration challenge.
Microsoft 365 DSC is an open source project, led by Microsoft and driven by the community. It allows you to compare configuration within a Microsoft 365 tenant or even across multiple tenants. In this article, I’ll detail how it can be used to “snapshot” your tenant’s configuration. We’ll then compare this snapshot to an updated configuration to detect changes in the environment.
Prepare an Azure AD application
To securely authenticate to resources, you’ll need to register a new Azure AD application. While the module allows for direct user credentials, this can be tricky. That’s why all components in the DSC module are updated to leverage the Microsoft Graph PowerShell SDK.
Create a new Azure AD application record and note the tenant ID, client IP, and client secret. In production, I recommend using certificate authentication, but client secret works well for testing.
Next, to grant permissions to the application, check the documentation for the associated resources you want to include. For example, I’ll add the application permissions for conditional access – “AADConditionalAccessPolicy.” Remember to grant consent to the permissions once they’re added. For export, you only need the permissions listed under “Export.” If you want to automate remediation, you’ll need the permissions listed under “Automate.”
For larger resource sets, the DSC module contains the Get-M365DSCCompiledPermissionList cmdlet. We can pass a list of resources to the cmdlet, which returns the required permissions:
| 1 | Get-M365DSCCompiledPermissionList -ResourceNameList @(‘AADConditionalAccessPolicy’) |
Install the Microsoft 365DSC module
Microsoft 365 DSC comes as a simple PowerShell module. To get started, open a PowerShell session and run the command:
| 1 | Install-Module -Name Microsoft365DSC |
This can take some time, as it will require downloading a large number of dependencies to enable the DSC module to operate.
Extract a configuration
To extract a configuration, run the Export-M365DSCConfiguration cmdlet. Specify the resources you want to extract, along with the application details, as shown below.
Export-M365DSCConfiguration -Components @(<Component List>) -ApplicationId <AppID> -TenantId <TenantName> -ApplicationSecret <AppSecret> -Path <Path for Export> -ConfigurationName <Configuration Name> -FileName <Name of export file .ps1>
This will export the configuration to the specified path as a DSC configuration .PS1 file. Inside the file, you’ll see the exported configuration details for the specified resources. In this case, it’s Conditional Access policies, but there are many more options available. You can even use the web-based export tool. This will generate your export command, selecting the resources and applications you want to include.
Create a configuration report
The PS1 configuration file exported by DSC is not a very user-friendly way to examine the tenant configuration. The configuration can be exported to Excel or HTML using the New-M365DSCReportFromConfiguration cmdlet.
The exported configuration will be in a much easier-to-read format.
Compare configurations
Reporting is great. But the exported configuration can also be compared to the current configuration to identify any changes since the initial export. To generate a comparison, make a few changes and then run the export again under a different file name. This will generate another file with the latest configuration in the same folder.
The files can then be compared by running the New-M365DSCDeltaReport cmdlet. Specify the source (Initial), destination (Updated) configurations, and an output path for the resulting HTML file. The command syntax is shown below:
| 1 | New-M365DSCDeltaReport -Source ‘C:\DSC\UpdatedConfig.ps1’ -Destination ‘C:\DSC\InitialConfig.ps1’ -OutputPath ‘C:\dsc\Delta.html’ |
The command generates the HTML delta report shown in Figure 5. This report highlights any missing, additional, or different components detected during the comparison.
In this example, the delta report shows that the “Teams via MCAS” conditional access policy is no longer present and the “IncludeApplications” setting of the “MFA” policy has been changed from “All” to a single application.
More than just a comparison
Reporting and comparison are just the beginning of what Microsoft 365 DSC can do. The real value lies in extending this concept to include regular consistency checks and even automatic remediation of configuration drift. DSC can also be useful for cloning tenancies for testing purposes. It can even be deployed in containers, Azure Automation, and Azure DevOps to improve configuration governance, deployment, and updating. For more information about Microsoft 365 DSC, visit the project website here.
