Prerequisites

To run Microsoft365DSC you will start by installing the PowerShell module.

install-module Microsoft365DSC

To get all the modules needed you can run command and just add the scope of the command you will use with your DSC command.

Update-M365DSCDependencies

If you just installed the module don’t forget to import-module Microsoft365DSC.

Certificate

Next up is to create a self signed certificate. To connect more secure we will use certificate instead of a “secret key”. To create the certificate we start PowerShell and run:

$certname = "{certificateName}"    ## Replace {certificateName}
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256

We can choose between to different methods when we Export the certificate.

  1. This option is preferred if we will only run the scripts/code from the same machine that we use to create the certificate.
  2. This option is if we will run scripts from another source like for example Azure Automation.

Option 1

To Export a certificate that we can use from the machine that we have created the certificate on: 

Export-Certificate -Cert $cert -FilePath "{c:\folder}\$certname.cer"   ##Replace {c:\folder} Specify your preferred location

Option 2

To Export a certificate that can be used from different imported to other locations:

$mypwd = ConvertTo-SecureString -String "{myPassword}" -Force -AsPlainText  ## Replace {myPassword}

Export-PfxCertificate -Cert $cert -FilePath "C:\Users\admin\Desktop\$certname.pfx" -Password $mypwd   ## Specify your preferred location

App registration

Go to Entra ID and create a App registrations with default settings. Give it a name and leave other options default. Select New registration. Choose a name that is according to your convention.

Now you can choose “Certificates and secrets” and select Certificates. Upload the certificate you exported under option 1 in the Certificate part of this blog.

Alternative

If you do not have an app or certificate you can create all with at same time with this PowerShell command:

$ApplicationName = "TestApp20230725-2"
$CertificatePath = "c:\temp\testapp20230725-2.cer" 
$Credential = Get-Credential 

 $Resource = @('IntuneAppProtectionPolicyiOS')

    $AppProtectionPermissions = Get-M365DSCCompiledPermissionList -ResourceNameList                       $Resource -PermissionType Application -AccessType Read

    Update-M365DSCAzureAdApplication -ApplicationName $ApplicationName `
        -Permissions $AppProtectionPermissions `
        -Type Certificate `
        -CreateSelfSignedCertificate `
        -AdminConsent `
        -CertificatePath $CertificatePath `
        -Credential $Credential

App permissions

To be able to execute the commands from Microsoft 365 DSC we need to give the Service Principal(App registration) correct permissions to execute our commands. We should always use least amount of permissions. This means that the permissions we assign to the Service Principal is dependent on what kind of operations we will use in Microsoft 365 DSC.

In this blog I will just export Intune APP Protection policies for iOS as an example.

To be able to export App Protection Policy we need to assign permissions

  • Organization.Read.All
  • DeviceManagementApps.Read.All

If you are unsure about what permissions you will need. You can use
Get-M365DSCCompiledPermissionList

An example of the command above to get the read permissions of the scope for this blog you can run the PowerShell command:

Get-M365DSCCompiledPermissionList -ResourceNameList @('IntuneAppProtectionPolicyiOS') -PermissionType Application -AccessType Read

We can use Azure portal to update permissions for the Service Principal or we can do it directly from our active PowerShell window. To update the permissions I just ran:

Update-M365DSCAzureAdApplication -ApplicationName 'M365 DSC' -Permissions @(@{Api='Graph';PermissionName='Organization.Read.All'},@{Api='Graph';PermissionName='DeviceManagementApps.Read.All'}) -ApplicationId '6cc3c4b4-f490-4b24-9240-fXXXXXXXX' -TenantId contoso.onmicrosoft.com -CertificateThumbprint '$cert.thumbprint' -Type Certificate -CertificatePath c:\{folder}\CloudtechXXXXXXXX.cer ##Replace ApplicationName, ApplicationId, TenantId, CertificateThumbprint and CertificatePath

Now go to the App in Azure AD and make sure that you grant admin consents for the permissions.

Export configuration

Now you can export the configuration. You can specify the location where you want to save the config. 

Export-M365DSCConfiguration -applicationID '6cc3c4b4-f490-4b24-9240-fXXXXXXXXX' -TenantID 'cloudtechnu.onmicrosoft.com' -CertificateThumbprint '3DD4EF83031AE96BCBD70B0B0XXXXXXXXXXX' -Components @('IntuneAppProtectionPolicyiOS')

This will generate a folder with two files in a folder.

  • ConfigurationData – Information about the tenant and connection
  • M365TenantConfig – The settings of App Protection Policies for iOS in my case. This is dependent on what you choose to export.

Issues

I have had a lot of issues with the DSC commands but when I run the PowerShell Core version 7 in preview from visual studio code all DSC commands works much better without many of the module issues I got in Windows PowerShell.