Task 01: OU Creation & Pre-Creation Artifacts
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
| Requirement | Description |
|---|---|
| Permissions | Create OU and user account in AD |
| Module | AsHciADArtifactsPreCreationTool (Learn 2610 installs version 2402, 10.2402; uninstall any previous version first) |
| Firewall | If 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 |
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
| Requirement | Learn 2610 statement |
|---|---|
| Username | 1-20 characters; only letters, numbers, hyphens and underscores; cannot start with a hyphen or a number |
| Username form | Provide only the username. Do not include the domain, for example contoso\username |
| Reserved or duplicate names | Cannot be admin; cannot be exactly the same as the local admin user; must be unique for each Azure Local instance |
| Password | At least 14 characters with a lowercase character, an uppercase character, a numeral and a special character |
| Logon rights | Allowed 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 |
| Scope | Learn recommends a dedicated LCM account with a unique password per instance to limit the impact of a compromised account |
OU path and lifecycle
- The
-AsHciOUNamevalue 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)
| Principal | Scope | Permissions |
|---|---|---|
| Deployment user | OU and all descendant objects | List contents, read all properties, read permissions, create computer objects, delete computer objects |
| Deployment user | OU, applied only to descendant msFVE-Recoveryinformation objects | Full control (list contents, read and write all properties, delete, read and modify permissions, modify owner, all validated writes) |
| Cluster CNO | OU and all descendant objects | Read 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.
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.
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.
| Key | What it is |
|---|---|
scenario.identity | active_directory runs this task. With local_identity the script does nothing and exits 0 |
identity.active_directory.domain_fqdn | The domain |
identity.active_directory.ou_path | The dedicated OU |
identity.active_directory.lcm_user.username, .password | The LCM user. The password is a secret reference, read in memory only |
identity.active_directory.create_parent_ous | Schema 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_objects | Schema 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
- Toolkit Script
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 ofinfrastructure.yml.
Script
| Script | What it does |
|---|---|
scripts/deploy/03-onprem-readiness/phase-01-active-directory/task-01-ou-creation-pre-creation-artifacts/powershell/Set-ADConfiguration.ps1 | Prepares 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_ous | A 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 |
true | The 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
- Toolkit Script
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
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-05-cluster-deployment/Invoke-AzureLocalPreClusterVerification.ps1 | The 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
| Issue | Cause | Resolution |
|---|---|---|
New-ADOrganizationalUnit fails with access denied | Insufficient permissions to create OUs | Run as Domain Admin or delegate OU creation rights on the parent container |
Set-ADConfiguration.ps1 stops: a parent OU does not exist | The OU of ou_path sits under an OU that is not there yet | Create 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 user | Default domain policy denies Log on as a batch job or interactive logon | Grant the right explicitly to the LCM account or remove the deny |
| OU creation rejects the path | Path contains &, ", ', < or >, or is the domain root | Use a distinguished name such as OU=Local001,DC=contoso,DC=com |
| AsHciADArtifactsPreCreationTool module not found | Module not installed or wrong PS version | Install via Install-Module AsHciADArtifactsPreCreationTool on PowerShell 5.1+ |
| LCM user creation fails with duplicate | Account already exists from prior attempt | Verify 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.
Navigation
| ← Phase 01: Active Directory | ↑ Part 3: On-Premises Readiness | Task 02: Security Groups → |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-01-31 | Azure Local Cloud | Initial document |
| 1.1 | 2026-03-03 | Azure Local Cloud | Standardized runbook format |
| 1.2.0 | 2026-11-08 | Azure Local Cloud | Aligned to Microsoft Learn 2610: removed KDS root key from AD prep, added requirements and constraints, delegated-rights table and preflight check |
| 1.3.0 | 2026-11-16 | Azure Local Cloud | The 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