top of page
  • Writer's pictureWill Francillette

M365DSC: Getting Started Part 2: Installation, authentication and export configuration

Updated: Mar 7


Microsoft 365 DSC

It's time for the part 2 of our series on Microsoft 365 DSC (M365DSC). This time we will cover the installation, the authentication and how to export your first resource.


Table of Content


Installation

Microsoft 365 DSC is a PowerShell module such as many others and can simply be installed from PowerShellGet gallery.


It requires local administrator privileges due to dependencies to the Windows Remote Management service (WinRM), so make sure to open PowerShell as administrator.


The solution is supported on PowerShell 5.1 and 7.1 and it's recommended to use the Windows Terminal as it's easy to switch between the different versions of PowerShell and has a better icon render. You can also use the legacy PowerShell application, the ISE and Visual Studio Code.


You may need to configure PowerShell execution policy (if not already done) to remoteSigned


Then run:

Install-Module -Name Microsoft365DSC

M365DSC depends on other PS modules such as Graph, DSCParser and more. you can use Update-M365DSCDependencies to install them all in one go:

Update-M365DSCDependencies

Below is the full code:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

# Install M365DSC module
Install-Module -Name Microsoft365DSC

#Update dependency modules
Update-M365DSCDependencies
M365dsc cmdlets

Make sure your WinRM service is started and the startupType to automatic from a Windows Management Console (mmc) or PowerShell

WinRM service
winRM service PowerShell

Authentication and permissions

The authentication in M365DSC is managed by the MSCloudLoginAssistant which allow a transparent and consistent authentication and connection to the different workloads. All workloads don't currently offer the same authentication features but Credential and Certificate Thumbprint authentication are available for all workloads.

Below the full description:

m365dsc authentication methods

For unattended processes best to use certificate thumbprint and not certificate secret. For evaluation purpose, the team has simplified the setup using: Update-M365DSCAzureAdApplication to create a Service Principal and configure a self-signed certificate. For production workloads, you would rather used a certificate signed by a CA or a managed identity.

Update-M365DSCAzureAdApplication `
    -ApplicationName 'Microsoft365DSC-F365C' ` #Name of the SP
    -AdminConsent ` #Grant Admin consent to the app and permissions
    -Type Certificate ` # Type of credential: Secret or Certificate
    -CreateSelfSignedCertificate `# Create the self-signed certificate
    -CertificatePath c:\Temp\M365DSC.cer ` # Destination path for the cert
    -Permissions @( #Array of permissions
        @{Api='SharePoint';PermissionName='Sites.FullControl.All'}
        )

m365dsc authentication interactive
m365dsc authentication certificate

You'll find the service principal in the Azure AD tenant > app registration and certificates & secrets

m365dsc service principal certificate setup

Keep a note of the thumbprint, app id and tenant id in the overview page we will use them later to connect.

You'll find the certificate in the location you've used in the parameter CertificatePath

certificate install 1

Make sure to add your certificate to the Local computer personal store


certificate install 2

certificate install 3

certificate install 4

certificate install 6


Finally the permissions, and again the team has made your life easy: you can use Update-M365DSCAllowedGraphScopes to grant permission to your application. Each resource is defined with the minimum set of permissions required to read or update a resource. You only need to assign the correct permission the first time you plan to use this resource.

Update-M365DSCAllowedGraphScopes `
    -ResourceNameList @('AADUSer', 'AADApplication') ` #List of resource
    -Type 'Read' # Possible value: read and update

For more information about Service Principal management, visit my previous posts:

Of course all those cmdlets are just helpers and nothing prevents you to manage those manually with your preferred method


Export resource

Available resources


M365DSC has more than 200 resources available across

  • Azure AD

  • Exchange Online

  • Intune

  • Office 365

  • OneDrive

  • Power Apps

  • Planner

  • Microsoft Purview

  • SharePoint Online

  • Teams

A resource is simply a policy or an object you can export and monitor its configuration.

They are named following this pattern:

<Workload><PolicyName>

AADTeamsMeetingPolicy

You can use export.microsoft365dsc.com to retrieve all currently available resources.

m365dsc resource selection

This is an easy way to generate your resource but more about this later in this blog.


The other way to retrieve the list of available resources is PowerShell and Get-M365DSCAllResources

m365dsc available resources

Export

A resource is exported using Export-M365DSCConfiguration

This function is very powerful and use the reverse DSC proxy developed by Microsoft team.

The exported resource is used to generate the mof file processed by the DSC engine.

It has many use cases such as

  • Policy backup

  • Tenant copy

  • Staging environment

  • Bulk deployment

  • Configuration drift monitoring

  • Versioning

  • and so many more

If you're just starting or evaluating the solution, I would advise to generate your first export using the export UI: export.microsoft365dsc.com > choose your resource(s), select the authentication type and press generate to retrieve the code


Make sure to start small!


The export job can be very long depending of the size of your environment, so don't try to export your complete tenant in once.


Focus on an area and then expand the scope of your deployment.

You can start with Teams meeting policy or Azure AD Conditional Access for example.

m365dsc first export resource selection
m365dsc first export script

You can also open the above UI by using

Export-M365DSCConfiguration -LaunchWebUI

Export-M365DSCConfiguration can export specific resources across any workloads by using the parameter Components (it's an array of string)

$params = @{
    #Credential           = (Get-Credential)
    ApplicationId         = "MyServicePrincipalId"
    TenantId              = "MyTenant.onmicrosoft.com"
    CertificateThumbprint = "MyCertificateThumbprint"
    #ApplicationSecret    = $ApplicationSecret
}

Export-M365DSCConfiguration `
    -Components @("TeamsMeetingPolicy","AADConditionalAccessPolicy") `
    -Path "C:\M365DSC\Exports\MyFirstResourceExport" `
    -CertificateThumbprint  $params.CertificateThumbprint `
    -TenantId  $params.TenantId `
    -ApplicationId $params.ApplicationId

You can also use the parameter Workload, to retrieve all the policies available for a specific workload such as Azure AD or Teams. Possible values are

  • AAD : Azure AD

  • SPO : SharePoint Online

  • EXO : Exchange Online

  • INTUNE : Microsoft Intune

  • SC : Microsoft Purview (SC for Security and Compliance)

  • OD : OneDrive for Business

  • O365 : Microsoft/Office 365 organization global settings

  • PLANNER : Microsoft Planner

  • PP: Power Platform

  • TEAMS : Microsoft Teams

$params = @{
    #Credential           = $Credential
    ApplicationId         = "MyServicePrincipalId"
    TenantId              = "MyTenant.onmicrosoft.com"
    CertificateThumbprint = "MyCertificateThumbprint"
    #ApplicationSecret    = $ApplicationSecret
}

Export-M365DSCConfiguration `
    -Workloads @("AAD","EXO") `
    -Path "C:\M365DSC\Exports\MyFirstWorkloadExport" `
    -CertificateThumbprint  $params.CertificateThumbprint `
    -TenantId  $params.TenantId `
    -ApplicationId $params.ApplicationId

This is what your export could look like if we used Components "TeamsMeetingPolicy":


m365dsc first export resource

Conclusion

The solution was initially created for Office 365 workloads (SharePoint Online, Teams and Exchange Online) and then integrated the Graph SDK for Azure AD and Intune workloads. It is in continuous development and new resources are added frequently. Get in contact with the team on GitHub for feedback , issues and feature requests.


In the next blog, we will start processing those exports and expand on how to use and monitor them.


Reference

2,833 views0 comments

Comments


bottom of page