ASD - Australian Signals Directorate

ASD's Blueprint for Secure Cloud

Desired State Configuration setup

This page describes the setup of Microsoft 365 Dynamic State Configuration (DSC)

Estimated reading time: 3 minutes

Overview

Microsoft 365 Desired State Configuration (M365DSC) is a configuration-as-code tool developed by Microsoft to automate the configuration of Microsoft 365 services. It is the primary tool used to automate the deployment of the configuration guidance in the Blueprint.

After following the steps below, please refer to the automated deployment or configuration assessment pages for further instructions.

Prerequisites

To deploy or assess an M365DSC configuration, the following prerequisites are required:

  • Knowledge of the Microsoft M365DSC prerequisites.
  • An admin account on a Windows host with connectivity to Entra ID and Microsoft 365, and with:
    • Powershell 5.1 or 7.3+ with the M365DSC module and dependencies installed. Instructions can be found here.
    • The WinRM service configured and running. Instructions can be found here.
  • The DSC file for the targeted M365 service (discussed below).
  • A DSC configuration data file from a configuration index page.

1. Create certificates and keys for authentication

On the Windows host used for deployment, execute the following commands in an elevated PowerShell prompt to create a PFX file that will be used for authentication, substituting a password of your choice and the location of your working folder:

$certname = 'M365DSC'
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation 'Cert:\CurrentUser\My' -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$password = ConvertTo-SecureString -String '<password>' -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath 'C:\<location>\M365DSC.pfx' -Password $password

2. Import the PFX file into the Local Computer certificate store

  • Double-click the M365DSC.pfx file to begin the import wizard.
  • Select Local Machine and accepting the defaults, follow the prompts to complete the wizard.

3. Export the leaf certificate from the Local Computer certificate store

  • Open the Local Computer certificate store (Start > Manage Computer certificates) and navigate to Personal\Certificates.
  • Right-click the M365DSC certificate, then select All Tasks > Export to begin the export wizard.
  • Accepting the defaults, follow the prompts to complete the wizard, specifying C:\<location>\M365DSC.cer as the file name, substituting location with the name of your working folder.

4. Register an app and service principal in Entra

Authenticate to your Entra tenant with an account with permissions to register an app and update the app’s permissions:

$creds = Get-Credential

Create the app, specifying the exported certificate to be used for authentication, substituting location with the name of your working folder:

Update-M365DSCAzureAdApplication -ApplicationName 'M365DSC' -Type Certificate -CertificatePath 'C:\<location>\M365DSC.cer' -Permissions @( @{Api='Graph';PermissionName='Organization.Read.All'} ) -Credential $creds

5. Download and edit the configuration data file

  • Download the configuration data file, renaming the linked .txt file to .psd1.
  • Edit the configuration data file to suit, substituting your Entra tenant and M365DSC app configurations:
# Your Entra tenant ID
TenantId = '<GUID>'

# Your Entra primary domain name
OrganizationName = '<organisation>.onmicrosoft.com'

# The Application ID of your app
ApplicationId = '<GUID>'

# The thumbprint of the certificate to authenticate your app
# This can be found in the certificates and secrets section of your app or in the the details tab of the exported CER file.
CertificateThumbprint = '<thumbprint hash>'

Refer to the automated deployment or configuration assessment pages for further instructions.

Configuration

Tools

References

Do you have a suggestion on how the above page could be improved? Get in touch! ASD's Blueprint for Secure Cloud is an open source project, and we would love to get your input. Submit an issue on our GitHub, or send us an email at blueprint@asd.gov.au

Acknowledgement of Country icon

Acknowledgement of Country
We acknowledge the Traditional Owners and Custodians of Country throughout Australia and their continuing connections to land, sea and communities. We pay our respects to them, their cultures and their Elders; past, present and emerging. We also recognise Australia's First Peoples' enduring contribution to Australia's national security.

Authorised by the Australian Government, Canberra