Use Desired State Configuration to Snapshot the Configuration of Your Microsoft 365 Tenant

As a broad and deep platform, Microsoft 365 can be challenging to enforce appropriate technical change management on. The sheer number of configuration options available is staggering when you take into account each workload on offer, not to mention settings that impact across multiple workloads like SharePoint configuration impacting Teams functionality. This isn’t helped by the fact that a true configuration level backup service for Microsoft 365 doesn’t exist.

As a result, making changes to any configuration item in Microsoft 365 can be very difficult to test and quite onerous to track and revert. Alerting can be configured for certain changes and some aspects like the Microsoft Defender for Office 365 Configuration Analyzer can help detect configuration skew over time but this doesn’t extend to the rest of the platform.

Microsoft 365 Desired State Configuration

To fill the gap of an effective “snapshot” of Microsoft 365 configuration, a lot of organizations have turned to configuration as code. The basic principle here is that the desired state configuration (DSC) of the tenancy is scripted to ensure that it can be reverted to an agreed baseline by rerunning the script against the environment. DSC isn’t a new concept and has been used in many other technologies throughout the years, however Microsoft 365 DSC leverages DSC to help solve the tenancy configuration challenge.

Microsoft 365 DSC is an open source, Microsoft lead, community driven project which allows for extraction, comparison and even remediation of configuration within a Microsoft 365 tenancy or even across multiple tenancies. In this article, I’ll detail how it can be used to “snapshot” your tenancy configuration and then compare this snapshot against and updated configuration to detect changes in the environment.

Prepare an Azure AD App

To secure authentication to resources, you will need register a new Azure AD app. While the module does allow passing user credentials directly, this can be tricky in secure environments, so all components of the DSC module are being upgraded to leverage the Microsoft Graph PowerS hell SDK module under the hood.

Create a new Azure AD app registration (as I did in this article) and take note of the Tenant ID, Client IP and Client Secret (for production use I recommend using Certificate authentication but Client Secret works fine for testing).

Next, to grant permissions to the app, check the documentation for the associated resources you would like to include. For example, I’ll add the application permissions for Conditional Access – “AADConditionalAccessPolicy” (Figure 1), don’t forget to grant consent on the permissions once they are added. For export, you only need the permissions listed under “Export”, if you want to automate remediation (which I won’t go into here) then you will need the permissions listed under “Automate.”

For larger sets of resources, the DSC module which is detailed below contains the cmdlet Get-M365DSCCompiledPermissionList which can be passed a list of resources and returns the required permissions:

Get-M365DSCCompiledPermissionList -ResourceNameList @('AADConditionalAccessPolicy')  

Install the Microsoft 365DSC module

Microsoft 365 DSC comes in the form of a simple PowerShell module. To get started, open up a PowerShell session and run the command:

Install-Module -Name Microsoft365DSC

This might take a little while as it will need to download a lot of dependencies to allow the DSC module to do its job.

Extract a Configuration

To extract a configuration, run the Export-M365DSCConfiguration cmdlet, passing in the resources you want to extract, along with the app details as shown in Figure 2.

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. In the file you will see the details of the exported configuration for the specified resources, in this case, Conditional Access policies however there are a lot more options available. You can even use the web-based export tool to generate your export command for you, selecting the resources and workloads you want to include.

Create a configuration report

The PS1 Configuration file exported by DSC isn’t a very user friendly way of reviewing the tenant config. The configuration can be exported to Excel or HTML format by using the New-M365DSCReportFromConfiguration cmdlet (Figure 3).

The exported configuration will be exported in a much easier to read format (Figure 4).

Compare configurations

Reporting is great but the exported configuration can also be compared to the current configuration to identify any changes since the original export. To generate a comparison, make some changes to Conditional Access and then run the export again specifying 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, specifying the source (Initial), destination (Updated) configurations and an output path for the resulting HTML file. The syntax of the command is shown below:

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 in the comparison.

In this example, the delta report shows that the Conditional Access Policy “Teams via MCAS” is no longer present and the “IncludeApplications” setting on the policy “MFA” has been modified from “All” to a single application.

More than just comparison

Reporting and comparison are only the beginning of the possibilities with Microsoft 365 DSC. The real value comes by expanding on this concept out to have regular consistency checks and even automated remediation of configuration drift. DSC can also be useful for cloning tenancies for testing. It can even be deployed to containers, Azure Automation and Azure DevOps to enhance the governance, deployment, and update of configurations. For more information on Microsoft 365 DSC, check out the project website here.