Home Getting Started Wiki Blueprints Contribute Releases YouTube

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:

    
    Install-M365DSCDevBranch
     

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
    Install-M365DSCDevBranch
     

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>
        }
    }
    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. When running the Export-O365Configuration 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:
        
        .\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 Template

It is important to understand here that we use the term Template loosely. A template is nothing but a verified and validated Microsoft365DSC configuration file. On the microsoft365dsc.com website, we offer several "vetted" configuration templates for you to use to assess your tenants against. These official Templates have been reviewed and approved by the team and have the .m365 extension. Note that it is completely possible to use any other .ps1 configuration as a template 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 template you can either use a local template or use an hosted template we offer in the Templates gallery on the Microsoft365DSCcom site.

To assess a tenant against a local template (.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 template against.

    
        Assert-M365DSCTemplate -TemplatePath {local path to the template}
    

Instead, if you wish to assess it against an hosted Template (.o365 file), you can use the -TemplateName parameter instead. This will automatically acquire the template from the microsoft365dsc.com website and initiate the assessment. Running the command will prompt you to provide the administrator credentials of the tenant you wish to assess the template against. Fo example, if you wish to assess your tenant against the Teams Baseline template, you can simply run the following command:

    
        Assert-M365DSCTemplate -TemplateName "Teams-M365Business-Baseline"
    

The Assert-M365DSCTemplate cmdlet will either the following message if the tenant you assessed matched the configuration template:

Successful M365DSC Template Assessment

Or in the case where the tenant is not in compliance with the template, the command will return a list of components that are not in compliance:

Successful M365DSC Template Assessment

While this will only return information about what component is not compliant based on the template it was assessed against, you can find additional in-depth information by looking at the local Microsoft365DSC log journal (under Applications and Services Logs > Microsoft365DSC).

Event Viewer Error Log