Security Groups
DOCUMENT CATEGORY: Runbook
SCOPE: Active Directory security groups
PURPOSE: Create role-based access control groups
MASTER REFERENCE: Microsoft Learn - AD Prerequisites
Status: Active
Overview
Create optional security groups for role-based access control in Azure Local administration.
What This Accomplishes
- Role-based access control for Azure Local operations
- Delegated administration capabilities
- Separation of duties for different administrative roles
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
- Security Groups OU exists in Active Directory
- Domain admin access for group creation
- Understanding of group scope and security requirements
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.
Security Group Model
Each group is an entry of identity.active_directory.security_groups[] in infrastructure.yml: name, purpose, members (filled in Task 05) and local_groups (applied to the nodes after the deployment). You choose the names; put the cluster in the name so groups stay unique per cluster in the same domain. The earlier object-by-role form (security_groups_by_role, with org_prefix and cluster_id) is removed from the registry.
Example name | local_groups on every node | Purpose |
|---|---|---|
sg-iic-azl-01-admins | Administrators | Full admin access to cluster nodes |
sg-iic-azl-01-operations | Remote Management Users, Remote Desktop Users | PowerShell remoting and RDP; no full admin |
sg-iic-azl-01-readonly | Remote Desktop Users, Performance Monitor Users, Event Log Readers | View only; cannot change configuration |
sg-iic-azl-01-hyperv-admins | Hyper-V Administrators, Remote Management Users | VM management through PowerShell remoting |
sg-iic-azl-01-storage-admins | Administrators | CSV and Storage Spaces Direct management |
identity:
active_directory:
security_groups:
- { name: "sg-iic-azl-01-admins", purpose: "Administrators of the instance", local_groups: ["Administrators"] }
- { name: "sg-iic-azl-01-operations", purpose: "PowerShell remoting and RDP", local_groups: ["Remote Management Users", "Remote Desktop Users"] }
- { name: "sg-iic-azl-01-readonly", purpose: "View only", local_groups: ["Remote Desktop Users", "Performance Monitor Users", "Event Log Readers"] }
- { name: "sg-iic-azl-01-hyperv-admins", purpose: "VM management", local_groups: ["Hyper-V Administrators", "Remote Management Users"] }
- { name: "sg-iic-azl-01-storage-admins", purpose: "Storage and CSV management", local_groups: ["Administrators"] }
Security Group Creation
Core Azure Local instance security groups in the enterprise Security Groups OU (pre-determined OU for security groups).
- Active Directory Users and Computers
- Orchestrated Script
- Open Active Directory Users and Computers.
- Navigate to the OU for the groups (the toolkit script uses the dedicated OU of the instance,
identity.active_directory.ou_path, for exampleOU=iic-azl-01,OU=AzureLocal,DC=improbability,DC=cloud). - Right‑click OU → New → Group.
- Create each group of
identity.active_directory.security_groups[](Global / Security), with itsname, for example:
sg-iic-azl-01-adminssg-iic-azl-01-operationssg-iic-azl-01-readonlysg-iic-azl-01-hyperv-adminssg-iic-azl-01-storage-admins
- For each group: Properties → Protection: enable "Protect object from accidental deletion".
- Document intended membership policy (who owns adds/removals).
PowerShell
When to use: Run the task with the script below, from the place its help names (a management workstation, or the node itself).
Script
| Script | What it does |
|---|---|
scripts/deploy/03-onprem-readiness/phase-01-active-directory/task-02-security-groups/powershell/New-ADSecurityGroups.ps1 | Creates the Active Directory security groups that identity.active_directory.security_groups[] of infrastructure.yml lists: a global security group per entry, in identity.active_directory.ou_path, with the purpose as its description. Idempotent; never deletes a group or changes a membership. Supports -WhatIf. |
Parameters: -InfrastructureFile (mandatory), -Credential (without it, the account that runs the script), -LogPath. The script asks nothing. Run task 01 (Set-ADConfiguration.ps1) first: it creates the OU.
Requires: PowerShell 7; modules ActiveDirectory.
Run
./New-ADSecurityGroups.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-ADSecurityGroups.ps1 -InfrastructureFile ./infrastructure.yml
Verification
# The OU of identity.active_directory.ou_path; the names of identity.active_directory.security_groups[]
$GroupsOuDn = "OU=iic-azl-01,OU=AzureLocal,DC=improbability,DC=cloud"
Get-ADGroup -LDAPFilter "(cn=sg-iic-azl-01-*)" -SearchBase $GroupsOuDn | Select-Object Name
Validation Checklist
- Security Groups OU accessible
- All required security groups created
- Groups configured as Global/Security scope
- Protection from accidental deletion enabled
- Membership policies documented
Next Steps
After creating security groups, proceed to Task 3 - DNS Node A Records for optional DNS record creation.
Troubleshooting
Common Issues
Group Creation Fails: Check permissions and OU access.
Scope Configuration: Ensure Global scope is appropriate for your domain structure.
Protection Setting: Verify "Protect object from accidental deletion" is enabled.
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 01: OU Creation | ↑ Part 3: On-Premises Readiness | Task 03: DNS Node A Records → |
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 |
End of Task