Service & Admin Accounts
DOCUMENT CATEGORY: Runbook
SCOPE: Service and administrative accounts
PURPOSE: Create break-glass and gMSA accounts
MASTER REFERENCE: Microsoft Learn - AD Prerequisites
Status: Active
Overview
Create supplemental break-glass admin accounts and optional gMSA scaffold for enterprise environments.
What This Accomplishes
- Break-glass administrative accounts for emergency access
- Group Managed Service Accounts (gMSA) for secure service authentication
- Secure password management and storage
- Account configuration following security best practices
The active directory information in these documents should have been decided in the planning phase and discovery phases. These are just examples. Please update your scripts with the right OU information, right security groups, DNS, etc.
Prerequisites
- OU structure created (Step 1)
- Domain admin access for account creation
- Secure password storage solution (vault)
- Only for the optional gMSA scaffold: a KDS root key that has replicated to all domain controllers (see below)
KDS root key (optional gMSA scaffold only)
The break-glass account does not need a KDS root key. The Microsoft Learn 2610 Azure Local AD-preparation and custom-AD articles do not mention a gMSA or a KDS root key, so this runbook set treats the gMSA scaffold as optional. If you create the gMSA, a KDS root key must exist first (one per forest). Check with Get-KdsRootKey, and create one only if none exists.
| Environment | Command | Wait |
|---|---|---|
| Production or any lab with more than one domain controller | Add-KdsRootKey -EffectiveImmediately | Wait 10 hours so the key replicates to all domain controllers before creating the gMSA |
| Single domain controller test environment only | Add-KdsRootKey -EffectiveTime (Get-Date).AddHours(-10) | None. Microsoft documents this backdating technique for single-DC tests only and says not to use it in production |
Source: Create a Key Distribution Service (KDS) root key. Do not create more than one root key per forest.
The Learn 2610 Environment Checker article still describes the Active Directory validator as checking that the preparation tool created gMSAs. The 2610 AD-preparation article documents only New-HciAdObjectsPreCreation -AzureStackLCMUserCredential ... -AsHciOUName ... from the AsHciADArtifactsPreCreationTool module (install version 2402 and uninstall earlier versions first). This repo follows the AD-preparation article; treat the gMSA wording as legacy and rely on the validator result in 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.
Account Creation
Lifecycle Manager (LCM) user created in Step 1. Add break‑glass admin and optional gMSA scaffold.
- Active Directory Users and Computers
- Orchestrated Script
- In Active Directory Users and Computers, inside instance OU create user:
adm-AzureLocal-BreakGlass-<clusterId>. - Set: Password never expires; User cannot change password; store password securely (vault).
- (Optional gMSA) After a KDS root key exists and has replicated (see the KDS table above), create gMSA via AD Administrative Center (if supported) targeting computer principals later.
PowerShell
When to use: Run the task from a management host that can reach a domain controller. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/03-onprem-readiness/phase-01-active-directory/task-04-service-admin-accounts/powershell/New-ADAccounts.ps1 | Creates the optional domain join account of infrastructure.yml (identity.active_directory.domain_join_account) in the dedicated OU, enabled, with the password read through the secret resolver. Supports -WhatIf. |
The LCM deployment user is created by Task 01 (Set-ADConfiguration.ps1), as Microsoft's preparation does it; this script does not create it again. It creates no break-glass account and no gMSA (the manual tab covers those). A file without domain_join_account does nothing and exits 0. The script gives the account no rights on the OU: delegate "create and delete computer objects" on the OU to it (Learn: Custom Active Directory configuration, Required permissions).
Parameters: -InfrastructureFile (mandatory), -Credential (the account that creates the user; without it the account that runs the script is used), -LogPath.
Values from infrastructure.yml: scenario.identity (local_identity does nothing), identity.active_directory.domain_fqdn, .ou_path, .netbios_name, .domain_join_account.username (a name, NETBIOS\name or name@domain), .domain_join_account.password (a secret reference).
Requires: PowerShell 7; modules ActiveDirectory.
Run
./New-ADAccounts.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-ADAccounts.ps1 -InfrastructureFile ./infrastructure.yml
Exit codes: 0 the account exists (created now, already there, or planned under -WhatIf) or the file names none; 1 the domain or the OU could not be reached, the module is missing, the secret could not be read or the account could not be created; 2 a value in the file is missing or not usable.
Verification
Get-ADUser -LDAPFilter "(sAMAccountName=adm-AzureLocal-BreakGlass-*)" -SearchBase $OuPath | Select SamAccountName,Enabled
Get-ADServiceAccount -LDAPFilter "(sAMAccountName=gMSA-AzureLocal-*)" -SearchBase $OuPath | Select Name,Enabled
Notes
- LCM user is created in Step 1; this step adds supplemental accounts
- Break-glass accounts should have passwords stored securely in a vault
- gMSA requires a KDS root key and replication to complete first (10 hours in production). KDS root key guidance lives here, not in Task 01
- Use unique cluster IDs to avoid naming conflicts
Validation Checklist
- Break-glass admin account created
- Password stored securely in vault
- Account properties configured correctly
- gMSA created if required
- Retrievers group configured for gMSA
- Accounts enabled and accessible
Next Steps
After creating accounts, proceed to Task 5 - Group Assignments to assign accounts to security groups.
Troubleshooting
Common Issues
Account Creation Fails: Check OU permissions and naming policies.
gMSA Creation Fails: Ensure a KDS root key exists and has replicated to all domain controllers. With -EffectiveImmediately wait 10 hours in production; use the -10 hours backdating only on a single-DC test domain.
Password Storage: Verify vault access and security policies.
Support Resources
Data verified with internal source [Azure Local Provisioning Runbook] and Docusaurus documentation release note dated 2025-12-08.
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
| ← Task 03: DNS Node A Records | ↑ Part 3: On-Premises Readiness | Task 05: Group Assignments → |
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 | KDS root key guidance moved here from Task 01 and scoped to the optional gMSA; production vs single-DC lab guidance |
| 1.3.0 | 2026-11-16 | Azure Local Cloud | The script section matches New-ADAccounts.ps1 (the domain join account from infrastructure.yml, parameters, exit codes) |
End of Task