How to use Microsoft 365 DSC to avoid configuration drift (original) (raw)

Desired State Configuration on the Microsoft 365 tenant is one way to enlist the advantage of automation to keep the platform running reliably.

For admins who are new to PowerShell and Microsoft 365, there is a learning curve to understand how to use Microsoft 365 Desired State Configuration (DSC), but knowing your tenant's current state regularly via automation is a huge benefit. This tool is ideal for jobs related to configuring, cloning, monitoring and reporting on your Microsoft 365 tenant and particularly helpful for admins who work with multiple Microsoft 365 tenants.

Why configuration as code with Microsoft 365 DSC is necessary

With the rapid adoption of cloud-based services such as Microsoft 365, it is essential to have a system in place for managing and securing services.

The configuration-as-code concept consists of writing scripts that define the desired configuration state of a platform's environment and using automation tools to apply and enforce that configuration state. With Microsoft 365 DSC, administrators manage and enforce configuration settings using this configuration-as-code approach. This feature is built on the PowerShell DSC framework and also covers the individual workloads on Microsoft 365, including Microsoft Teams, Exchange Online and services in Security and Compliance.

With Microsoft 365 DSC, administrators define configuration settings to enforce across the Microsoft 365 environment and use automation tools to apply and enforce those settings. With Microsoft 365 DSC's declarative approach, administrators automate repetitive tasks, reduce manual errors and improve efficiency to manage Microsoft's cloud collaboration configuration settings.

Automation is essential to reduce errors, increase efficiency and free up valuable time for IT staff to focus on more critical tasks. With Microsoft 365 DSC, administrators can continually monitor the state of their Microsoft 365 environment. Microsoft 365 DSC checks for configuration drift and can alert administrators when settings change, enabling them to act immediately. This proactive approach can head off issues before they cause problems, reducing the risk of downtime and data loss.

Microsoft 365 DSC also simplifies deployment by providing a consistent way to configure Microsoft 365 services across multiple tenants, deploy new tenants or update existing ones. Microsoft 365 DSC automates repetitive tasks, such as creating new users, setting up mailboxes and configuring SharePoint sites to maximize efficiency and consistency.

How to install Microsoft 365 DSC

Before setting up Microsoft 365 DSC, administrators must meet the following prerequisites:

PowerShell version 5.1 or later.
Microsoft Exchange Online Remote PowerShell Module.
Microsoft Graph PowerShell SDK.
Teams PowerShell Module.
Microsoft PowerApps PowerShell Module.
PnP PowerShell Module.

Microsoft 365 supports two types of authentication: user credential and service principal. User credentials are login credentials specific to the user. Service principal authentication involves specifying parameters such as a Microsoft Entra ID -- formerly Azure Active Directory -- application ID, tenant ID, and a secret or certificate. However, each Microsoft 365 workload can only support a specific combination of authentication methods due to the dependencies of the underlying modules. Each workload might require a different authentication method, and administrators need to know these requirements when configuring authentication for their Microsoft 365 environment.

Service principal authentication provides granular access control and is more secure than user credentials. Microsoft recommends using service principal authentication whenever possible for Microsoft 365 because it offers high security and avoids the risk of sending highly privileged credentials over the network for authentication. Additionally, since Microsoft 365 DSC is an unattended process, using multifactor authentication for user credentials is not supported.

How to install Microsoft 365 DSC

Once the prerequisites are in place, you can set up Microsoft 365 DSC.

Microsoft maintains the Microsoft 365 DSC source code within GitHub and pushes releases to the PowerShell Gallery. To install the Microsoft365DSC PowerShell module, run the same install and import commands used for all PowerShell modules.

Install-Module Microsoft365DSC -Force
Import-Module Microsoft365DSC

To check the module's status, execute the following command:

Get-Command -Module Microsoft365DSC

Microsoft 365 DSC PowerShell module installation.

Use the Module parameter to see the commands in the Microsoft 365 DSC PowerShell module to verify it installed properly.

The next step is to connect to a Microsoft 365 tenant. The most straightforward approach is to use the Get-Credential method, although it does not support second-factor authentication. For example, when retrieving a current configuration, you can use these commands:

$creds = Get-Credential
Export-M365DSCConfiguration -Credential $creds

Use the Get-Credential command to connect to the Microsoft 365 tenant.

The export process writes an error log for review, then outputs the PowerShell data file and script for the retrieved configuration.

How to set up Microsoft 365 DSC securely

Microsoft 365 DSC supports multiple authentication methods, depending on the service used. Most services support credentials, service principals and managed identities. With a service principal, you get support for certificate thumbprints, certificate paths and application secrets.

If you want to connect using a service principal and then check the basic Microsoft 365 settings, then you must first create it within Microsoft Entra ID, formerly Azure Active Directory, assign the required permissions, then use the values for it within the PowerShell code.

Service principal setup screen.

Create the service principal with the permissions needed to work with Microsoft 365.

$appId = Read-Host -Prompt '<App Id>'
$appSecret = Read-Host -Prompt '<App Secret>'
$tenantId = Read-Host -Prompt '<Tenant Id>'

Export-M365DSCConfiguration `
-Components @(
"O365AdminAuditLogConfig",
        "O365OrgCustomizationSetting",
        "O365OrgSettings") `
    -ApplicationId $appId `
    -ApplicationSecret $appSecret `
    -TenantId $tenantId

How to manage tenant configurations with Microsoft 365 DSC

Most admins use Microsoft 365 DSC to take a snapshot of their Microsoft 365 tenant. The DSC web UI generates the PowerShell commands and the PowerShell scripts for this task. You can either directly browse to the export.microsoft365dsc.com URL or execute the following PowerShell command:

Export-M365DSCConfiguration -LaunchWebUI

Web-based user interface.

The LaunchWebUI parameter opens the web-based user interface in a browser.

Use the web UI to select the service and the configuration items to check. For example, you can manually select the items if you choose None from the Selection mode dropdown.

You can also pick the authentication option. Lastly, select the required items and click the Generate button to display the PowerShell code.

Interface to select services and configuration items.

Select the services and other items to manage from the web GUI.

Click Copy to clipboard from the PowerShell page to use this.

# Getting application information for Application + Secret authentication
$ApplicationId = Read-Host -Prompt 'Application Id.'
$ApplicationSecret = Read-Host -Prompt 'Application Secret.'
$TenantId = Read-Host -Prompt 'Tenant Id.'

# Exporting resources using an application
Export-M365DSCConfiguration `
-Components @(
"SPOAccessControlSettings",
"SPOSharingSettings",
"SPOSite",
"SPOUserProfileProperty") `
-ApplicationId $ApplicationId `
-ApplicationSecret $ApplicationSecret `
-TenantId $TenantId

Export the configuration to see the current state of the Microsoft 365 tenant. From here, you can move into more advanced features, such as deploying custom configurations and tracking changes.

Microsoft 365 DSC creates reports in several formats, such as Excel, HTML and JSON. Executing the New-M365DSCReportFromConfiguration command uses exported results to create the report in the desired format.

New-M365DSCReportFromConfiguration `
-Type 'JSON' `
-ConfigurationPath 'C:\Code\DSC\M365TenantConfig.ps1' `
-OutputPath 'C:\Code\DSC\Microsoft_365_Report.json'

New-M365DSCReportFromConfiguration `
-Type 'HTML' `
-ConfigurationPath 'C:\Code\DSC\M365TenantConfig.ps1' `
-OutputPath 'C:\Code\DSC\Microsoft_365_Report.html'

New-M365DSCReportFromConfiguration `
-Type 'Excel' `
-ConfigurationPath 'C:\Code\DSC\M365TenantConfig.ps1' `
-OutputPath 'C:\Code\DSC\Microsoft_365_Report.xlsx'

Aside from the reporting on the current state, you can take snapshots of the configuration for different purposes, such as a comparison to check for changes.

New-M365DSCDeltaReport `
-Source 'C:\Code\DSC\M365TenantConfig_INITIAL.ps1' `
-Destination 'C:\Code\DSC\M365TenantConfig_UPDATED.ps1' `
-OutputPath 'C:\Code\DSC\Microsoft_365_DELTA_Report.html'

If you add the parameter -DriftOnly $true the report will only output to the deviations.

You can deploy a configuration you define, then utilize the local engine for DSC for automatic monitoring of changes from the original configuration. The following link provides more information about how to create and deploy configurations in Microsoft 365.

Liam Cleary runs his own consulting company that helps customers work with Microsoft 365 and Azure-based technologies. He specializes in internal and external collaboration, document and records management, business process automation and implementing security measures.