Getting Started

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
    

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.

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.

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>
        }
    }
    NameOfTheConfiguration
    

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. 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
-LaunchWebUI	Switch	Launches a new web browser and navigates to the Web based Graphical User Interface.	Export-M365DSCConfiguration -LaunchWebUI
-Credential	PSCredential	Specifies the 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.	$creds = Get-Credential Export-M365DSCConfiguration -Credential $creds
-Components	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-Components @("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 -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 -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 -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 -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 -MaxProcesses 12

NOTE: While Microsoft365DSC fully supports Multi Factor Authentication (MFA) when extracting the configuration, it does not support MFA when pushing a configuration to a target tenant (Automate).

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:

       
       .\M365TenantConfig.ps1
       
   

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'