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 Microsoft365DSCM365DSC depends on other PS modules such as Graph, DSCParser and more. you can use Update-M365DSCDependencies to install them all in one go:
Update-M365DSCDependenciesBelow is the full code:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
# Install M365DSC module
Install-Module -Name Microsoft365DSC
#Update dependency modules
Update-M365DSCDependencies
Make sure your WinRM service is started and the startupType to automatic from a Windows Management Console (mmc) or 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:
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'}
)
You'll find the service principal in the Azure AD tenant > app registration and certificates & secrets
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
Make sure to add your certificate to the Local computer personal store
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 updateFor 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.
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
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.
You can also open the above UI by using
Export-M365DSCConfiguration -LaunchWebUIExport-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.ApplicationIdYou 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.ApplicationIdThis is what your export could look like if we used Components "TeamsMeetingPolicy":
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.