Azure Guest Configuration extends Azure Policy into the operating system of Azure virtual machines and Arc-enabled servers. A custom guest configuration lets you describe a desired state in PowerShell DSC, package it, host it, and use Azure Policy to audit or remediate that state at scale.

This article walks through a Windows example that enforces a legal logon message. The same process applies to IIS features, Windows optional features, users, registry values, and other DSC resources.

Important: Test every package in a non-production subscription first. An AuditAndSet package changes the guest operating system when it detects drift.

Matrix of supported systems

Machine configuration policy definitions are inclusive of new versions. Older versions of operating systems available in Azure Marketplace are excluded if the Guest Configuration client isn’t compatible. Additionally, Linux server versions that are out of lifetime support by their respective publishers are excluded from the support matrix.

How the pieces fit together

The workflow has five parts:

1. Author a DSC configuration and compile it into a MOF file.
2. Package the MOF with the Guest Configuration module.
3. Validate the package locally and calculate its content hash.
4. Upload the ZIP package to HTTPS-accessible blob storage.
5. Assignee configuration package to Virtual Machine.

Prerequisites

Before creating a custom package, prepare the authoring workstation and Azure environment.

Install the two DSC modules on the authoring workstation:

Note: PSDesiredStateConfiguration is required in version at lest 2.0.7

Install-Module -Name PSDscResources -Scope CurrentUser
Install-Module -Name GuestConfiguration -Scope CurrentUser # Work only on PowerShell 7

Get-Module -ListAvailable -FullyQualifiedName PSDscResources
Get-Module -ListAvailable -FullyQualifiedName GuestConfiguration

Sign in to the tenant and select the subscription where the policy will be assigned:

Connect-AzAccount
Set-AzContext -Subscription '<subscription-id-or-name>'

Step 1: Virtual Machine need to have those perquisites

⁉️ Resource provider on subscription need to be registred: Microsoft.GuestConfiguration.
⁉️ System Assigne Identity / User Managed Idenity.
⁉️ Virtual machine extension is enabled, To use machine configuration packages that apply configurations, Azure VM guest configuration extension version 1.26.24 or later, or Arc agent 1.10.0 or later, is required.
⁉️ Azure Arc servers are supported.

Prerequisites can be added by Azure policy to all servers on different scope:

Step 2: Author and compile the DSC configuration

Guest Configuration packages use a compiled DSC MOF. The following configuration writes a title and body for the Windows interactive logon message.

Configuration SetupLogonMessage {
    Import-DscResource -ModuleName PSDscResources

    Node 'localhost' {
        Registry LogonMessageTitle {
            Key       = 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'
            ValueName = 'legalnoticecaption'
            ValueData = 'Security Warning'
            ValueType = 'String'
            Ensure    = 'Present'
            Force     = $true
        }

        Registry LogonMessageBody {
            Key       = 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System'
            ValueName = 'legalnoticetext'
            ValueData = 'Authorized access only. All activities are monitored and recorded.'
            ValueType = 'String'
            Ensure    = 'Present'
            DependsOn = '[Registry]LogonMessageTitle'
            Force     = $true
        }
    }
}

SetupLogonMessage -OutputPath .\SetupLogonMessage

Compilation creates SetupLogonMessage.mof in the output folder. Keep the configuration source in version control alongside the generated policy files, but rebuild the MOF and package whenever the configuration changes.

Step 3: Create the Guest Configuration package

Note: PowerShell 7 need to be running as local administrator

Choose the package type deliberately:

For the logon-message configuration, create an AuditAndSet package:

Note: Package name need to exactly the same as configuration file.

$params = @{
    Name          = 'SetupLogonMessage'
    Configuration = './SetupLogonMessage/SetupLogonMessage.mof'
    Type          = 'AuditAndSet'
    Force         = $true
    # FrequencyMinutes = 180 # Default is 15 minutes.
}

New-GuestConfigurationPackage @params

Zip file will contain resources and config file.

Step 4: Validate the package before publishing

Validate locally before you place the ZIP in storage or create a policy definition. This catches packaging errors and gives you the hash that Azure Policy uses to identify the exact package version.

Get-FileHash .\SetupLogonMessage.zip
Get-GuestConfigurationPackageComplianceStatus -Path .\SetupLogonMessage.zip

The compliance command should return a result instead of a packaging or resource-loading error. If it fails, confirm that every DSC resource referenced by the MOF is available to the Guest Configuration packaging process and that the MOF path is correct.

Step 5: Publish the ZIP to a stable HTTPS URI

Upload the ZIP to Azure Blob Storage. The policy definition must reference a URI that every target machine can reach over HTTPS. A blob URI with a time-limited SAS token is useful for testing, but production packages should use an access method and renewal process that will not unexpectedly expire.

After upload, keep the content URI and the SHA-256 value from Get-FileHash available. Treat a package update as a versioned release: publish a new ZIP, validate it, then update the policy definition or create a new policy version.

Step 6: Deploy guest configuration to one virtual machine

For a single test VM, create a Guest Configuration assignment directly on the VM. This does not create an Azure Policy definition or policy assignment. Azure installs or updates the Guest Configuration extension as part of processing the assignment.

Install the Azure PowerShell module that provides the assignment cmdlets:

Install-Module -Name Az.GuestConfiguration -Scope CurrentUser

Set the values for the target VM and the published ZIP. The content hash must be the SHA-256 value returned in Step 4 for the exact ZIP file at $contentUri.

$resourceGroupName = '<resource-group-name>'
$vmName            = '<virtual-machine-name>'
$contentUri        = 'https://<storage-account>.blob.core.windows.net/<container>/SetupLogonMessage.zip?<sas-token>'
$contentHash       = (Get-FileHash -Path '.\SetupLogonMessage.zip' -Algorithm SHA256).Hash

$assignmentParams = @{
    GuestConfigurationAssignmentName = 'SetupLogonMessage'
    ResourceGroupName                = $resourceGroupName
    VMName                           = $vmName
    GuestConfigurationName           = 'SetupLogonMessage'
    GuestConfigurationVersion        = '1.0.0'
    GuestConfigurationContentUri     = $contentUri
    GuestConfigurationContentHash    = $contentHash
    GuestConfigurationAssignmentType = 'ApplyAndAutoCorrect'
    GuestConfigurationKind           = 'DSC'
}

New-AzGuestConfigurationAssignment @assignmentParams

ApplyAndAutoCorrect applies the AuditAndSet package and corrects drift. To use an Audit package instead, set GuestConfigurationAssignmentType to Audit; the extension reports compliance but does not change the VM.

Configuration can be added by Azure portal, as well from Virtual machine management resources.

Check the assignment status and verify the expected values on the VM:

Get-AzGuestConfigurationAssignment `
    -ResourceGroupName $resourceGroupName `
    -VMName $vmName `
    -GuestConfigurationAssignmentName 'SetupLogonMessage'

Get-ItemProperty `
    -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' `
    -Name legalnoticecaption, legalnoticetext

Check assignment is also available form Azure portal from Virtual Machine resource management plane.

Note: The assignment must show a successful provisioning state before the configuration can report compliance. Ensure the VM can reach the package URI over HTTPS and that the SAS token remains valid for the test.

Guest Configuration assignment can be check globally for all resources in section Guest Assignments in Azure Portal

DSC (Guest Configuration) custom package authoring and deploying process

Common problems

Summary

Custom Guest Configuration turns a DSC configuration into a control that can be measured across a fleet. The reliable loop is simple: compile the MOF, package it, validate it locally, publish it to a durable HTTPS location, generate the policy, and assign it to a limited test scope before expanding the rollout.

Examples of code

Code examples of configuration can be found on this repo in GitHub - Blog code examples Github

This guide shows how to discover DSC v3 resources for Azure Arc, how to list and filter resources available on your machine, and how to read current configuration state before applying changes.

The resource used in this catalog is Microsoft.Azure.Arc/AgentConfiguration.

Prerequisites

Install DSC v3:

winget install --id Microsoft.DSC --exact --source winget

Make the resource discoverable:

$repoRoot = "D:\Git\AzureConnectedMachineDsc"
$env:DSC_RESOURCE_PATH = Join-Path $repoRoot 'dsc_resources'

Confirm the resource is visible:

dsc resource list | Select-String 'Microsoft.Azure.Arc/AgentConfiguration'

How to List and Get DSC Resources

List all DSC resources currently available:

dsc resource list

List only Azure Arc-related resources:

dsc resource list | Select-String 'Microsoft.Azure.Arc'

Get current state from the Azure Arc resource:

'{}' | dsc resource get -r Microsoft.Azure.Arc/AgentConfiguration -f - | ConvertFrom-Json

The get output includes an actualState object with values such as:

• incomingConnectionsEnabled
• guestConfigurationEnabled
• extensionsEnabled
• extensionAllowlist
• extensionBlocklist
• configMode
• agentInstalled

Use this output as your baseline before creating desired-state payloads for test and set.

Configurable Options

The resource supports these writable options:

Read-only output fields:

• agentInstalled
• _inDesiredState

Important runtime notes:

• set operation requires elevated security context.
• Unknown properties are rejected.
• configMode only accepts monitor or full.

Quick Get and Test

Get current state:

'{}' | dsc resource get -r Microsoft.Azure.Arc/AgentConfiguration -f - | ConvertFrom-Json

Test desired state:

$desired = @{
	incomingConnectionsEnabled = $false
	guestConfigurationEnabled  = $false
	extensionsEnabled          = $false
	extensionAllowlist         = @(
		"Microsoft.Azure.AzureDefenderForServers/MDE.Windows"
		"Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"
	)
	extensionBlocklist         = @(
		"Microsoft.Azure.Automation.HybridWorker/HybridWorkerForWindows"
		"Microsoft.Azure.Automation/HybridWorkerForLinux"
		"Microsoft.Azure.Extensions/CustomScript"
		"Microsoft.Cplat.Core/RunCommandHandlerLinux"
		"Microsoft.Cplat.Core/RunCommandHandlerWindows"
		"Microsoft.Compute/CustomScriptExtension"
		"Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent"
		"Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux"
	)
	configMode = "full"
}

$desired | ConvertTo-Json -Depth 10 -Compress |
	dsc resource test -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

Example: Export Current Configuration

Use export to capture live, non-null settings and reuse them as a baseline:

$exported = '{}' |
	dsc resource export -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

$exported | ConvertTo-Json -Depth 10 | Set-Content .\arc-agent-export.json

Why this helps:

• Baselines current production settings.
• Makes onboarding additional servers easier.
• Supports drift investigations.

Tier 0 Server Baseline (Recommended)

For Tier 0 servers, use a strict Arc agent profile with the following requirements:

• incomingconnections.enabled = false
• guestconfiguration.enabled = false
• extensions.allowlist = Microsoft.Azure.Monitor/AzureMonitorWindowsAgent,Microsoft.Azure.AzureDefenderForServers/MDE.Windows

In the DSC resource payload, these map to:

• incomingConnectionsEnabled = $false
• guestConfigurationEnabled = $false
• extensionAllowlist = @("Microsoft.Azure.Monitor/AzureMonitorWindowsAgent", "Microsoft.Azure.AzureDefenderForServers/MDE.Windows")

Tier 0 set example:

$tier0Desired = @{
	incomingConnectionsEnabled = $false
	guestConfigurationEnabled  = $false
	extensionAllowlist         = @(
		"Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"
		"Microsoft.Azure.AzureDefenderForServers/MDE.Windows"
	)
}

$tier0Desired | ConvertTo-Json -Depth 10 -Compress |
	dsc resource set -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

$tier0Desired | ConvertTo-Json -Depth 10 -Compress |
	dsc resource test -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

This baseline reduces attack surface by disabling incoming Arc connections, turning off guest configuration, and allowing only the required monitoring and defender extensions.

Example: Set Desired Configuration

Apply a hardened configuration with allowlist/blocklist control and full mode:

$desired = @{
	incomingConnectionsEnabled = $false
	guestConfigurationEnabled  = $false
	extensionsEnabled          = $false
	extensionAllowlist         = @(
		"Microsoft.Azure.AzureDefenderForServers/MDE.Windows"
		"Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"
	)
	extensionBlocklist         = @(
		"Microsoft.Azure.Automation.HybridWorker/HybridWorkerForWindows"
		"Microsoft.Azure.Automation/HybridWorkerForLinux"
		"Microsoft.Azure.Extensions/CustomScript"
		"Microsoft.Cplat.Core/RunCommandHandlerLinux"
		"Microsoft.Cplat.Core/RunCommandHandlerWindows"
		"Microsoft.Compute/CustomScriptExtension"
		"Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent"
		"Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux"
	)
	configMode = "full"
}

$desired | ConvertTo-Json -Depth 10 -Compress |
	dsc resource set -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

After set, run a validation pass:

$desired | ConvertTo-Json -Depth 10 -Compress |
	dsc resource test -r Microsoft.Azure.Arc/AgentConfiguration -f - |
	ConvertFrom-Json

You should see _inDesiredState: true when everything is applied correctly.

Troubleshooting Tips

If DSC cannot find the resource:

• Verify DSC_RESOURCE_PATH points to the dsc_resources folder.
• Run dsc resource list and check for Microsoft.Azure.Arc/AgentConfiguration.

If set fails with security context errors:

• Run PowerShell as Administrator.

If the agent is not installed:

• Install Azure Arc Connected Machine Agent (azcmagent) first.

Summary

This catalog gives you a practical DSC v3 interface for Azure Arc agent local configuration. The best operational pattern is:

1. export current state as baseline.
2. Define desired hardened settings.
3. set and then test for drift-free compliance.

It is simple, scriptable, and easy to plug into CI/CD pipelines for consistent Arc agent posture across servers.

References

• Microsoft DSCv3 Github
• DSC Resources Github
• Blog code examples Github

Auto-Documenting DSC v3 Drift and Compliance with DSC-DocsGenerator

Introduction

DSC v3 is excellent at telling you whether a target is in the desired state — but the raw output of dsc config test is JSON intended for tooling, not humans. Auditors, security reviewers, and operations teams need something they can read, share, and attach to a change record: a report that says what was configured, what was actually found on the machine, and which controls drifted.

That is the gap DSC-DocsGenerator fills. It is a small PowerShell module that wraps dsc config test, parses the JSON output, and emits a Markdown report containing:

• A configuration summary (OS, hostname, file, run time, document version).
• A resource overview table with per-control compliance status.
• A detailed desired vs actual state block for every resource.

The module is published to the PowerShell Gallery as DSC-DocsGenerator and the source lives at mimachniak/DSC-DocsGenerator.

This post walks through what the module does, how to install and run it, and shows a real CIS Windows Server 2025 example with drift and compliance points.

Why an Auto-Generated Compliance Report?

DSC v3’s test subcommand returns structured JSON describing, for each resource, whether the system is _inDesiredState, which properties differ, the desired state from the YAML, and the actual state collected from the machine. That JSON is precise but hard to consume.

A Markdown report on top of that JSON gives several practical wins:

The same flow works for any DSC v3 configuration — application baselines, WinRM hardening, ActiveDirectory roles — but a CIS benchmark is the clearest demonstration because it produces a large number of controls with a realistic mix of compliant and non-compliant results.

How the Module Works

The single public command is Invoke-DSCDrifftDocs (note the intentional double f in Drifft — it must be typed exactly).

When invoked, it performs these steps internally:

1. Verifies the dsc CLI is installed and on PATH.
2. Reads the YAML config and checks that the referenced resource types are available.
3. Runs dsc config test --file <ConfigFile>.
4. Parses the JSON returned by DSC.
5. Builds the Markdown report (summary, overview table, per-resource details).
6. Writes the report file unless -WhatIf is used.

That is the whole pipeline: YAML in → DSC test → JSON → Markdown out.

Prerequisites

• PowerShell 5.1 or PowerShell 7+.

• DSC v3 installed and available on PATH (dsc --version works). Install with:

  winget install --id Microsoft.DSC
  

• The DSC resources referenced by the YAML config installed. For the CIS examples that is Microsoft.Windows/Registry (built-in to DSC v3) and SecurityPolicyDsc.

Install the Module

Three options, in order of convenience:

Option 1 — PowerShell Gallery (recommended)

Install-Module -Name DSC-DocsGenerator
Import-Module DSC-DocsGenerator -Force

Option 2 — Clone and import from the repo

git clone https://github.com/mimachniak/DSC-DocsGenerator.git
Import-Module .\DSC-DocsGenerator\module\DSC-DocsGenerator\DSC-DocsGenerator.psd1 -Force

Option 3 — Copy to $env:PSModulePath

Copy the module\DSC-DocsGenerator folder to any path in $env:PSModulePath, then:

Import-Module DSC-DocsGenerator -Force

Verify the command is exported:

Get-Command -Module DSC-DocsGenerator

Command Syntax

Invoke-DSCDrifftDocs `
    -ConfigFile <string> `
    [-OutputFile <string>] `
    [-DocumentVersion <string>] `
    [-ReportTitle <string>] `
    [-PassThru] `
    [-WhatIf] [-Confirm] [-Verbose]

Example — CIS Windows Server 2025 Level 1 Member Server

The repository ships with two ready-to-run CIS baselines under dsc-config\:

• CIS-w2025-Level1-MemberServer.registry.dsc.yaml — 260 registry controls.
• CIS-w2025-Level1-MemberServer.securitypolicy.dsc.yaml — 38 account policy, user rights, and security option controls.

1) Generate the registry compliance report

Invoke-DSCDrifftDocs `
    -ConfigFile .\dsc-config\CIS-w2025-Level1-MemberServer.registry.dsc.yaml `
    -OutputFile .\report-example\registry-report.md `
    -ReportTitle "CIS Windows Server 2025 - Registry Compliance" `
    -DocumentVersion "2.0"

2) Generate the security policy report with default output

Invoke-DSCDrifftDocs `
    -ConfigFile .\dsc-config\CIS-w2025-Level1-MemberServer.securitypolicy.dsc.yaml

3) Capture the Markdown in memory (no file written next to the YAML)

$markdown = Invoke-DSCDrifftDocs `
    -ConfigFile .\dsc-config\CIS-w2025-Level1-MemberServer.registry.dsc.yaml `
    -PassThru

$markdown.Length

4) Preview without writing

Invoke-DSCDrifftDocs `
    -ConfigFile .\dsc-config\CIS-w2025-Level1-MemberServer.registry.dsc.yaml `
    -WhatIf

What the Generated Report Looks Like

The full rendered examples live in report-example/. Below are the key sections, taken from the registry baseline run on a freshly built Windows Server 2025 box.

Configuration Summary

The report opens with a fixed metadata block — exactly the information an auditor wants on the first page:

On a default-installed Server 2025 image the registry baseline is 32/260 compliant — exactly what you would expect before any CIS hardening is applied. That ratio becomes the headline KPI you track across remediation runs.

Resource Overview

Below the summary the report lists every control with its CIS reference, status, and DSC type:

This table is the triage view: filter to ❌ rows and you have a backlog of CIS controls to remediate, each with its benchmark number for traceability.

Per-Resource Drift Detail

For every control the report renders a block with the differing properties and the full desired vs actual JSON. A compliant control:

### 4. 2.3.2.2 - CrashOnAuditFail

| Property | Value |
|----------|-------|
| **Status** | ✅ Compliant |
| **Type** | `Microsoft.Windows/Registry` |

**Desired State**

```json
{
  "_exist": true,
  "keyPath": "HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Lsa",
  "valueName": "CrashOnAuditFail",
  "valueData": { "DWord": 0 }
}
```

**Actual State**

```json
{
  "keyPath": "HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Lsa",
  "valueName": "CrashOnAuditFail",
  "valueData": { "DWord": 0 }
}
```

A non-compliant control with a value mismatch — CIS 2.3.7.2 Interactive logon: Do not display last user name:

### 12. 2.3.7.2 - DontDisplayLastUserName

| Property | Value |
|----------|-------|
| **Status** | ❌ Non-Compliant |
| **Type** | `Microsoft.Windows/Registry` |
| **Differing Properties** | `valueData` |

**Desired State**

```json
{
  "_exist": true,
  "keyPath": "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System",
  "valueName": "DontDisplayLastUserName",
  "valueData": { "DWord": 1 }
}
```

**Actual State**

```json
{
  "keyPath": "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System",
  "valueName": "DontDisplayLastUserName",
  "valueData": { "DWord": 0 }
}
```

And a missing-key drift — CIS 9.1.1 Windows Firewall: Domain: Firewall state not configured at all:

### 57. 9.1.1 - EnableFirewall

| Property | Value |
|----------|-------|
| **Status** | ❌ Non-Compliant |
| **Type** | `Microsoft.Windows/Registry` |
| **Differing Properties** | `_exist`, `valueName`, `valueData` |

**Desired State**

```json
{
  "_exist": true,
  "keyPath": "HKEY_LOCAL_MACHINE\\SOFTWARE\\Policies\\Microsoft\\WindowsFirewall\\DomainProfile",
  "valueName": "EnableFirewall",
  "valueData": { "DWord": 1 }
}
```

**Actual State**

```json
{
  "keyPath": "HKEY_LOCAL_MACHINE\\SOFTWARE\\Policies\\Microsoft\\WindowsFirewall\\DomainProfile",
  "_exist": false
}
```

The Differing Properties row is the most useful piece of metadata: it points straight to which fields drifted (valueData only, vs. the whole key being absent), so you can decide whether the gap is a missed GPO, a wrong value, or a key never created.

The Security Policy Baseline

The second baseline — SecurityPolicyDsc/AccountPolicy, SecurityPolicyDsc/UserRightsAssignment, SecurityPolicyDsc/SecurityOption — produces the same shape of report but exercises a different resource provider. On the same fresh Server 2025 the summary is 26/38 compliant, and the drift blocks include rich examples like 2.2.21 Deny access to this computer from the network:

### 16. 2.2.21 Deny access to this computer from the network

| Property | Value |
|----------|-------|
| **Status** | ❌ Non-Compliant |
| **Type** | `SecurityPolicyDsc/UserRightsAssignment` |
| **Differing Properties** | `Identity`, `Force` |

**Desired State**

```json
{
  "Policy": "Deny_access_to_this_computer_from_the_network",
  "Identity": [ "Guests", "[Local Account|Administrator]" ],
  "Force": true
}
```

The same module, the same command — only the input YAML changes.

Where This Fits in a DSC v3 Workflow

This module is the reporting leg of the lifecycle described in the earlier posts in this series:

• Setting Up WinRM HTTPS Listener with DSC v3 and PowerShell — authoring DSC v3 YAML configurations.
• Deploy and Configure a Windows VM with Bicep and DSC v3 — applying configurations as part of an IaC deployment.
• How to use DSC v3 in Azure DevOps — pipelining the apply step.

Invoke-DSCDrifftDocs plugs into the same pipelines: run it in a scheduled job or release stage after dsc config test, publish the resulting Markdown as a pipeline artifact, and you have a per-host audit trail without writing a single line of custom JSON parsing.

Troubleshooting

dsc not found — Install DSC v3 with winget install --id Microsoft.DSC and confirm with dsc --version.

Missing DSC resources — Install the modules referenced by the YAML (for the CIS examples that is SecurityPolicyDsc) and rerun.

No report written — Check whether -WhatIf was used, and confirm the output folder is writable.

Run with diagnostics — Add -Verbose to see each pipeline step.

Wrap-Up

DSC-DocsGenerator turns the raw JSON output of dsc config test into a Markdown compliance report with summary metrics, a per-control overview, and full desired vs actual state for every resource — in a single command. Run it once against the bundled CIS Windows Server 2025 baselines and you immediately have an audit-quality document showing exactly where the box drifts from the benchmark.

• Module: github.com/mimachniak/DSC-DocsGenerator
• PowerShell Gallery: DSC-DocsGenerator
• Example reports: report-example/

Pull requests and issues are welcome.

Deploy and Configure a Windows VM with Bicep and DSC v3

Introduction

Infrastructure as Code (IaC) covers not only resource provisioning but also the initial operating system configuration. Bicep handles the Azure resources; DSC v3 handles the Windows configuration. Combining them in a single deployment means the VM is provisioned and correctly configured before the deployment finishes.

This post walks through deploying a Windows Server 2025 Azure VM with Bicep and then using two DSC v3 YAML documents — served from Azure Blob Storage — to:

1. Create a self-signed certificate bound to the computer name.
2. Configure a secure WinRM HTTPS listener on port 5986.

The DSC YAML files are covered in detail in the companion post Setting Up WinRM HTTPS Listener with DSC v3 and PowerShell.

Architecture Overview

┌──────────────────────────────────────────────────────┐
│  Bicep deployment (New-AzResourceGroupDeployment)    │
│                                                      │
│  1. Storage Account + container (dsc)                │
│  2. VNet / NSG / NIC / Public IP                     │
│  3. Windows Server 2025 VM                           │
│  4. Run Command: install DSC v3                      │
│  5. Run Command: apply DSC configs from blob         │
└──────────────────────────────────────────────────────┘
          │                        │
          ▼                        ▼
   Azure Blob Storage       VM (after deploy)
   dsc/                     ├─ DSC v3 installed
   ├─ ps-script-            ├─ Self-signed cert
   │  certificate.          │  in LocalMachine\My
   │  dsc.yaml              └─ WinRM HTTPS :5986
   └─ winrm.dsc.yaml

Prerequisites

• Azure CLI or Azure PowerShell installed and authenticated.
• An Azure subscription and a resource group.
• The DSC YAML files locally (or cloned from the companion repository).

Step 1 — Prepare the DSC YAML Documents

The configuration is split into two focused DSC v3 YAML documents. Place both files in a local folder before uploading them.

ps-script-certificate.dsc.yaml

Uses the Microsoft.DSC.Transitional/PowerShellScript resource to generate a self-signed certificate in Cert:\LocalMachine\My if one does not already exist for the current computer name.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json

metadata:
  Microsoft.DSC:
    requiredSecurityContext: current
resources:
  - type: Microsoft.DSC.Transitional/PowerShellScript
    name: CreateSelfSignedCertificate
    properties:
      GetScript: |
          $dnsName = $env:COMPUTERNAME
          $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }

          return @{
              Result = if ($cert) { "Present" } else { "Absent" }
              Thumbprint = if ($cert) { $cert.Thumbprint } else { $null }
          }
      TestScript: |
          $dnsName = $env:COMPUTERNAME
          $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }

          return ($null -ne $cert)
      SetScript: |
        $dnsName = $env:COMPUTERNAME
        $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }
        if (-not $cert) {
            $cert = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation "Cert:\LocalMachine\My" -KeyLength 2048 -HashAlgorithm SHA256
            }
        return @{ Thumbprint = $cert.Thumbprint }

The SetScript returns the certificate thumbprint in the afterState output. The Bicep run command extracts it and forwards it as a parameter to the next document.

winrm.dsc.yaml

Uses native DSC v3 resources (Microsoft.Windows/Registry, Microsoft.Windows/FirewallRuleList, Microsoft.Windows/Service) to write the WSMAN listener registry keys, open port 5986, and ensure the WinRM service is running.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json

metadata:
  Microsoft.DSC:
    requiredSecurityContext: restricted

parameters:
  certThumbprint:
    type: string
    description: Thumbprint of the certificate to use for the WinRM HTTPS listener.
    defaultValue: "341B58BC25D182D844B64BF7FC52D1D751625960"

resources:
- name: WinRM HTTPS listener - Address
  type: Microsoft.Windows/Registry
  properties:
    _exist: true
    keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
    valueName: Address
    valueData:
      String: "*"

- name: WinRM HTTPS listener - Transport
  type: Microsoft.Windows/Registry
  properties:
    _exist: true
    keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
    valueName: Transport
    valueData:
      String: "HTTPS"

- name: WinRM HTTPS listener - Port
  type: Microsoft.Windows/Registry
  properties:
    _exist: true
    keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
    valueName: Port
    valueData:
      DWord: 5986

- name: WinRM HTTPS listener - certThumbprint
  type: Microsoft.Windows/Registry
  properties:
    _exist: true
    keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
    valueName: certThumbprint
    valueData:
      String: "[parameters('certThumbprint')]"

- name: WinRM HTTPS listener - hostname
  type: Microsoft.Windows/Registry
  properties:
    _exist: true
    keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
    valueName: hostname
    valueData:
      String: "[envvar('COMPUTERNAME')]"

- name: WinRM firewall rules
  type: Microsoft.Windows/FirewallRuleList
  properties:
    rules:
      - name: Windows Remote Management (HTTPS-In)
        description: Allow inbound TCP traffic on port 5986 for Windows Remote Management (HTTPS-In).
        applicationName: System
        protocol: 6
        localPorts: '5986'
        direction: Inbound
        action: Allow
        enabled: true
        profiles:
          - Domain
          - Private

- name: WinRM Service
  type: Microsoft.Windows/Service
  properties:
    name: WinRM
    _exist: true
    status: Running
    startType: Automatic

Step 2 — Create the Azure Storage Account and Blob Container

The Bicep template expects the YAML files to be reachable via an HTTPS URL (anonymous read or SAS token). Create a dedicated storage account and container before running the deployment.

Using Azure PowerShell

$rg            = 'demo-dsc-bicep-rg'
$location      = 'West Europe'
$storageName   = 'dscconfigstore'   # must be globally unique
$containerName = 'dsc'

# Create resource group
New-AzResourceGroup -Name $rg -Location $location

# Create storage account (Standard LRS, public blob read enabled)
$sa = New-AzStorageAccount `
    -ResourceGroupName $rg `
    -Name $storageName `
    -Location $location `
    -SkuName Standard_LRS `
    -Kind StorageV2 `
    -AllowBlobPublicAccess $true

# Create container with anonymous blob-level read access
$ctx = $sa.Context
New-AzStorageContainer -Name $containerName -Context $ctx -Permission Blob

Security note: Anonymous public blob access is convenient for demos. For production deployments, disable public access and supply a short-lived SAS token to the Bicep parameters instead.

Step 3 — Upload the DSC YAML Files

Yaml files can be found here: DSC Yaml configurations

$ctx = (Get-AzStorageAccount -ResourceGroupName $rg -Name $storageName).Context

Set-AzStorageBlobContent `
    -File   '.\ps-script-certificate.dsc.yaml' `
    -Container $containerName `
    -Blob   'ps-script-certificate.dsc.yaml' `
    -Context $ctx `
    -Force

Set-AzStorageBlobContent `
    -File   '.\winrm.dsc.yaml' `
    -Container $containerName `
    -Blob   'winrm.dsc.yaml' `
    -Context $ctx `
    -Force

Note the blob base URL — you will need it in the next step:

https://<your-storage-account>.blob.core.windows.net/dsc/

Step 4 — Review and Update main.bicep

The full Bicep template provisions the network stack, the VM, and two Microsoft.Compute/virtualMachines/runCommands resources that install DSC v3 and apply the configuration.

Update the blob URLs

Locate the runCommandsApplyDSC resource in main.bicep and replace the placeholder URLs with your actual storage account blob URLs:

Bicep code main:

# Replace with your storage account url

$contentYamlCert = Invoke-RestMethod -Uri "https://<your-storage-account>.blob.core.windows.net/dsc/ps-script-certificate.dsc.yaml"

# Replace with your storage account url

$contentYamlWinrm = Invoke-RestMethod -Uri "https://<your-storage-account>.blob.core.windows.net/dsc/winrm.dsc.yaml"

Step 5 — Deploy with Bicep

Bicep main file for this example with all steps can be found here: bicep-demo-dsc

$exampleRG    = 'demo-dsc-bicep-rg'
$adminUser    = 'godmode'
$location     = 'West Europe'

New-AzResourceGroup -Name $exampleRG -Location $location

New-AzResourceGroupDeployment `
    -ResourceGroupName $exampleRG `
    -TemplateFile      ./main.bicep `
    -adminUsername     $adminUser `
    -Verbose

You will be prompted for adminPassword (minimum 12 characters).

How It Works — Run Command Walk-through

Run Command 1: DSC-Install

Downloads the DSC v3 ZIP from the GitHub releases page, extracts it to C:\Program Files\DSC\<version>, and adds the directory to the system PATH.

Key parameters passed from Bicep:

The download URL is constructed as:

https://github.com/PowerShell/DSC/releases/download/v<version>/DSC-<version>-<arch>.zip

Bicep code:

resource runCommandsInstallDSC 'Microsoft.Compute/virtualMachines/runCommands@2025-11-01' = {
  parent: vm
  name: 'DSC-Install'
  location: location
  properties: {
    timeoutInSeconds: 900
    treatFailureAsDeploymentFailure: true
    parameters: [
      {
        name: 'dscVersion'
        value: '3.2.0'
      }
      {
        name: 'dscArch'
        value: 'x86_64-pc-windows-msvc'
      }

    ]
    source: {
      script: '''
          #Requires -RunAsAdministrator

          param(
              [string]$dscVersion,
              [string]$dscArch
          )
          $downloadUrl = "https://github.com/PowerShell/DSC/releases/download/v$dscVersion/DSC-$dscVersion-$dscArch.zip"
          $installDir  = "C:\Program Files\DSC\$dscVersion"
          $zipPath     = Join-Path $env:TEMP "DSC-$dscVersion-$dscArch.zip"
          $logPath     = Join-Path $env:TEMP "DSC-$dscVersion-install_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

          $ProgressPreference = 'SilentlyContinue'

          function Write-Log {
              param([string]$Message, [ValidateSet('INFO','WARN','ERROR')]$Level = 'INFO')
              $entry = "[$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')] [$Level] $Message"
              Write-Host $entry
              Add-Content -Path $logPath -Value $entry
          }

          Write-Log "Log file: $logPath"
          Write-Log "Install directory: $installDir"
          Write-Log "Download URL: $downloadUrl"

          # Download
          Write-Log "Downloading DSC v$dscVersion..."
          try {
              Invoke-WebRequest -Uri $downloadUrl -OutFile $zipPath -UseBasicParsing
              Write-Log "Download completed: $zipPath"
          } catch {
              Write-Log "Download failed: $_" -Level ERROR
              exit 1
          }

          # Extract
          if (-not (Test-Path $installDir)) {
              New-Item -ItemType Directory -Path $installDir -Force | Out-Null
              Write-Log "Created directory: $installDir"
          }
          Write-Log "Extracting to $installDir..."
          try {
              Expand-Archive -Path $zipPath -DestinationPath $installDir -Force
              Write-Log "Extraction completed."
          } catch {
              Write-Log "Extraction failed: $_" -Level ERROR
              exit 1
          }

          # Add to system PATH if not already present
          $currentPath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
          if ($currentPath -split ';' -notcontains $installDir) {
              Write-Log "Adding $installDir to system PATH..."
              [Environment]::SetEnvironmentVariable('Path', "$currentPath;$installDir", 'Machine')
              Write-Log "System PATH updated. Restart your shell to apply changes."
          } else {
              Write-Log "$installDir is already in the system PATH." -Level WARN
          }

          # Cleanup temp file
          Remove-Item -Path $zipPath -Force
          Write-Log "Removed temporary file: $zipPath"

          Write-Log "DSC v$dscVersion installed successfully."
          Write-Log "Full log saved to: $logPath"

      '''

    }
  }
}

Run Command 2: DSC-Configuration

Runs after DSC-Install (dependsOn). It:

1. Adds the DSC install directory to the current session PATH so dsc.exe resolves immediately.
2. Downloads ps-script-certificate.dsc.yaml from Blob Storage and pipes it to dsc config set --file -, capturing the JSON output.
3. Extracts the certificate thumbprint from the DSC afterState output.
4. Builds an inline parameters JSON block containing the thumbprint.
5. Downloads winrm.dsc.yaml and applies it with dsc config --parameters <json> set --file -.

resource runCommandsApplyDSC 'Microsoft.Compute/virtualMachines/runCommands@2025-11-01' = {
  parent: vm
  name: 'DSC-Configuration'
  location: location
  properties: {
    timeoutInSeconds: 900
    treatFailureAsDeploymentFailure: true
    parameters: [
      {
        name: 'dscInstallDir'
        value: '3.2.0'
      }
    ]
    source: {
      script: '''

        param(
          [string]$dscInstallDir
        )

        $dscInstallDir = "C:\Program Files\DSC\$dscInstallDir"
        Write-Host "DSC for certificate "

        # Add DSC install dir to current user PATH if not already present
        $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
        if ($userPath -split ';' -notcontains $dscInstallDir) {
            [Environment]::SetEnvironmentVariable('Path', "$userPath;$dscInstallDir", 'User')
            Write-Host "Added $dscInstallDir to user PATH."
        }
        # Also update the current session so dsc.exe is resolvable immediately
        if ($env:PATH -split ';' -notcontains $dscInstallDir) {
            $env:PATH = "$env:PATH;$dscInstallDir"
        }


        $contentYamlCert = Invoke-RestMethod -Uri "https://<your-storage-account>.blob.core.windows.net/dsc/ps-script-certificate.dsc.yaml"
        $result = $contentYamlCert | dsc config set --file - --output-format pretty-json
        $result = $result | ConvertFrom-Json

        $thumbprint = if ($result.results.result.afterState.output -is [System.Array]) {
            $result.results.result.afterState.output[0].Thumbprint
        } else {
            $result.results.result.afterState.output.Thumbprint
        }

        if (-not $thumbprint) {
            throw "Thumbprint was not found in DSC output."
        }


        Write-Host "DSC for certificate Thumbprint: " $thumbprint

        $inlineParams = @{
            parameters = @{
                certThumbprint = $thumbprint
            }
        } | ConvertTo-Json

        # dsc config --parameters $inlineParams get --file .\winrm.dsc.yaml
        # dsc config --parameters $inlineParams test --file .\winrm.dsc.yaml

        Write-Host "DSC - winrm HTTPS setup"

        $contentYamlWinrm = Invoke-RestMethod -Uri "https://<your-storage-account>.blob.core.windows.net/dsc/winrm.dsc.yaml"

        $contentYamlWinrm | dsc config --parameters $inlineParams set --file -


      '''

    }
  }
  dependsOn: [
    runCommandsInstallDSC
  ]
}

Verifying the Result

After the deployment completes, RDP into the VM and run:

# Check WinRM listener
Get-WSManInstance -ResourceURI winrm/config/listener -Enumerate

# Confirm the HTTPS listener is present
winrm enumerate winrm/config/listener

You should see an HTTPS listener on port 5986 with the thumbprint of the self-signed certificate.

Summary

This pattern is composable: swap the YAML documents for any other DSC v3 configuration and the same Bicep skeleton handles the bootstrap and delivery.

Related Posts

• Setting Up WinRM HTTPS Listener with DSC v3 and PowerShell
• How to Use AzureDevOpsDscv3 in Azure DevOps Pipelines

References

• Microsoft DSCv3 Github
• DSC community Github
• Blog code examples Github

Setting Up a WinRM HTTPS Listener with DSC v3 and PowerShell

Introduction

Windows Remote Management (WinRM) is the Microsoft implementation of the WS-Management protocol. By default WinRM operates over HTTP on port 5985 — adequate for internal lab environments, but not suitable for production. Enabling the HTTPS listener on port 5986 encrypts the entire management channel using TLS and requires a certificate bound to the listener.

Configuring this manually involves multiple steps: creating or importing a certificate, writing registry values under a dynamically named GUID key, opening the firewall, and ensuring the WinRM service is running. One missed step means the listener is broken or insecure.

This post automates the whole process with Microsoft DSC v3 — a standalone, declarative engine that applies YAML configuration documents and supports native Windows resources out of the box.

Solution Overview

The configuration is split into two focused DSC YAML documents and one PowerShell orchestrator:

The split is intentional: the certificate step runs under the current security context (the default), while the WinRM registry and firewall configuration requires an elevated (restricted) security context.

Prerequisites

DSC v3 installed:

winget install --id Microsoft.DSC

Verify resources are available:

dsc resource list Microsoft.Windows/Registry
dsc resource list Microsoft.Windows/FirewallRuleList
dsc resource list Microsoft.Windows/Service
dsc resource list Microsoft.DSC.Transitional/PowerShellScript

Phase 1 — Create the Self-Signed Certificate

ps-script-certificate.dsc.yaml

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json

metadata:
  Microsoft.DSC:
    requiredSecurityContext: current

resources:
  - type: Microsoft.DSC.Transitional/PowerShellScript
    name: CreateSelfSignedCertificate
    properties:
      GetScript: |
          $dnsName = $env:COMPUTERNAME
          $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }

          return @{
              Result = if ($cert) { "Present" } else { "Absent" }
              Thumbprint = if ($cert) { $cert.Thumbprint } else { $null }
          }
      TestScript: |
          $dnsName = $env:COMPUTERNAME
          $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }

          return ($null -ne $cert)
      SetScript: |
        $dnsName = $env:COMPUTERNAME
        $cert = Get-ChildItem Cert:\LocalMachine\My |
              Where-Object {
                  $_.Subject -eq "CN=$dnsName"
              }
        if (-not $cert) {
            $cert = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation "Cert:\LocalMachine\My" -KeyLength 2048 -HashAlgorithm SHA256
            }
        return @{ Thumbprint = $cert.Thumbprint }

Resource: Microsoft.DSC.Transitional/PowerShellScript

This is a transitional resource — a bridge between DSC v3’s native model and imperative PowerShell logic. It implements the three-method contract that every DSC resource must expose:

Note: requiredSecurityContext: current means this document can be applied by any user context. Creating a certificate in Cert:\LocalMachine\My still requires administrative rights in practice, but the DSC security context flag here is set to current since the operation does not touch system-wide WinRM configuration.

Phase 2 — Configure the WinRM HTTPS Listener

winrm.dsc.yaml

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json

metadata:
  Microsoft.DSC:
    requiredSecurityContext: restricted

parameters:
  certThumbprint:
    type: string
    description: Thumbprint of the certificate to use for the WinRM HTTPS listener.
    defaultValue: "341B58BC25D182D844B64BF7FC52D1D751625960"

resources:

  - name: WinRM HTTPS listener - Address
    type: Microsoft.Windows/Registry
    properties:
      _exist: true
      keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
      valueName: Address
      valueData:
        String: "*"

  - name: WinRM HTTPS listener - Transport
    type: Microsoft.Windows/Registry
    properties:
      _exist: true
      keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
      valueName: Transport
      valueData:
        String: "HTTPS"

  - name: WinRM HTTPS listener - Port
    type: Microsoft.Windows/Registry
    properties:
      _exist: true
      keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
      valueName: Port
      valueData:
        DWord: 5986

  - name: WinRM HTTPS listener - certThumbprint
    type: Microsoft.Windows/Registry
    properties:
      _exist: true
      keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
      valueName: certThumbprint
      valueData:
        String: "[parameters('certThumbprint')]"

  - name: WinRM HTTPS listener - hostname
    type: Microsoft.Windows/Registry
    properties:
      _exist: true
      keyPath: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\*+HTTPS
      valueName: hostname
      valueData:
        String: "[envvar('COMPUTERNAME')]"

  - name: WinRM firewall rules
    type: Microsoft.Windows/FirewallRuleList
    properties:
      rules:
        - name: Windows Remote Management (HTTPS-In)
          description: Allow inbound TCP traffic on port 5986 for WinRM HTTPS.
          applicationName: System
          protocol: 6
          localPorts: '5986'
          direction: Inbound
          action: Allow
          enabled: true
          profiles:
            - Domain
            - Private

  - name: WinRM Service
    type: Microsoft.Windows/Service
    properties:
      name: WinRM
      _exist: true
      status: Running
      startType: Automatic

Resource: Microsoft.Windows/Registry

The Registry resource is DSC v3’s native way to manage Windows registry keys and values. Each instance targets one specific value.

WinRM stores its listener configuration under:

HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN\Listener\<GUID>+HTTPS

The <GUID> portion is generated randomly when the listener is first created and is not predictable. DSC v3’s Registry resource supports the * wildcard in keyPath, so *+HTTPS matches the listener key regardless of its GUID, making the configuration portable across machines.

Key properties used across all five Registry resource instances:

Values configured:

Notice two DSC v3 expression functions in use:

• [parameters('certThumbprint')] — resolves the certThumbprint parameter, which is supplied at runtime from the orchestrator script.
• [envvar('COMPUTERNAME')] — reads the COMPUTERNAME environment variable at apply time, making the configuration self-adapting to any machine.

Resource: Microsoft.Windows/FirewallRuleList

The FirewallRuleList resource manages one or more Windows Firewall rules as a single unit. It maps directly to Windows Defender Firewall rules and supports both creating new rules and enforcing the desired state of existing ones.

- name: WinRM firewall rules
  type: Microsoft.Windows/FirewallRuleList
  properties:
    rules:
      - name: Windows Remote Management (HTTPS-In)
        description: Allow inbound TCP traffic on port 5986 for WinRM HTTPS.
        applicationName: System
        protocol: 6        # TCP
        localPorts: '5986'
        direction: Inbound
        action: Allow
        enabled: true
        profiles:
          - Domain
          - Private

Key fields:

The Public profile is intentionally excluded — exposing WinRM on public networks is a security risk.

Resource: Microsoft.Windows/Service

The Service resource ensures the WinRM Windows service is running and set to start automatically:

- name: WinRM Service
  type: Microsoft.Windows/Service
  properties:
    name: WinRM
    _exist: true
    status: Running
    startType: Automatic

Security Context: restricted

winrm.dsc.yaml declares requiredSecurityContext: restricted, which is the default and signals that the configuration must be applied by an elevated (administrative) process. Writing to HKLM, creating firewall rules, and managing services all require administrator rights — the security context declaration makes this requirement explicit and prevents accidental application from a non-elevated shell.

Orchestrator: winrm.ps1

The PowerShell script ties both documents together. It:

1. Applies the certificate configuration and extracts the thumbprint from the DSC output
2. Passes the thumbprint as an inline parameter to the WinRM listener configuration

Write-Host "DSC for certificate"

$result = dsc config set --file .\ps-script-certificate.dsc.yaml --output-format pretty-json | ConvertFrom-Json -Depth 20

$thumbprint = if ($result.results.result.afterState.output -is [System.Array]) {
    $result.results.result.afterState.output[0].Thumbprint
} else {
    $result.results.result.afterState.output.Thumbprint
}

if (-not $thumbprint) {
    throw "Thumbprint was not found in DSC output."
}

Write-Host "Certificate thumbprint: $thumbprint"

$inlineParams = @{
    parameters = @{
        certThumbprint = $thumbprint
    }
} | ConvertTo-Json

Write-Host "DSC - WinRM HTTPS setup"

dsc config --parameters $inlineParams set --file .\winrm.dsc.yaml

Key points:

• dsc config set --output-format pretty-json returns structured JSON, including the afterState for each resource. The PowerShellScript resource returns the SetScript output in .results.result.afterState.output.
• The thumbprint is extracted by checking whether the output is an array (multiple results) or a single object, making the extraction robust.
• The inline parameters JSON is passed via dsc config --parameters <json> which injects it at runtime, replacing [parameters('certThumbprint')] in the YAML.
• A guard (throw) stops execution immediately if the thumbprint is missing rather than proceeding with an empty value.

Applying the Configuration

Run the orchestrator from the directory containing all three files:

# Test only — no changes applied
dsc config test --file .\ps-script-certificate.dsc.yaml

# Full apply
.\winrm.ps1

To verify the listener was created:

winrm enumerate winrm/config/listener

Get-ChildItem WSMan:\localhost\Listener

Expected output should include a listener with Transport = HTTPS and Port = 5986.

To test the connection from a remote machine:

Test-WSMan -ComputerName <hostname> -UseSSL

Summary

DSC v3 makes this multi-step process repeatable, auditable, and idempotent. The split between certificate creation and listener configuration, the use of [parameters()] and [envvar()] expressions, and the requiredSecurityContext declaration together produce a configuration that is both portable and security-aware.

References

• DSC v3 documentation
• Microsoft.Windows/Registry resource
• Microsoft.Windows/Service resource
• Microsoft.Windows/FirewallRuleList resource

• WinRM HTTPS setup — Microsoft Docs

• Microsoft DSCv3 Github
• DSC community Github
• Blog code examples Github

Deploying Active Directory with Microsoft DSC v3 — A Configuration-as-Code Approach

Introduction

Microsoft Desired State Configuration (DSC) v3 is a cross-platform, declarative configuration management engine built in Rust. Unlike its PowerShell-based predecessors (DSC v1 and v2), DSC v3 is a standalone binary (dsc.exe) that orchestrates resources defined in YAML documents. It supports the full PowerShell DSC adapter ecosystem, enabling teams to configure Windows infrastructure — including Active Directory — using pure YAML files.

This post walks through a complete, modular Active Directory deployment built on DSC v3, covering every configuration file, parameter file, and the commands used to apply them.

Why DSC v3 for Active Directory?

Traditional AD deployment relies on PowerShell scripts or manual steps that are difficult to audit, version, and reproduce. DSC v3 brings:

• Declarative YAML — describe what you want, not how to do it
• Idempotency — running the same configuration multiple times produces the same result
• Modularity — split large configurations into focused, reusable include files
• Parameter separation — keep environment-specific values (domain names, passwords) out of the configuration files
• Built-in dependency management — dependsOn ensures resources are applied in the correct order

Prerequisites

Before running any configuration, ensure the following are in place on the target Domain Controller:

Search DSC v3:

winget search DesiredStateConfiguration
Name                              Id            Version Match                          Source
----------------------------------------------------------------------------------------------
DesiredStateConfiguration         9NVTPZWRC6KQ  Unknown                                msstore
DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z  Unknown                                msstore
DSC v3                            Microsoft.DSC 3.2.0   Tag: desiredstateconfiguration winget

Install DSC v3:

winget install --id 9PCX3HX4HZ0Z --source msstore

Install the ActiveDirectoryDsc PowerShell module:

Install-Module -Name ActiveDirectoryDsc -Repository PSGallery -Force

Verify DSC v3 is available and can discover resources:

dsc resource list

Project File Structure

The configuration is split into a layered directory structure to separate concerns:

config/ADS/
├── ads-root-forest.dsc.yaml          # Stage 1 – Forest/domain creation
├── ads-root.dsc.parameters.yaml      # Parameters for root forest deployment
├── ads-child-forest.dsc.yaml         # Stage 1 (optional) – Child domain creation
│
└── ADS-Include/
    ├── ads.main.dsc.yaml             # Stage 2 – Orchestrator (Include entries)
    │
    ├── config/
    │   ├── ads.ou.dsc.yaml           # OU hierarchy definition
    │   ├── ads.admin-users.dsc.yaml  # Administrative user accounts
    │   ├── ads.groups.dsc.yaml       # Delegation security groups
    │   ├── ads.groups-members.dsc.yaml    # Group membership assignments
    │   ├── ads.ou-delegation.dsc.yaml     # OU permission entries (ACLs)
    │   └── ads.finegrained-password-policy.dsc.yaml  # PSO policies
    │
    └── parameters/
        ├── ads.parameters.yaml            # Domain root path parameter
        └── ads.admin-user.parameters.yaml # Admin user credentials

Stage 1 — Forest and Domain Creation

ads-root-forest.dsc.yaml

This is the entry point for bringing up the first domain controller. It installs the required Windows features and then creates the AD forest using ActiveDirectoryDsc/ADDomain.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-root-forest-configuration
  version: 1.0.0
  description: Global Active Directory configuration for forest and domain creation
  Microsoft.DSC:
    requiredSecurityContext: current

parameters:
  SafemodeAdministratorPassword:
    type: secureObject
  Credential:
    type: secureObject
  DomainName:
    type: string
    defaultValue: contoso.com
  DomainNetBiosName:
    type: string
    defaultValue: contoso
  ForestMode:
    type: string
    defaultValue: WinThreshold   # Win2008, Win2008R2, Win2012, Win2012R2, WinThreshold, Win2025
  SuppressReboot:
    type: bool
    defaultValue: true
resources:
  - name: Windows Features Install ADS
    type: PSDesiredStateConfiguration/WindowsFeature
    properties:
      ensure: Present
      name: AD-Domain-Services
  - name: Windows Features Install ADS RSAT
    type: PSDesiredStateConfiguration/WindowsFeature
    properties:
      ensure: Present
      name: RSAT-AD-PowerShell
  - name: Windows Features Install AD DS Tools
    type: PSDesiredStateConfiguration/WindowsFeature
    properties:
      ensure: Present
      name: RSAT-ADDS
      IncludeAllSubFeature: true
  - name: Active Directory Forest
    type: ActiveDirectoryDsc/ADDomain
    properties: 
      DomainName: "[parameters('DomainName')]"
      DomainNetBiosName: "[parameters('DomainNetBiosName')]"
      SafemodeAdministratorPassword: "[parameters('SafemodeAdministratorPassword')]"
      Credential: "[parameters('Credential')]"
      ForestMode: "[parameters('ForestMode')]"
      SuppressReboot: "[parameters('SuppressReboot')]" # no reboot rquired
    dependsOn: 
      - "[resourceId('PSDesiredStateConfiguration/WindowsFeature','Windows Features Install ADS')]"
      - "[resourceId('PSDesiredStateConfiguration/WindowsFeature','Windows Features Install ADS RSAT')]"
      - "[resourceId('PSDesiredStateConfiguration/WindowsFeature','Windows Features Install AD DS Tools')]"

Key resources:

The ADDomain resource depends on all three WindowsFeature resources, so DSC applies them in sequence automatically.

ads-root.dsc.parameters.yaml — supplies the sensitive values at runtime, keeping them out of the configuration file:

parameters:
  Credential:
    username: AdminTest
    password: Password
  SafemodeAdministratorPassword:
    username: AdminTest
    password: AdminTest
  DomainName: contoso.com
  DomainNetBiosName: contoso

Security note: In Organization, replace plain-text passwords with secrets retrieved from Azure Key Vault or a secrets manager. Never commit credential files to source control.

Deploy command:

dsc config set `
  --parameters-file .\ads-root.dsc.parameters.yaml `
  --file .\ads-root-forest.dsc.yaml

ads-child-forest.dsc.yaml

Used when adding a child domain to an existing forest. The structure mirrors the root forest file but adds DomainType and DomainMode parameters:

parameters:
  DomainType:
    type: string
    defaultValue: ChildDomain   # TreeDomain or ChildDomain
  DomainMode:
    type: string
    defaultValue: WinThreshold

This allows the same pattern to deploy both root and child domains by varying the parameters.

Stage 2 — AD Structure with Include-Based Orchestration

Once the domain exists, the second stage configures its internal structure. Rather than one monolithic YAML, the project uses the Microsoft.DSC/Include resource type to compose smaller, focused files.

ADS-Include/ads.main.dsc.yaml

This is the single entry point for Stage 2. It does nothing itself — it delegates to six sub-configurations via Include, order of deployment is base on yaml files:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:

# Deploy in order 

- name: Active Directory Ou structure
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.ou.dsc.yaml
    parametersFile: parameters\ads.parameters.yaml

- name: Active Directory Administrative User
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.admin-users.dsc.yaml
    parametersFile: parameters\ads.admin-user.parameters.yaml

- name: Active Directory Groups Management
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.groups.dsc.yaml
    parametersFile: parameters\ads.parameters.yaml

- name: Active Directory Groups Membership
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.groups-members.dsc.yaml

- name: Active Directory Groups OU Delegation
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.ou-delegation.dsc.yaml
    parametersFile: parameters\ads.parameters.yaml

- name: Active Directory Password Policy
  type: Microsoft.DSC/Include
  properties:
    configurationFile: config\ads.finegrained-password-policy.dsc.yaml
    parametersFile: parameters\ads.parameters.yaml

The Microsoft.DSC/Include resource loads an external configuration file and optionally merges a parameters file into it before execution. This pattern is the key to keeping each concern in its own file without repeating boilerplate.

Sub-Configuration Files

config/ads.ou.dsc.yaml — Organizational Unit Hierarchy

Defines the entire OU tree under the domain root. The structure follows a tiered model:

Organization (root)
├── Accounts
│   ├── Users
│   ├── Users.NoSync
├── Devices
│   └── Servers
│       ├── Tier0
│       ├── Tier1
│       └── Tier2
│   └── Computers
└── Groups
    ├── Delegation
    └── Distribution

Each OU uses ActiveDirectoryDsc/ADOrganizationalUnit and declares its parent via dependsOn, using the resourceId() function to reference sibling resources:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-groups-ou-configuration
  version: 1.0.0
  description: Active Directory configuration of defualt groups
  Microsoft.DSC:
    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins

parameters:
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
resources:

- name: Active Directory Root Organizational Unit
  type: ActiveDirectoryDsc/ADOrganizationalUnit
  properties: 
    Name: Organization
    Path: "[parameters('DomainRootPath')]"
    Description: "Organization OU for All organizational objects"
    ProtectedFromAccidentalDeletion: true
    ensure: Present


- name: Active Directory Accounts Organizational Unit
  type: ActiveDirectoryDsc/ADOrganizationalUnit
  properties:
    Name: Accounts
    Path: "[concat('OU=Organization,', parameters('DomainRootPath'))]"
    Description: "Accounts OU for all user and service accounts"
    ProtectedFromAccidentalDeletion: true
    ensure: Present
    dependsOn:
      - "[resourceId('ActiveDirectoryDsc/ADOrganizationalUnit','Active Directory Root Organizational Unit')]"

- name: Active Directory Users Organizational Unit
  type: ActiveDirectoryDsc/ADOrganizationalUnit
  properties: 
    Name: Users
    Path: "[concat('OU=Accounts,','OU=Organization,', parameters('DomainRootPath'))]"
    Description: "OU for Users accounts that can be synchonized to Microsoft 365 or used for on-premises authentication"
    ProtectedFromAccidentalDeletion: true
    ensure: Present
    dependsOn: 
      - "[resourceId('ActiveDirectoryDsc/ADOrganizationalUnit','Active Directory Accounts Organizational Unit')]"

The concat() function builds the LDAP path dynamically from the DomainRootPath parameter, making the file fully portable across domains.

All OUs have ProtectedFromAccidentalDeletion: true set to prevent inadvertent removal.

config/ads.admin-users.dsc.yaml — Administrative User Accounts

Creates privileged user accounts and places them in the correct OU:

parameters:
  DomainName:
    type: string
    defaultValue: "contoso.com"
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
  Password:
    type: secureObject

The Password parameter is typed as secureObject, meaning it accepts a { username, password } structure without exposing the value in logs. The user is placed in OU=Users.Special.NoSync — the dedicated OU for privileged accounts that must not synchronize to Microsoft 365:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-admin-users-configuration
  version: 1.0.0
  description: Active Directory configuration for administrative user
  Microsoft.DSC:
    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins

parameters:
  DomainName:
    type: string
    defaultValue: "contoso.com"
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
  Password:
    type: secureObject
resources:
- name: Active Directory admin - michal.mmachniak
  type: ActiveDirectoryDsc/ADUser
  properties:
    Ensure: Present
    UserName: michal.mmachniak
    CommonName: "Michal Machniak"
    UserPrincipalName: "[concat('michal.mmachniak@', parameters('DomainName'))]"
    Password: "[parameters('Password')]"
    Path: "[concat('OU=Users.Special.NoSync,OU=Accounts,OU=Organization,', parameters('DomainRootPath'))]"
    PasswordNeverResets: true # Each deployment won't setup new password

parameters/ads.admin-user.parameters.yaml provides the runtime values for this config:

parameters:
  Password:
    username: admin
    password: P@SSWord!@!
  DomainRootPath: "DC=contoso,DC=com"
  DomainName: "contoso.com"

config/ads.groups.dsc.yaml — Delegation Security Groups

Creates Universal Security Groups in the OU=Delegation,OU=Groups,OU=Organization container. Each group corresponds to a delegation scope on a specific OU:

All groups follow the same pattern:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-groups-ou-configuration
  version: 1.0.0
  description: Active Directory configuration of defualt groups
  Microsoft.DSC:
    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins

parameters:
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
resources:

- name: Active Directory Organization OU
  type: ActiveDirectoryDsc/ADGroup
  properties:
    GroupName: OU-Organization-FullControl
    GroupScope: Universal
    Category: Security
    Description: Delegation group for OU Organization with full control permissions
    Path: "[concat('OU=Delegation,OU=Groups,OU=Organization,', parameters('DomainRootPath'))]"
    Ensure: Present

Using Universal scope allows these groups to work across trusts in multi-domain forest scenarios.

config/ads.groups-members.dsc.yaml — Group Membership

Assigns accounts to groups using MembersToInclude, which is additive and non-destructive (it does not remove existing members):

- name: Active Directory - Domain Admins group membership
  type: ActiveDirectoryDsc/ADGroup
  properties:
    GroupName: Domain Admins
    Ensure: Present
    MembersToInclude:
      - michal.mmachniak

This config intentionally has no parameters file — the group names and member accounts are static by design for privileged group membership, reducing the risk of accidental misconfiguration.

config/ads.ou-delegation.dsc.yaml — OU Permission Entries

Applies ACLs to OUs using ActiveDirectoryDsc/ADObjectPermissionEntry. Each entry grants the corresponding delegation group the required access:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-groups-ou-configuration
  version: 1.0.0
  description: Active Directory configuration for organizational units delegations
  Microsoft.DSC:
    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins

parameters:
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
resources:

# This configuration defines a security group for delegating permissions on the Organization OU in Active Directory. The group is created with full control permissions on the OU, allowing members of the group to manage the OU and its contents effectively.


  - name: Active Directory Organization OU Delegation Group Permissions
    type: ActiveDirectoryDsc/ADObjectPermissionEntry
    properties: 
      Ensure: Present
      Path: "[concat('OU=Organization,', parameters('DomainRootPath'))]"
      IdentityReference: OU-Organization-FullControl
      ActiveDirectoryRights: 
        - GenericAll
      AccessControlType: Allow
      ObjectType: 00000000-0000-0000-0000-000000000000
      ActiveDirectorySecurityInheritance: Descendents
      InheritedObjectType: 00000000-0000-0000-0000-000000000000

# This configuration defines a security group for delegating permissions on the Organization-Accounts OU in Active Directory. The group is created with full control permissions on the OU, allowing members of the group to manage user accounts and other objects within the OU effectively.


  - name: Active Directory Organization-Accounts OU Delegation Group Permissions Descendents
    type: ActiveDirectoryDsc/ADObjectPermissionEntry
    properties: 
      Ensure: Present
      Path: "[concat('OU=Accounts,OU=Organization,', parameters('DomainRootPath'))]"
      IdentityReference: OU-Organization-Accounts-RWD
      ActiveDirectoryRights: 
        - GenericAll
      AccessControlType: Allow
      ObjectType: 00000000-0000-0000-0000-000000000000
      ActiveDirectorySecurityInheritance: Descendents
      InheritedObjectType: User # User"


  - name: Active Directory Organization-Accounts-Users OU Delegation Group Permissions Descendents
    type: ActiveDirectoryDsc/ADObjectPermissionEntry
    properties: 
      Ensure: Present
      Path: "[concat('OU=Users,OU=Accounts,OU=Organization,', parameters('DomainRootPath'))]"
      IdentityReference: OU-Organization-Accounts-Users-RWD
      ActiveDirectoryRights: 
        - GenericAll
      AccessControlType: Allow
      ObjectType: 00000000-0000-0000-0000-000000000000
      ActiveDirectorySecurityInheritance: Descendents
      InheritedObjectType: User # User

      ## User.NoSync

  - name: Active Directory Organization-Accounts-Users.NoSync OU Delegation Group Permissions Descendents
    type: ActiveDirectoryDsc/ADObjectPermissionEntry
    properties: 
      Ensure: Present
      Path: "[concat('OU=Users.NoSync,OU=Accounts,OU=Organization,', parameters('DomainRootPath'))]"
      IdentityReference: OU-Organization-Accounts-Users.NoSync-RWD
      ActiveDirectoryRights: 
        - GenericAll
      AccessControlType: Allow
      ObjectType: 00000000-0000-0000-0000-000000000000
      ActiveDirectorySecurityInheritance: Descendents
      InheritedObjectType: User # User

      
# Computer objects in the Organization-Devices OU are delegated to a security group with permissions to manage computer accounts and other objects within the OU effectively.

  - name: Active Directory Organization-Devices OU Delegation Group Permissions
    type: ActiveDirectoryDsc/ADObjectPermissionEntry
    properties: 
      Ensure: Present
      Path: "[concat('OU=Devices,OU=Organization,', parameters('DomainRootPath'))]"
      IdentityReference: OU-Organization-Devices-RWD
      ActiveDirectoryRights: 
        - GenericAll
      AccessControlType: Allow
      ObjectType: 00000000-0000-0000-0000-000000000000
      ActiveDirectorySecurityInheritance: Descendents
      InheritedObjectType: Computer # Computer objects


   

For granular OUs (like Users, Users.NoSync), the InheritedObjectType is set to User, restricting the ACE to apply only to user object descendants:

ActiveDirectorySecurityInheritance: Descendents
InheritedObjectType: User

This enforces the principle of least privilege — delegation group members can only manage user objects in their designated OU subtree.

config/ads.finegrained-password-policy.dsc.yaml — Fine-Grained Password Policies

Applies Password Settings Objects (PSOs) to privileged groups, enforcing stricter password rules than the default domain policy:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  name: ads-finegrained-password-policy-configuration
  version: 1.0.0
  description: Active Directory configuration for AD FineGrained Password Policy
  Microsoft.DSC:
    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins

parameters:
  DomainRootPath:
    type: string
    defaultValue: "DC=contoso,DC=com"
resources:

  - name: Active Directory ADFineGrainedPasswordPolicy - Domain Admins
    type: ActiveDirectoryDsc/ADFineGrainedPasswordPolicy
    properties: 
      Name: 'DomainAdmins'
      DisplayName: 'Domain Admins Password Policy'
      Description: 'This is the Fine Grained Password Policy for Domain Admins'
      Subjects: 
        - Domain Admins
      ComplexityEnabled: true
      LockoutDuration: '00:30:00'
      LockoutObservationWindow: '00:30:00'
      LockoutThreshold: 5
      MaxPasswordAge: '90.00:00:00'
      MinPasswordAge: '1.00:00:00'
      MinPasswordLength: 15
      PasswordHistoryCount: 6
      ReversibleEncryptionEnabled: false
      ProtectedFromAccidentalDeletion: true
      Precedence: 10

  - name: Active Directory ADFineGrainedPasswordPolicy - Enterprise Admins
    type: ActiveDirectoryDsc/ADFineGrainedPasswordPolicy
    properties: 
      Name: 'EnterpriseAdmins'
      DisplayName: 'Enterprise Admins Password Policy'
      Description: 'This is the Fine Grained Password Policy for Enterprise Admins'
      Subjects: 
        - Enterprise Admins
      ComplexityEnabled: true
      LockoutDuration: '00:30:00'
      LockoutObservationWindow: '00:30:00'
      LockoutThreshold: 5
      MaxPasswordAge: '90.00:00:00'
      MinPasswordAge: '1.00:00:00'
      MinPasswordLength: 15
      PasswordHistoryCount: 6
      ReversibleEncryptionEnabled: false
      ProtectedFromAccidentalDeletion: true
      Precedence: 11

Two PSOs are defined:

Lower Precedence numbers take priority when multiple PSOs apply to the same user.

Parameter Files

parameters/ads.parameters.yaml

Shared by most sub-configurations to supply the domain LDAP root path:

parameters:
  DomainRootPath: "DC=contoso,DC=com"

parameters/ads.admin-user.parameters.yaml

Provides all values required by the admin users configuration:

parameters:
  Password:
    username: AdminTest
    password: Password
  DomainRootPath: "DC=contoso,DC=com"
  DomainName: "contoso.com"

Deployment Workflow

Step 1 — Validate configuration (dry-run)

Before applying anything, use test mode to see what is out of compliance:

dsc config --parameters-file .\ads-root.dsc.parameters.yaml test `
  --file .\ads-root-forest.dsc.yaml

For the Stage 2 orchestrator:

dsc config --parameters-file .\ADS-Include\parameters\ads.parameters.yaml test `
  --file .\ADS-Include\ads.main.dsc.yaml

Step 2 — Apply Stage 1: Create the forest

Run this on the first server that will become the Domain Controller. The server will be promoted and — if SuppressReboot: false — will reboot automatically.

dsc config --parameters-file .\ads-root.dsc.parameters.yaml set `
  --file .\ads-root-forest.dsc.yaml

Step 3 — Apply Stage 2: Configure AD structure

After the DC is up and the domain is functional, run the main orchestrator from within the ADS-Include directory:

Set-Location .\ADS-Include

dsc config set --file .\ads.main.dsc.yaml

The Include resource resolves configurationFile paths relative to the location of ads.main.dsc.yaml, so the working directory must match.

Step 4 — Enable trace-level logging (troubleshooting)

If any resource fails, enable detailed output with --trace-level:

dsc --trace-level trace config --parameters-file .\parameters\ads.parameters.yaml set `
  --file .\ads.main.dsc.yaml

Available trace levels: error, warn, info, debug, trace

Step 5 — Re-validate after apply

Confirm the configuration converged successfully:

dsc config test --file .\ads.main.dsc.yaml

A fully converged configuration returns InDesiredState: true for every resource.

DSC v3 Concepts Used in This Project

Recommended Execution Checklist

• DSC v3 (dsc.exe) installed and in PATH
• ActiveDirectoryDsc module installed via PSGallery
• Running as a Domain Admin (or local Administrator for Stage 1)
• Passwords in parameter files replaced with vault-sourced values before Organization use
• dsc config test passes cleanly before dsc config set
• Stage 1 (forest creation) completes and DC reboots before running Stage 2
• Stage 2 executed from within the ADS-Include directory

Summary

This project demonstrates how DSC v3 can manage the full lifecycle of an Active Directory environment — from forest creation to a Organization-ready OU structure, delegation model, and password policies — using nothing but declarative YAML files.

The Microsoft.DSC/Include pattern is the architectural cornerstone: it allows each concern (OUs, users, groups, delegation, password policy) to live in its own file while a single orchestrator file (ads.main.dsc.yaml) ties them together. Combined with parameter files, the same set of configurations can target any domain simply by swapping the DomainRootPath and DomainName values.

This approach brings Active Directory configuration into the modern infrastructure-as-code world — auditable, reproducible, and version-controlled.

Links for more resources

• Microsoft DSCv3
• DSC community

This post shows a real-life example for using AzureDevOpsDscv3 inside an Azure DevOps pipeline. The goal is to define Azure DevOps projects, users, and groups as code, then apply the configuration in a controlled pipeline.

Scenario

You are onboarding a new product team. Every environment must have:

• A standard project created from a Git template
• A group created from Entra ID
• A baseline set of users

Instead of clicking in the UI, you use DSC v3 to declare everything, and the pipeline applies it consistently across environments.

Prerequisites

• Azure DevOps organization and a PAT with permissions to manage projects and users
• A self-hosted or Microsoft-hosted Windows agent
• PowerShell 7 and DSC v3 (dsc CLI)
• The AzureDevOpsDscv3 module from the PowerShell Gallery

In the pipeline we will install the required modules, so the agent stays clean and the process is repeatable.

Repository Layout

Example structure you can place in your repo:

.
├─ dsc
│  └─ ado.dsc.yaml
├─ pipelines
│  └─ ado-dsc.yml
└─ README.md

DSC v3 Configuration File

Below is a simplified config that creates a project, adds a user, and links an Entra ID group. Save it as dsc/ado.dsc.yaml.

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
parameters:
	Token:
		type: string
		defaultValue: PAT-Token
resources:
- name: Configure Azure DevOps
	type: Microsoft.Windows/WindowsPowerShell
	properties:
		resources:
		- name: Create project
			type: AzureDevOpsDscv3/ProjectResource
			properties:
				Organization: ExampleOrganization
				ProjectName: Contoso-Platform
				Description: "Project created via DSC v3"
				pat: "[parameters('Token')]"
				SourceControlType: Git
				Ensure: Present
		- name: Add user
			type: AzureDevOpsDscv3/OrganizationUserResource
			properties:
				UserPrincipalName: dev1@contoso.com
				Organization: ExampleOrganization
				AccessLevel: Basic
				Ensure: Present
				pat: "[parameters('Token')]"
		- name: Add group
			type: AzureDevOpsDscv3/OrganizationGroupResource
			properties:
				GroupOriginId: 00000000-0000-0000-0000-000000000000
				GroupDisplayName: Contoso-DevTeam
				Organization: ExampleOrganization
				AccessLevel: Basic
				Ensure: Present
				pat: "[parameters('Token')]"

Notes:

• GroupOriginId is the Entra ID group object ID.
• pat is sourced from the Token parameter, which we inject in the pipeline.

Azure DevOps Pipeline

Create a pipeline YAML file, for example pipelines/ado-dsc.yml.

trigger:
- main

pool:
	vmImage: windows-latest

variables:
- name: DscConfigPath
	value: dsc/ado.dsc.yaml

steps:
- checkout: self

- task: PowerShell@2
	displayName: Install DSC v3 and AzureDevOpsDscv3
	inputs:
		pwsh: true
		targetType: inline
		script: |
			Set-StrictMode -Version Latest
			$ErrorActionPreference = 'Stop'

			#(Note: If you are on a 32-bit system, use .x86 instead).
            winget install Microsoft.VCRedist.2015+.x64 

            # Install latest stable
            winget install --id 9NVTPZWRC6KQ --source msstore
			Install-Module -Name AzureDevOpsDscv3 -Scope CurrentUser -Force
			dsc --version

- task: PowerShell@2
	displayName: Inject PAT and apply configuration
	inputs:
		pwsh: true
		targetType: inline
		script: |
			Set-StrictMode -Version Latest
			$ErrorActionPreference = 'Stop'

			$configPath = "$(DscConfigPath)"
			$tempPath = Join-Path $env:Agent_TempDirectory 'ado.dsc.yaml'

			(Get-Content $configPath -Raw) -replace 'PAT-Token', $env:ADO_PAT | Set-Content $tempPath

			dsc -l debug config set --file $tempPath
	env:
		ADO_PAT: $(ADO_PAT)

Secure the PAT

Create a variable in your Azure DevOps pipeline or a variable group:

• Name: ADO_PAT
• Type: secret

Keep the PAT scoped to the minimum permissions required to manage projects, users, and groups in your organization.

Run the Pipeline

1. Commit the DSC config and pipeline YAML.
2. Create a new pipeline from pipelines/ado-dsc.yml.
3. Run the pipeline.

The pipeline installs the required modules, injects the PAT into the config, and executes dsc config set to apply the desired state.

Real-World Tips

• Store multiple configs per environment and pass the file path as a pipeline parameter.
• Use a dedicated service account for the PAT to keep audit trails clean.
• Add a validation step that runs dsc config get (or dsc resource list) to verify expected resources.
• For production, add a manual approval gate between validation and apply.

Troubleshooting

• If dsc is not found, confirm the Microsoft.PowerShell.DSC module is installed and available in the pwsh session.
• If the pipeline fails to create a project, check the PAT scope and the Azure DevOps organization name.
• For group assignment, verify GroupOriginId is the Entra ID object ID, not the display name.

Closing

This pattern lets you manage Azure DevOps configuration as code with minimal drift. Start small with one project and a few users, then expand to include repos, pipelines, and permissions in a controlled, repeatable way.

Building a well-structured and secure network in Azure is one of the foundational steps toward a successful cloud deployment. Whether you’re migrating workloads, designing new environments, or improving existing infrastructure, Azure networking provides powerful tools to help you design for scalability, performance, and governance.

In this post, we’ll walk through the core principles and best practices for building a network in Azure — from initial planning to advanced connectivity options.

🧭 Start with the Azure Landing Zone Concept

Before diving into subnets and IP ranges, it’s crucial to understand the Azure Landing Zone model.

Microsoft defines an Azure Landing Zone as an environment that implements key design principles across eight design areas — governance, security, identity, networking, operations, management, and more. It ensures that your environment can scale and support multiple applications and workloads consistently.

Platform vs Application Landing Zones

Azure uses subscriptions to isolate and scale resources:

• Platform landing zones host shared services like networking, identity, and monitoring.
• Application landing zones host workloads and apps.

This separation allows for cleaner management boundaries, better security, and easier automation.

🕸️ Designing Your Network Topology

One of the most common approaches for Azure networking is the hub-and-spoke topology.

Hub-and-Spoke Model

In this model:

• The hub is the central network that hosts shared components like firewalls, DNS, or VPN gateways.
• The spokes are individual VNets (Virtual Networks) that connect to the hub and host application workloads.

This approach provides:

• Centralized management of connectivity and security.
• Isolation between applications.
• Easier integration with on-premises networks.

You can also use Azure Virtual Network Manager to create and manage:

• Hub-and-spoke topology
• Mesh topology (in preview)
• Hybrid hub-spoke with direct spoke-to-spoke connectivity

🧱 Planning Your Network

Mapping on-premises network to Azure network

Mapping VLANs to Azure networking depends on how and where you’re connecting Azure to your on-premises or extended network. Azure itself doesn’t use VLANs internally—it uses Virtual Networks (VNets) for segmentation—but VLANs still matter when you’re integrating Azure with your physical or hybrid infrastructure.

• Use subnets within a VNet to logically segment traffic (similar to VLANs).
• Apply Network Security Groups (NSGs) or Azure Firewall rules for isolation.
• VLAN tagging or trunking is not available between Azure VMs or subnets.

Naming Conventions

A consistent naming convention is the foundation of an organized environment.
Follow Microsoft’s Cloud Adoption Framework recommendations for naming standards:

[Cloud Adoption Framework

Microsoft Learn](https://learn.microsoft.com/azure/cloud-adoption-framework/)

IP Addressing

When planning your VNets and subnets, avoid overlapping with your on-premises or partner networks.

Common private address ranges:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 100.64.0.0/10 (shared address space)

Keep subnet masks small, such as /28 or /26, to maintain flexibility and minimize wasted IPs.

Remember:

Azure reserves certain IPs in every subnet:

• .0 — network address
• .1 — default gateway
• .2 and .3 — Azure DNS mapping
• .255 — broadcast address

Subnet nameing and functionality example

Subnet ranges

Tool for to help design your subnets

Visual Subnet Calculator

The Visual Subnet Calculator is a free, browser-based tool designed to assist network administrators and IT professionals in subnetting IPv4 networks.
It offers a straightforward interface to quickly visualize and manage subnets without requiring advanced mathematical calculations.

Visual Subnet Calculator

🔐 Security and Access

Security starts with Network Security Groups (NSGs) is easier to unblock traffic, then setup block rules on production environment.
It’s a best practice to:

• Create custom rules.
• Block all inbound and outbound traffic by default.
• Explicitly allow only what’s required.

🔗 Private Connectivity

When connecting Azure services privately:

• Use Private Link for secure, private access to Azure services like Storage, SQL, and Key Vault.
• Use Private DNS Zones to manage DNS resolution for private endpoints.
  • A single Private DNS Zone can be linked to multiple VNets.
  • No need to deploy a separate DNS resolver for every network.

Microsoft DNS: Azure IP address 168.63.129.16 is a virtual public IP address that facilitates communication channels to Azure platform resources. Customers can define any address space for their private virtual network in Azure. Therefore, the Azure platform resources must be presented as a unique public IP address

🔍 Monitoring Your Network

Don’t forget about visibility and diagnostics.
Use Network Watcher to:

• Monitor traffic flows.
• Diagnose connectivity issues.
• Capture packets and analyze performance.

🧰 Is One Subscription Enough?

For small environments, a single Azure subscription can be sufficient.
However, for larger organizations, multiple subscriptions provide better scalability, governance, and isolation between workloads or teams.

Example of building and envoling network in azure for organization

Example for organization with one Azure subscription

Example 1

• One Azure subscription
• One Azure Virtual Network
• Azure Virtual Network with subntes (segmentation)
• Network Secuirty groups for all subnetes with DenyRules for Inbound / Outbound
• Azure Virtual Gateway for Site to Site VPN connection
• Azure Nat Gateway for NAT outbound traffic

Example 2

• One Azure subscription
• One Azure Virtual Network
• Azure Virtual Network with subntes (segmentation)
• Network Secuirty groups for all subnetes with DenyRules for Inbound / Outbound
• Azure Virtual Gateway for Site to Site VPN connection
• Azure Nat Gateway for NAT outbound traffic
• Azure Private DNS zones dedicated for Azure SQL services
• Azure privet link for Azure SQL server
• Azure SQL server without any Internet access

Example 2

• One Azure subscription
• One Azure Virtual Network
• Azure Virtual Network with subntes (segmentation)
• Network Secuirty groups for all subnetes with DenyRules for Inbound / Outbound
• Azure Virtual Gateway for Site to Site VPN connection
• Azure Nat Gateway for NAT outbound traffic
• Azure Private DNS zones dedicated for Azure SQL services
• Azure privet link for Azure SQL server
• Azure SQL server without any Internet access
• Azure Firewall that inspect all traffic between subnets
• Azure user definie route to pass traffic between subnets over Azure firewall

Example for organization with multiple Azure subscription (Hub)

Example 1

• 3 Azure subscription
• 3 Azure Virtual Network
• Azure Virtual Network with subntes (segmentation)
• Network Secuirty groups for all subnetes with DenyRules for Inbound / Outbound
• Azure Virtual Gateway for Site to Site VPN connection
• Azure Nat Gateway for NAT outbound traffic
• Azure Private DNS zones dedicated for Azure SQL services
• Azure privet link for Azure SQL server

• 3 Azure subscription
• 3 Azure Virtual Network
• Azure Virtual Network with subntes (segmentation)
• Network Secuirty groups for all subnetes with DenyRules for Inbound / Outbound
• Azure Virtual Gateway for Site to Site VPN connection
• Azure Nat Gateway for NAT outbound traffic
• Azure Private DNS zones dedicated for Azure SQL services
• Azure privet link for Azure SQL server
• Azure Network Manager

⚙️ Tips and Best Practices

• Create good naming convention
• Keep it simple
• Subnet with small mask like 28 / 26
• One Virtual Network per Azure Subscription per region
• Use NAT gateway
• Avoid overlap network spaces with you on-premises environment
• Use Hub spoken network if it’s needed
• Not all resources need to have privet access
• DNS resolving is important – all azure resources work over HTTPS
• Good description of routing tables
• Private DNS Zones can be linked to multiple Vnet don’t need to user DNS resolver
• NSG create custom rule block all Inboud / Outboud traffic
• For internet access, use NAT Gateways instead of assigning public IPs directly to VMs.

🧩 Summary

Building a robust Azure network requires thoughtful design and attention to detail.
Start with a solid landing zone, plan your IPs and subnets carefully, use secure connectivity methods, and monitor everything.

When done right, your Azure network becomes the backbone for all your cloud workloads — secure, scalable, and future-proof.

Author: Michał Machniak
System Administrator / Cloud Architect / DevOps
mmachniak.net

“Automate everything you can — but plan your network manually first.”

When working with Azure Arc–enabled servers, you often need to control access in a way that doesn’t fit the built-in roles provided by Azure. While roles like Reader, Contributor, or Azure Connected Machine Onboarding cover many scenarios, they might either grant too many permissions or not enough.

That’s where custom roles come in. By defining a custom role, you can tailor access so that users, groups, or service principals only get the permissions they actually need — nothing more, nothing less.

Why Create a Custom Role for Azure Arc?

Some common scenarios include:

• Delegated administration: Allowing specific teams to manage extensions or policies on Arc-enabled machines, without giving them full subscription-wide rights.

• Security hardening: Enforcing least-privilege access so that hybrid server operators can perform their job without unnecessary permissions.

• Operational separation: Letting one team onboard servers, while another team manages monitoring or updates.

For example, you may want a role that only allows installation and management of VM extensions (like Azure Monitor Agent or Defender for Cloud extensions) on Arc servers — but nothing else.

Step 1: Identify the Required Permissions

Azure roles are defined as sets of Actions and NotActions. For Azure Arc hybrid compute, common permissions include:

• Microsoft.HybridCompute/machines/read – View Arc machines

• Microsoft.HybridCompute/machines/extensions/* – Manage extensions

• Microsoft.HybridCompute/machines/write – Update properties (if needed)

You can explore available permissions with:

az provider operation show --namespace Microsoft.HybridCompute

Step 2: Define the Custom Role JSON

Save the following as ArcOperator.json:

{
  "Name": "[Custom] Azure Arc Operator",
  "IsCustom": true,
  "Description": "View, update patch managment for hybride VM.",
  "Actions": [
                    "*/read",
                    "Microsoft.HybridCompute/operations/read",
                    "Microsoft.HybridCompute/osType/agentVersions/read",
                    "Microsoft.HybridCompute/osType/agentVersions/latest/read",
                    "Microsoft.HybridCompute/machines/read",
                    "Microsoft.HybridCompute/machines/installPatches/action",
                    "Microsoft.HybridCompute/machines/listAccessDetails/action",
                    "Microsoft.HybridCompute/machines/UpgradeExtensions/action",
                    "Microsoft.HybridCompute/machines/assessPatches/action",
                    "Microsoft.HybridCompute/machines/addExtensions/action",
                    "Microsoft.HybridCompute/machines/patchInstallationResults/read",
                    "Microsoft.HybridCompute/machines/patchInstallationResults/softwarePatches/read",
                    "Microsoft.HybridCompute/machines/extensions/read",
                    "Microsoft.HybridCompute/machines/extensions/write",
                    "Microsoft.HybridCompute/machines/extensions/delete",
                    "Microsoft.HybridCompute/machines/patchAssessmentResults/read",
                    "Microsoft.HybridCompute/machines/patchAssessmentResults/softwarePatches/read",
                    "Microsoft.HybridCompute/machines/runcommands/read",
                    "Microsoft.HybridCompute/machines/runcommands/write",
                    "Microsoft.HybridCompute/machines/runcommands/delete",
                    "Microsoft.HybridCompute/machines/write"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/<SUBSCRIPTION_ID>" # Can be Managment group / Resource group
  ]
}

Step 3: Create the Role in Azure

Use the Azure CLI to create the role:

az role definition create –role-definition ./ArcOperator.json

To verify:

az role definition list --name "[Custom] Azure Arc Operator"

Step 4: Assign the Role

Assign the role to a user, group, or managed identity:

az role assignment create \
  --assignee <USER_OR_SP_OBJECT_ID> \
  --role "Arc Extension Operator" \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>

This ensures that the principal can only manage Arc extensions within the defined scope.

Conclusion

Azure Arc custom roles let you implement least-privilege access for hybrid servers. By carefully crafting role definitions, you can give teams exactly the permissions they need — no more, no less.

This approach improves security, simplifies operations, and ensures compliance with enterprise governance requirements.

In large, multi-subscription environments, such as Azure Landing Zones, managing identity and access at scale is a constant challenge. Security groups are a key component of Azure RBAC (Role-Based Access Control), enabling centralized control of permissions for teams and workloads. While you can configure them manually in the Azure Portal, Infrastructure as Code (IaC) ensures consistency, repeatability, and compliance.

With Bicep and the Microsoft Graph extension, we can define security groups and assign Azure roles programmatically—integrating identity management directly into our landing zone deployment workflows

Why Use the Microsoft Graph Extension in Bicep?

By default, Bicep focuses on Azure Resource Manager (ARM) resources. However, security groups in Entra ID (formerly Azure AD) are not ARM resources—they are managed through Microsoft Graph. The Bicep Graph extension bridges this gap, enabling you to:

• Create Azure AD / Entra ID security groups.

• Assign users or service principals to those groups.

• Bind those groups to Azure roles within subscriptions or resource groups.

• This allows a single Bicep deployment to set up both your Azure resources and the associated identity access controls.

Example of code : Creating a Security Group and Assigning a Role

/*
SUMMARY: The Management Groups module deploys a management group hierarchy in a customer's tenant under the 'Tenant Root Group'.
DESCRIPTION: Management Group hierarchy is created through a tenant-scoped Azure Resource Manager (ARM) deployment.  The hierarchy is:
  * Tenant Root Group
      * Organization
        ** Platform
        ** DEV
        ** STAGE
        ** PROD
      * Default - new onborded subscriptions
AUTHOR/S: Michał Machniak
VERSION: 1.0
Logs: Get-AzTenantDeployment -id /providers/Microsoft.Resources/deployments/azl | Get-AzTenantDeploymentOperation
Logs: Get-AzTenantDeployment -id /providers/Microsoft.Resources/deployments/azl-rbac | Get-AzTenantDeploymentOperation
*/

targetScope = 'tenant'

extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/beta:1.0.0' // Load beta extension
extension 'br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:1.0.0' // Load v1.0 extension

///////////////////////// PARAMETERS /////////////////////////

param par_list_secuirty_groups_name array = [
  {
    name: 'GAL-AAD-MG-Organization-Org-Reader'
    description: 'Security group with permissions to read the management group hierarchy'
    role: 'Reader'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGXYZOrgOrgReader' // No whitspaces allowed
    MangmentGroupId: 'Organization' // Management Group ID to assign the group to
  }
  {
    name: 'GAL-AAD-MG-Organization-Contributor'
    description: 'Security group with permissions to contribute to the management group hierarchy'
    role: 'Contributor'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGXYZOrgOrgContributor' // No whitspaces allowed
    MangmentGroupId: 'Organization' // Management Group ID to assign the group to
  }
  {
    name:'GAL-AAD-MG-Organization-Owner'
    description: 'Security group with permissions to manage the management group hierarchy'
    role: 'Owner'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGXYZOrgOrgOwner' // No whitspaces allowed
    MangmentGroupId: 'Organization' // Management Group ID to assign the group to
  }
  // Dev Groups
  {
    name: 'GAL-AAD-MG-DEV-Reader'
    description: 'Security group with permissions to read the management group hierarchy'
    role: 'Reader'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGDEVReader' // No whitspaces allowed
    MangmentGroupId: 'DEV' // Management Group ID to assign the group to
  }
  {
    name: 'GAL-AAD-MG-DEV-Contributor'
    description: 'Security group with permissions to contribute to the management group hierarchy'
    role: 'Contributor'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGDEVContributor' // No whitspaces allowed
    MangmentGroupId: 'DEV' // Management Group ID to assign the group to

  }
  {
    name:'GAL-AAD-MG-DEV-Owner'
    description: 'Security group with permissions to manage the management group hierarchy'
    role: 'Owner'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGDEVOwner' // No whitspaces allowed
    MangmentGroupId: 'DEV' // Management Group ID to assign the group to
  }
  // Prod groups
  {
    name: 'GAL-AAD-MG-PROD-Reader'
    description: 'Security group with permissions to read the management group hierarchy'
    role: 'Reader'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGPRODReader' // No whitspaces allowed
    MangmentGroupId: 'PROD' // Management Group ID to assign the group to
  }
  {
    name: 'GAL-AAD-MG-PROD-Contributor'
    description: 'Security group with permissions to contribute to the management group hierarchy'
    role: 'Contributor'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGPRODContributor' // No whitspaces allowed
    MangmentGroupId: 'PROD' // Management Group ID to assign the group to

  }
  {
    name:'GAL-AAD-MG-PROD-Owner'
    description: 'Security group with permissions to manage the management group hierarchy'
    role: 'Owner'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGPRODOwner' // No whitspaces allowed
    MangmentGroupId: 'PROD' // Management Group ID to assign the group to
  }
    // Prod Default
  {
    name: 'GAL-AAD-MG-Default-Reader'
    description: 'Security group with permissions to read the management group hierarchy'
    role: 'Reader'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGDefualtReader' // No whitspaces allowed
    MangmentGroupId: 'Default' // Management Group ID to assign the group to
  }
  {
    name: 'GAL-AAD-MG-Default-Contributor'
    description: 'Security group with permissions to contribute to the management group hierarchy'
    role: 'Contributor'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMDefualtContributor' // No whitspaces allowed
    MangmentGroupId: 'Default' // Management Group ID to assign the group to
  }
  {
    name:'GAL-AAD-MG-Default-Owner'
    description: 'Security group with permissions to manage the management group hierarchy'
    role: 'Owner'
    securityEnabled: true
    mailEnabled: false // Need to be false is not supported by v1.0 and beta
    uniqueName: 'GALAADMGDefualtOwner' // No whitspaces allowed
    MangmentGroupId: 'Default' // Management Group ID to assign the group to
  }

]


resource res_secuirty_group_alz 'Microsoft.Graph/groups@beta' = [for sec_group in par_list_secuirty_groups_name: {
  displayName: sec_group.name
  description: sec_group.description
  securityEnabled: true
  mailEnabled: false // Need to be false is not supported by v1.0 and beta
  mailNickname: toLower('${sec_group.name}')
  owners: {
    relationships: []
  }
  members: {
    relationships: []
  }
  uniqueName: sec_group.uniqueName  // No whitspaces allowed

}]



// Assign security groups to management groups - need delay against the creation of the security groups

module mod_mg_role_permissions '.modules/RoleAssigment/managmentGroups.bicep' = [for i in range(0, length(par_list_secuirty_groups_name)) : {
  name: guid(par_list_secuirty_groups_name[i].name)
  scope: managementGroup('${par_list_secuirty_groups_name[i].MangmentGroupId}')
  params: {
    principalId: res_secuirty_group_alz[i].id
    roleDefinitionIdOrName: par_list_secuirty_groups_name[i].role
    managementGroupId: par_list_secuirty_groups_name[i].MangmentGroupId
  }
  dependsOn: [
    res_secuirty_group_alz
  ]
}]

output out_groups_id array = [for i in range(0, length(par_list_secuirty_groups_name)): res_secuirty_group_alz[i].id]

Example Deployment Command:

New-AzTenantDeployment -Location "North Europe" -Name "AAD-v2" -TemplateFile .\main-aad-loop.bicep

az deployment sub tenant --location northeurope --template-file .\main-aad-loop.bicep

Link to repo with code:

You can find code example in my GitHub repository: Github Bicep code example

Know issue

When you create security groups in EntraID, it will take time for Graph API to procced chnages, so you can see that assigne permissions will faild because object wasn not found in Entra I, so this will required to rerun bicep as EntraID need some time.

Conclusion

By using the Microsoft Azure Bicep Graph extension, you can extend your IaC workflows beyond Azure resources, directly into identity and access management. This approach helps ensure that your Azure Landing Zone deployments are secure, consistent, and repeatable—with all permissions configured as code.