Configuration assessment
This page describes methods used to assess configuration drift in a Microsoft 365 service.
Estimated reading time: 4 minutes
Instruction
Implementation of the Blueprint, including automated assessment, will differ depending on an organisation’s operating context and culture. Organisations should implement the Blueprint in alignment with their existing change management, business processes and frameworks.
When using automated configuration files, organisations should note they will configure the relevant settings in a Microsoft 365 tenancy exactly as outlined in the Configuration pages of the Blueprint. Organisations should ensure they customise configuration of their Microsoft 365 services in accordance with their own design decisions and requirements, deviating from the Blueprint configurations where appropriate.
Overview
Microsoft 365 Desired State Configuration (M365DSC) is a configuration-as-code tool developed by Microsoft to automate the configuration of Microsoft 365 services. M365DSC can also be used to undertake automated assessment of an M365 configuration in order to complement manual and other automated assessment tools.
Manual assessment of configurations should be the primary assessment method, or it should be used in conjunction with an automated tool to address any gaps in tool coverage and for validating assessment tool reports.
When comparing your targeted M365 service against the guidance in the Blueprint’s configuration pages, consideration should be given to the reasons behind any deviations, and if the deviations are appropriate in the current context.
The mechanism described below will automatically assess approximately half of the Blueprint configurations, the remainder will require manual assessment.
Automated Microsoft 365 Desired State Configuration Assessment
M365DSC performs an assessment by comparing an M365 service’s configuration to a DSC Blueprint. A DSC Blueprint is a file with a .ps1 extension that includes a set of configuration / a configuration profile. By using the DSC files published in the Blueprint as the DSC Blueprint files, a user can perform an assessment of the configuration of an M365 service against the Blueprint.
While these DSC Blueprints can be extended to include complementary metadata to contextualise an assessment report (rather than linking directly to the relevant Blueprint Design Decision), this is not currently in scope.
1. Complete the prerequisite tasks
- A Windows host and specific credentials are required to use DSC, instructions on setting these up are in the DSC setup page.
2. Copy the DSC files
- On the Windows host used for assessment, copy the DSC file for the targeted M365 service to your working folder and rename it to have a .M365 extension. The DSC file is a .ps1 file and can be found on each services page below:
| Service | Automated assessment mechanism | Automated assessment coverage |
|---|---|---|
| Entra ID | - Desired State Configuration | Partial |
| Microsoft 365 | - N/A | None |
| Microsoft Intune | - Desired State Configuration | Partial |
| Microsoft Defender | - Desired State Configuration | Partial |
| Microsoft Purview | - Desired State Configuration | Partial |
| Exchange Online | - Desired State Configuration | Partial |
| SharePoint Online | - Desired State Configuration | Partial |
| Microsoft Teams | - Desired State Configuration | Full |
| Power Platform | - N/A | None |
DSC instructions
Additional instructions for using DSC are provided in the above-linked pages.
3. Assess the configuration
- Authenticate to your Entra ID tenant with an account with permissions to read the target M365 service’s configurations:
$creds = Get-Credential
- Execute the following command to assess the configuration, substituting the full file and folder paths:
Assert-M365DSCBlueprint -BluePrintUrl <path to .M365 file> -OutputReportPath <path to HTML folder> -Credentials $creds
This will generate a HTML report comparing the targeted M365 service’s configuration to the DSC Blueprint file.
3a. Assess the configuration - alternative
It is also possible to execute the Assert-M365DSCBlueprint command using the credentials created during the DSC setup process. This can be useful if a less-interactive execution of an assessment is required, or when delegating execution of an assessment to another user.
With additional arguments, the parameters used in the configuration data file can replace the -Credentials $creds part of the command:
- substitute
<organisation.onmicrosoft.com>for the primary domain name of the tenant to assess - substitute
<GUID>for the application ID of the service principal used for assessment - substitute
<thumbprint hash>for the thumbprint of the certificate used to authenticate the service principal
Assert-M365DSCBlueprint -BluePrintUrl <path to .M365 file> -OutputReportPath <path to HTML folder> -TenantId <organisation.onmicrosoft.com> -ApplicationId <GUID> -CertificateThumbprint <thumbprint hash>
4. Manually assess configurations and evaluate deviations
- Verify the M365 service’s configurations against the Blueprint’s configuration pages, noting where the generated HTML provides assessment coverage.
- Evaluate configuration deviations and modify as required.
Related information
Configuration
- Entra ID
- Microsoft Intune
- Microsoft Defender
- Microsoft Purview
- Exchange Online
- SharePoint Online
- Microsoft Teams