top of page
Writer's pictureWill Francillette

M365DSC: Getting Started Part 1- Desired State Configuration

Updated: Mar 7




Microsoft 365 DSC


It's time to start a new series of blog on a project I am a complete fan:

Microsoft 365 DSC


It is a combination of Microsoft 365, PowerShell , and Desired State Configuration (DSC) DSC is a management platform that enables the management of resources with configuration as code. A team from Microsoft lead by Nik Charlebois has developed and adapted this technology to manage initially Office 365 collaborative platform(SharePoint, Teams and Exchange) and have expended it across other workloads taking advantage of the Graph API and other PowerShell modules. The solution covers policies across:

  • Azure AD

  • Exchange Online

  • Intune

  • Office 365

  • OneDrive

  • Power Apps

  • Planner

  • Security & Compliance Center

  • SharePoint Online

  • Teams

It allows you to export your policies, monitor configuration drifts, generate reports, compare configurations and much more. It can be fully integrated to your DevOps processes.

M365DSC features

It is Opensource, developed and maintained by Microsoft and the community. First stop is the official website, GitHub repository and YouTube channel:

Before digging more into the solution, I want to focus this blog on DSC and the structure of the solution. This first blog will be an introduction to DSC.


The concept

DSC is a declarative platform used for configuration, deployment and management of systems. It can be used on-premises in traditional Windows infrastructure but also in the cloud with Azure automation and Linux. It consists of 3 components:

  1. The configuration: This is the settings you are monitoring or enforcing - the desired state

  2. The resource: This is the code and logic that monitor configuration drifts and keep the system in the desired state

  3. The Local Configuration Manager (LCM): This is the engine running the solution.

The configuration

The DSC configuration is a PowerShell script using special type of functions and keywords:

  1. Configuration: This is the declaration of the DSC object

  2. Node: This is your engine declaration - For M365DSC we use localhost

  3. Resource: This is your properties values per type of resource - in the screenshot below the resource type is WindowsFeature

DSC resource

Or here an example specific to M365DSC and the AADUser resource

m365dsc resource

Each resource block must include the Ensure parameter and accept 2 values:

  • "Present": means that the resource and its settings must be found in the desired state in the environment. The LCM will monitor this feature and if configured will create or update the resource.

  • "Absent": means that the resource should not be present and that the LCM should remove any instances found.

If you don't specify the Ensure parameter, the default value is "Present"


The resource

The DSC resource provides the building block to retrieve, test and update a resource. There are built-in resources part of the PSDesiredSateConfiguration module

dsc cmdlets

Other DSC modules are available from PowerShellGet and other provider, and finally you can develop custom resources. As of today, M365DSC has reached a milestone with more than 200 resources available and the coverage is always expending! A resource is a PowerShell script that defines 3 functions Get-TargetResource, Test-TargetResource and Set-TargetResource.

1- Get-TargetResource: This is where you retrieve your resource/policy and format it as required. 2- Test-TargetResource: This is where you test your configuration file against your reference - In case of M365DSC this reference is the policy in your M365 tenant. 3- Set-TargetResource: This is where you define the code to create, update or remove a resource.


In M365DSC, an additional method is exposed called Export-TargetResource. This is the method allowing you to extract the resource from your tenant using the Reverse DSC proxy. Each resource has a schema that determines the syntax needed to use the resource in a Configuration. This schema is a declarative of all parameters, their types, possible values, permissions (key, read, write) and some description.

m365dsc schema file

Finally you compile a Managed Object Format (mof) file from the combination of the configuration and the schema files and will be used by the LCM to enforce or monitor desired state. To compile your mof file you will execute your configuration file.

The Local Configuration Manager (LCM)

It can be any Windows Server or container running preferably PowerShell v5 and later (some down-level support available for v4.0). The LCM is configured using Set-DscLocalConfigurationManager and to retrieve the current configuration use Get-DscLocalConfigurationManager

LCM configuration

We want to focus on a few parameters here:

  • ConfigurationModeFequencyMins: The interval of time the engine check for configuration drifts

  • ConfigurationMode: This setting specifies if the engine should monitor settings and/or autocorrect configuration drifts. Possible values are:

    • ApplyOnly: The engine will apply the configuration once only during initial setup

    • ApplyAndMonitor: The engine will apply the configuration during initial setup and then audit any drift.

    • ApplyAndAutoCorrect: The engine will apply the configuration during initial setup and then enforce the desired state configuration if any drift is detected

  • RefreshMode:

    • Push: The engine pushes configuration to remote nodes - In the case of M365DSC the remote node is localhost which pushes the config to the M365 tenant

    • Pull: Each node pull the configuration from the pull server.

DSC is highly dependent on WMI and CIM instances so make sure your Windows Management Service is running and that you don't have your ASR rule blocking WMI commands. To start the engine and apply the initial setup, run:

Start-DscConfiguration -Wait -Verbose -Force -Path .\MyConfiguration

With MyConfiguration the name of the Configuration block in the Configuration file 🤩

resource name

You can stop the engine using

Stop-DSCConfiguration

Reference

That's a wrap for this blog, next time we will look into installing and getting started with M365DSC. Happy PowerShelling!

4,752 views0 comments

Comments


bottom of page