Home Getting Started Wiki Contribute Releases YouTube Resources

Getting Started

This document will help you get started with the Microsoft365DSC project. For any questions regarding how to use the project, please fill out an item in the Issues section of the official repository.

How to Install

Open a PowerShell console (run as Administrator) from any machine. Microsoft365DSC requires that the machine be running at least PowerShell version 4.0+, but we stronly recommend having PowerShell 5.1. In the PowerShell console, run the following command to install the module:
    Install-Module Microsoft365DSC -Force -AllowClobber

When this is run, PowerShell is pinging the PowerShell gallery, getting the Microsoft365DSC module and will then download and install it locally on the machine. It will download the required components such as the SharePoint PNP module, Azure Active Directory module, the Exchange Online Management Shell, as well as other dependent modules.

Once this is done the module can be used by closing the current PowerShell console and re-opening a new one or by importing the module into the current PowerShell Session by running the following command:

    Import-Module Microsoft365DSC -Force
Importing the Microsoft365DSC module

Note: It is important that the machine that executes the configuration has internet connectivity back to the Microsoft 365 tenant you are trying to configure or extract the configuration from.

Using the Dev Branch from GitHub

Official releases of the Microsoft365DSC module are published to the PowerShell Gallery every 6 weeks. However, bug fixes and improvements are commited to the official code base on a daily basis on our GitHub repository. It is our recommendation that you try using the latest code base as much as possible. To make it easier for you to acquire the latest version of the modules from GitHub, we've included the following cmdlet as part of the tool:


By running the above cmdlet, you will automatically download the bits from the GitHub Dev branch, and all the associated dependencies. If you are trying to configure a brand new machine that never had Microsoft365DSC installed on it before, and wish to use the Dev branch, simply run the following two lines of PowerShell in order:

    Install-Module Microsoft365DSC -Force

Note: You may be getting errors when running the Install-M365DSCDevBranch cmdlet right after installing the module. In this case, simply run the Install-Module command first, close the PowerShell session, re-open a new one as an administrator and then run the Install-M365DSCDevBranch command.

Write your First Microsoft365DSC Configuration

With Microsoft365DSC, you write your configuration for an Microsoft 365 tenant just like you'd be writing any other DSC configuration. If you don't feel comfortable writing your configuration from scratch, we recommend starting by extracting the configuration from an existing tenant and using this as a baseline to modify/add your own set of configuration. Please refer to the Extracting Configuration from an Existing Microsoft 365 Tenant for more information.

A Microsoft365DSC configuration is a PowerShell script (.ps1) file that defines a Configuration object. Most Microsoft365DSC configuration should be run on the current machine (localhost) and will have a structure similar to the following:

    Configuration NameOfTheConfiguration
        Import-DSCResource -ModuleName Microsoft365DSC
        $GlobalAdminAccount = Get-Credential
        Node localhost
            <Insert Configuration Here>

The last line of the above code simply calls into the Configuration Object as if it was a function. This will initiate a compilation operation on the current configuration. If you decide to name your configuration something other than "NameOfTheConfiguration" you will need to update that line accordingly as well.

Now that we have the skeleton for our configuration, we need to start populating it with configuration blocks we call DSC Resources Blocks. In the Microsoft365DSC taxonomy, a resource is a component of a workload that can be configured. For example, SPOSite is the resource to configure a SharePoint Online site collection, SCDLPComplianceRule is the resource to configure a Security and Compliance Center Data Loss Prevention (DLP) Rule, etc. Each one of these resources further defines properties that they can manage. In the case of the SPOSite resource for example, properties such as the URL, Title, Storage Quota, etc. acan all be managed by the resource. If we build on this example, I can define a new SharePoint Online site collection using the following DSC Resource Block:

    SPOSite MyHRSite
        Title              = "Human Resources"
        Url                = "https:/<My Domain>/sites/HR"
        Owner              = "admin@<My Domain>"
        Template           = "STS#3"
        GlobalAdminAccount = $GlobalAdminAccount
        Ensure             = "Present"

The above DSC Resource Block could be inserted inside the Node section of the configuration frame we've convered above. In our example, we are defining a SharePoint Online site collection with title Human Resources and a given URL, owner alias and Template. The DSC Resource Block is given a name of MyHRSite which is meaningless in the bigger scheme of things. DSC simply requires that all instances of a given resource have DSC resource blocks with unique names. Therefore within the same configuration you cannont have two SPOSite DSC Resource Blocks named MyHRSite, but you could have a SPOSite and a SCDLPComplianceRule resource block both named MyHRSite without any issues.

You will also notice from the example above that we are defining a GlobalAdminAccount property, passing it the obtained credentials for our tenant's admin account. This property is required for every DSC Resource Block and specifies what account to impersonate when configuring or analyzing the Microsoft 365 tenant. The other property in the resource block is Ensure. Most resources that can be used to create instances of a component have that property available. It can either be set to Present or Absent. If the above example had the property set to Absent, it would mean that a site collection should never exist at the specified URL. If there was such an existing site, Microsoft365DSC would remove it. Omitting to specify this property on resources that support it will default to a value of 'Present'.

For a full list of all DSC resources supported by Microsoft365DSC, their associated properties and examples on how to use them, please refer to our List of Resources on the wiki of our GitHub repository.

Extracting Configuration from an Existing Microsoft 365 Tenant

The moment you install the Microsoft365DSC module onto a machine, a new PowerShell cmdlet, Export-M365DSCConfiguration is made available. When running the Export-M365DSCConfiguration command, a graphical interface will be launched to allow you to choose which configuration you want to extract. When providing the login credentials, a Tenant Admin must be used otherwise you will not be able to extract the configuration of the tenant. Extracting the configuration out of an existing tenant is often refered to taking a "Configuration Snapshot.

The Export-M365DSCConfiguration cmdlet exposes several parameters to help you customize the extraction experience. The following table lists all the parameters available:

Parameter Name Type Description Description
-Quiet Switch Use this switch to indicate that you wish to do an unattended extraction. When this switch is specified, the Graphical User Interface which lets you select the components to extract will not be displayed. Export-O365Configuration -Quiet
-GlobalAdminAccount PSCredential This parameter is to be used in conjonction with the -Quiet paremeter. It specified the admin credentials to use to perform the configuration's extraction. If you omit this parameter, the user will be prompted to provide credentials before executing the extraction. Specifying this parameter without the -Quiet parameter will not have any effect. $creds = Get-Credential
Export-M365DSCConfiguration -Quiet -GlobalAdminAccount $creds
-ComponentsToExtract String Array The -ComponentsToExtract parameter allows you to specify a granular list of components you wish to extract. The components need to be listed by their associated resource name. For a complete list of all resources supported, please refer to the List of Resources wiki pages on our GitHub repository. Export-M365DSCConfiguration -Quiet -ComponentsToExtract @("EXOMailboxSettings", "TEAMSCallingPolicy", "SCDLPComplianceRule")
-Workloads String Array The -Workloads parameter allows you to specify a list of workloads you wish to extract ALL components from. Accepted valus are:
  • EXO - For Exchange Online
  • O365 - For Office 365 administrative components
  • OD - For OneDrive
  • PP - For Power Platform
  • SC - For Security and Compliance
  • SPO - For SharePoint Online
  • TEAMS - For Teams
Export-M365DSCConfiguration -Quiet -Workloads @("TEAMS", "SPO")
-FileName String Specifies the name of the extracted .ps1 configuration file. If the -Path is not specified along with the -FileName parameter, the file will be created in the current folder where the extraction process was triggered from. If omitted, the default name will be M365TenantConfig.ps1. Export-M365DSCConfiguration -Quiet -FileName "MyTenantExtract.ps1"
-Path String Specifies the location where the extracted .ps1 configuration file will be located. If omitted, the file will be created in the current folder where the extraction process was triggered from. Export-M365DSCConfiguration -Quiet -Path "C:\DSCExtracts\"
-ConfigurationName String Specifies the name of the configuration inside the extracted file. If omitted, the dafault value will be M365TenantConfig. This represents the actual name given to the Configuration object inside the .ps1 file extracted, and by default will always be the name of the compiled configuration folder. Export-M365DSCConfiguration -Quiet -ConfigurationName "MyTenantConfig"
-MaxProcesses Number (integer) Certain resources support parallelism to help speed up their extraction processes. Resources such as TEAMSUser, SPOPropertyBag and SPOUserProfileProperty split up the extraction process over multiple parallel threads. By default, Microsoft365DSC will attempt to create up to 16 parallel threads. By specifying this parameter, you can control the maximum number of parallel threads these resources will spin off. Note that,as an example, if you speficy a value of 20 and that there are only 12 instances of a given resources, that only 12 threads will be spun off. Export-M365DSCConfiguration -Quiet -MaxProcesses 12

The unattended extraction will extract the SPO sites, Hub sites which cannot be done using the graphical interface shown below:

Microsoft365DSC Extraction Graphical User Interface

When using the Graphical Interface, you will need to enter in the Tenant Admin credentials and click "Start Extraction" to capture the configurations for that tenant.

Specific workload configurations can be checked by selecting the checkbox beside each section.

NOTE: This tool fully supports Multi Factor Authentication (MFA) when extracting the configuration. The tool does not support MFA when pushing a configuration to a target tenant.

To get a full list of all components support by Microsoft365DSC, please refer to our Resources List on our GitHub repository.

Once the extraction completes it will prompt you to enter in a file location where the extractions will be stored. If the path entered does not exist, the tool will create it. The following files with the extracted data will be placed in the file location specified:

  • ConfigurationData.psd1 contains information about the tenant, and let's you abstract additional values in your configuration (advanced topic).
  • M365TenantConfig.ps1 file that represents the configuration of the tenant. This file has the information that was extracted.

Apply a Configuration to your Microsoft 365 Tenant

Microsoft365DSC is a PowerShell Desired State Configuration (DSC) module. Just like for any DSC configuration, Microsoft365DSC configurations need to be compiled into a .MOF file before they can be applied.

To compile the configuration file, do the following:

  1. Move to the location where the extracted files reside for example:
        cd C:\Microsoft365DSC\
  2. Execute the ps1 file within PowerShell:
  3. Provide the Tenant Admin password.

A .mof file will be compiled and will represent the Microsoft 365 tenant for example localhost.mof. This localhost.mof file can be re-run against a different tenant and will automatically sync all the configurations that were extracted to the new tenant. The mof file will be located in its own folder and this folder will be named based on the Configuration name within the .ps1 configuration file. In order to apply the compiled configuration against your Microsoft 365 tenant, you will need to call into the Start-DSCConfiguration PowerShell cmdlet. For example, if your configuration was named M365TenantConfig, you can apply the configuration by running the following command:

    Start-DSCConfiguration M365TenantConfig -Wait -Verbose -Force

Monitor Tenants for Configuration Drifts

Once a configuration has been applied to a tenant, the machine from which it was pushed becomes what we commonly call an M365DSC agent. This means that while this machine remains active, it will perform regular (every 15 minutes by default) to assess the tenant against the configuration that was applied, and checks for any configuration drifts. By default, when a configuration drift is detected, the agent will simply log a new error in Event Viewer under Applications and Services Logs > Microsoft365DSC. This default behavior can be changed by configuring the Local Configuration Manager (LCM) of the agent. Other behaviors include not taking any actions when configuration drifts are detected or automatically fixing drifts when they get detected. For more information on how to configure the agent's LCM, please refer to the Configuring the Local Configuration Manager article.

Assess Tenants Against a Blueprint

It is important to understand here that we use the term Blueprint loosely. A blueprint is nothing but a verified and validated Microsoft365DSC configuration file. These Blueprints are configuration files that have been reviewed and approved by an entity and have the .m365 extension. Note that it is completely possible to use any other .ps1 configuration as a blueprint to assess a tenant. In fact you can extract the configuration from a tenant (using the steps in the above section), and use that extracted configuration to assess any other tenant against it. PowerShell Desired State Configuration (DSC) let's you assess an environment against any given compiled DSC configuration without actually applying it on the environment. If you wish to assess the state of your Microsoft 365 tenant against a blueprint you can either use a local blueprint or use an hosted blueprint hosted in a public repository such as GitHub.

To assess a tenant against a local blueprint (.m365 or .ps1), you can use the following PowerShell command. Running the command will prompt you to provide the administrator credentials of the tenant you wish to assess the blueprint against.

        Assert-M365DSCBluePrint -BlueprintUrl {local path or URL to the Blueprint} -OutputReportPath {path to where to save the .html file}

Generating Reports

Whether you wrote your own Microsoft365DSC configuration or you've exported it from an existing tenant, you can convert it to either an HTML or Excel report. Both these reports are read-only, and values changed in the Excel report will not update values in your tenant. To generate reports from an existing configuration, you need to use the New-M365DSCReportFromConfiguration cmdlet. This cmdlet let's you specify what type of report you wish to generate (HTML or Excel), specify the path to the configuration you are generating the report for and the destination path where you wish to store the generated report.

            New-M365DSCReportFromConfiguration -Type Excel -ConfigurationPath c:\DSC\PathToMyConfig.ps1 -OutputPath c:\whatever\Report.xlsx
            New-M365DSCReportFromConfiguration -Type HTML -ConfigurationPath c:\DSC\PathToMyConfig.ps1 -OutputPath c:\whatever\Report.html

Microsoft365DSC also allows you to generate discrepancy reports between two configurations. The discrepancy report will identify the differences between the two configuration into an HTML format.

            New-M365DSCDeltaReport -Source 'C:\DSC\SourceConfig.ps1' -Destination 'C:\DSC\DestinationConfig.ps1' -OutputPath 'C:\Output\Delta.html'