Skip to main content

Task 01: OU Creation & Pre-Creation Artifacts

Runbook Platform

DOCUMENT CATEGORY: Runbook
SCOPE: Active Directory preparation
PURPOSE: Create Azure Local OU and LCM user account
MASTER REFERENCE: Microsoft Learn - AD Prerequisites

Status: Active Estimated Time: 15 minutes Last Updated: 2026-11-16


Overview​

Create the Azure Local OU container and LCM (Lifecycle Manager) user account using Microsoft's AsHciADArtifactsPreCreationTool.


Prerequisites​

RequirementDescription
PermissionsCreate OU and user account in AD
ModuleAsHciADArtifactsPreCreationTool (Learn 2610 installs version 2402, 10.2402; uninstall any previous version first)
FirewallIf a firewall sits between Azure Local and Active Directory, allow Active Directory Web Services (ADWS) and the Active Directory Gateway Management Service. See firewall requirements
No KDS root key needed for this task

The Microsoft Learn 2610 Active Directory preparation article (New-HciAdObjectsPreCreation) and the custom Active Directory article do not mention a KDS root key or a gMSA. This task therefore no longer creates one. In this runbook set a KDS root key is only needed for the optional gMSA scaffold in Task 04.

Requirements and constraints (Microsoft Learn 2610)​

Review these before you choose names. They come from the Learn articles Prepare Active Directory, Custom Active Directory configuration and Deploy via the Azure portal.

Active Directory requirements

  • A dedicated OU for the Azure Local objects (the computer objects and the cluster CNO), with Group Policy inheritance blocked so existing GPOs do not conflict with the Azure Local security defaults.
  • A deployment (LCM) user with the necessary permissions over that OU. The user can reside anywhere in the directory.
  • The prep script is optional. You can meet the requirements with your own process (see the delegated rights table below).

Deployment (LCM) user

RequirementLearn 2610 statement
Username1-20 characters; only letters, numbers, hyphens and underscores; cannot start with a hyphen or a number
Username formProvide only the username. Do not include the domain, for example contoso\username
Reserved or duplicate namesCannot be admin; cannot be exactly the same as the local admin user; must be unique for each Azure Local instance
PasswordAt least 14 characters with a lowercase character, an uppercase character, a numeral and a special character
Logon rightsAllowed to log on interactively, and has the Log on as a batch job right. Make sure the default domain policy does not deny it, or grant it explicitly to the account
ScopeLearn recommends a dedicated LCM account with a unique password per instance to limit the impact of a compromised account

OU path and lifecycle

  • The -AsHciOUName value is a distinguished name and cannot contain any of these characters anywhere in the path: &, ", ', <, >.
  • The portal deployment wizard states that the OU cannot be at the top level of the domain, for example OU=Local001,DC=contoso,DC=com.
  • After deployment, moving the computer objects to a different OU is not supported.
  • If you repair a single machine, do not delete the existing OU. If the machine volumes are encrypted, deleting the OU removes the BitLocker recovery keys.
  • Blocking inheritance at the OU does not block GPOs that have the Enforced option. Block them by another method, for example a WMI filter that excludes the Azure Local machine computer accounts.
  • At scale, create one OU per instance under a single parent OU, enable Block Inheritance on both the parent and the sub-OU, and link any GPO that must reach every instance to the parent OU with Enforced.

Delegated rights (if you do not use New-HciAdObjectsPreCreation)

PrincipalScopePermissions
Deployment userOU and all descendant objectsList contents, read all properties, read permissions, create computer objects, delete computer objects
Deployment userOU, applied only to descendant msFVE-Recoveryinformation objectsFull control (list contents, read and write all properties, delete, read and modify permissions, modify owner, all validated writes)
Cluster CNOOU and all descendant objectsRead all properties, create computer objects

The msFVE-RecoveryInformation permission must be set with PowerShell; the Active Directory delegation wizard cannot set it. The full manual script is in the Learn article.

Domain-joining nodes before deployment (2604 and later)

Microsoft Learn 2610 states that, starting with version 2604, domain joining before deployment is supported. If you choose to domain join, you must add the deployment user to the local Administrators group. If you do not, the machines are joined to a domain automatically during the Azure portal deployment. If you pre-join, add the computer to the correct OU (the one created by this task), because moving computer objects to a different OU after deployment is not supported. See the phase 02 OS installation runbooks.

Preflight check​

Run this read-only check before New-HciAdObjectsPreCreation. It validates the names against the rules above and warns if the OU already exists.

#Requires -Version 7.0
param(
[Parameter(Mandatory)][string]$LcmUserName,
[Parameter(Mandatory)][string]$OuDistinguishedName
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

$problems = @()
if ($LcmUserName -notmatch '^[A-Za-z_][A-Za-z0-9_-]{0,19}$') { $problems += 'LCM username must be 1-20 characters (letters, numbers, hyphen, underscore) and must not start with a hyphen or a number.' }
if ($LcmUserName -ieq 'admin') { $problems += 'LCM username cannot be admin.' }
if ($OuDistinguishedName -match '[&"''<>]') { $problems += 'OU path cannot contain & " '' < >.' }
if ($OuDistinguishedName -notmatch '^OU=.+,DC=.+') { $problems += 'OU path must be a distinguished name that starts with OU= (not the domain root).' }
if ((Get-Module -ListAvailable -Name ActiveDirectory) -and
(Get-ADOrganizationalUnit -Filter "distinguishedName -eq '$OuDistinguishedName'" -ErrorAction SilentlyContinue)) {
Write-Warning 'OU already exists. Do not delete it when repairing a node (BitLocker recovery keys).'
}
if ($problems) { $problems | ForEach-Object { Write-Error $_ -ErrorAction Continue }; exit 1 }
Write-Output 'Preflight passed.'

The regex also rejects a username that starts with a number; it does not check password complexity or the unique-per-instance rule, which you must confirm against your instance inventory.

info

AD structure should be defined during the planning phase. Update variables below for your environment.


Values from infrastructure.yml​

The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.

KeyWhat it is
scenario.identityactive_directory runs this task. With local_identity the script does nothing and exits 0
identity.active_directory.domain_fqdnThe domain
identity.active_directory.ou_pathThe dedicated OU
identity.active_directory.lcm_user.username, .passwordThe LCM user. The password is a secret reference, read in memory only
identity.active_directory.create_parent_ousSchema 5.6.28. Whether Set-ADConfiguration.ps1 creates the parent OUs of ou_path that are missing, from the domain down, before it calls New-HciAdObjectsPreCreation. Microsoft's cmdlet creates only the OU itself and stops when its parent does not exist. A parent that exists is never changed, and no group policy setting is made on a parent the script creates. Default false: a missing parent stops the script with exit code 1 and nothing is created
identity.active_directory.precreate_computer_objectsSchema 5.6.23. Whether Set-ADConfiguration.ps1 creates the computer objects of the machines (nodes[].name) and of the cluster (cluster.name) in the OU before the deployment. Microsoft Learn allows this instead of letting the deployment create them (Custom Active Directory configuration for your Azure Local instance; Prestage cluster computer objects). The cluster object is created disabled. Default false: the domain join of the OS configuration and the deployment create the objects

Execution​

PowerShell​

When to use: Run the task from a management host that can reach a domain controller. The script calls Microsoft's New-HciAdObjectsPreCreation (see the preflight above) with the OU and the LCM user of infrastructure.yml.

Script​

ScriptWhat it does
scripts/deploy/03-onprem-readiness/phase-01-active-directory/task-01-ou-creation-pre-creation-artifacts/powershell/Set-ADConfiguration.ps1Prepares Active Directory for Azure Local from infrastructure.yml: the dedicated OU and the LCM deployment user, and, when the file asks, the computer objects of the machines and the cluster. Supports -WhatIf.

Parameters: -InfrastructureFile (mandatory), -Credential (the account that creates the objects; without it the account that runs the script is used), -LogPath. The script asks nothing. It is idempotent: when the OU and the user both exist, it sends nothing. When only one of the two exists, it stops and says so. It never deletes anything.

Parent OUs. New-HciAdObjectsPreCreation creates the OU inside its parent and stops when the parent does not exist. Before it runs, the script reads every parent OU of identity.active_directory.ou_path from the domain down:

create_parent_ousA parent OU is missing
false or not set (default)The script stops with exit code 1, names the first missing parent and creates nothing. Also under -WhatIf
trueThe script creates the missing parents top-down with New-ADOrganizationalUnit (protected from accidental deletion), then runs Microsoft's cmdlet. Under -WhatIf it lists them as WouldCreate

The script sets no group policy option on a parent it creates. Learn recommends Block Inheritance on the parent OU too when many instances share it; set it yourself if your design needs it.

Requires: PowerShell 7; modules ActiveDirectory, AsHciADArtifactsPreCreationTool.

Run​

./Set-ADConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf

./Set-ADConfiguration.ps1 -InfrastructureFile ./infrastructure.yml

Exit codes: 0 the OU, the user (and the objects) are in place, already there or planned under -WhatIf; 1 a precondition or a call failed (module missing, domain not reachable, a half-made preparation, a missing parent OU with create_parent_ous not set, the secret could not be read); 2 a value in the file is missing or not usable.


Verification​

PowerShell​

When to use: Check only what this task creates: the KDS root key, the OU and the LCM user. The checks do not look at security groups, DNS records or computer accounts. Those belong to later tasks.

Script​

ScriptWhat it does
scripts/deploy/04-cluster-deployment/phase-05-cluster-deployment/Invoke-AzureLocalPreClusterVerification.ps1The pre-cluster verification. Read only. Checks ID-AD-003, ID-AD-004 and ID-AD-012 cover this task: the OU, the LCM user and the KDS root key.

The three earlier validation scripts of this task folder (Test-ADConfiguration.ps1, Invoke-ADValidation-AzVM.ps1, Invoke-ADValidation-Arc.ps1) are removed. The pre-cluster verification does the same checks.

Run​

./Invoke-AzureLocalPreClusterVerification.ps1 -InfrastructureFile ./infrastructure.yml -Mode Verify -Category identity

A run with -Category is partial. It ends with exit code 3 when nothing blocks, and it never passes the ARM precondition. Run all categories before the deployment.


Validation Checklist​

  • AsHciADArtifactsPreCreationTool module installed (version 2402 or later, previous versions uninstalled first)
  • LCM username and password meet the rules in Requirements and constraints
  • LCM user can log on interactively and has the Log on as a batch job right
  • OU path has no &, ", ', < or > characters and is not the domain root
  • OU created with Block Inheritance enabled (enforced GPOs handled with a WMI filter if present)
  • LCM user created in OU
  • Credentials stored securely

Troubleshooting​

IssueCauseResolution
New-ADOrganizationalUnit fails with access deniedInsufficient permissions to create OUsRun as Domain Admin or delegate OU creation rights on the parent container
Set-ADConfiguration.ps1 stops: a parent OU does not existThe OU of ou_path sits under an OU that is not there yetCreate the parent OU, or set identity.active_directory.create_parent_ous: true and run the script again
Deployment later fails to log on as the LCM userDefault domain policy denies Log on as a batch job or interactive logonGrant the right explicitly to the LCM account or remove the deny
OU creation rejects the pathPath contains &, ", ', < or >, or is the domain rootUse a distinguished name such as OU=Local001,DC=contoso,DC=com
AsHciADArtifactsPreCreationTool module not foundModule not installed or wrong PS versionInstall via Install-Module AsHciADArtifactsPreCreationTool on PowerShell 5.1+
LCM user creation fails with duplicateAccount already exists from prior attemptVerify existing account properties match requirements or remove and recreate

Next Steps​

Proceed to Task 2 - Security Groups to create optional security groups.



Alternatives​

The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.

← Phase 01: Active Directory↑ Part 3: On-Premises ReadinessTask 02: Security Groups →

Version Control​

VersionDateAuthorChanges
1.02026-01-31Azure Local CloudInitial document
1.12026-03-03Azure Local CloudStandardized runbook format
1.2.02026-11-08Azure Local CloudAligned to Microsoft Learn 2610: removed KDS root key from AD prep, added requirements and constraints, delegated-rights table and preflight check
1.3.02026-11-16Azure Local CloudThe script checks the parent OUs and creates the missing ones when create_parent_ous is true; the task folder's placeholder is retired

End of Task