Prepare Active Directory for Azure Local, version 23H2 deployment

Applies to: Azure Local, version 23H2

This article describes how to prepare your Active Directory environment before you deploy Azure Local, version 23H2.

Active Directory requirements for Azure Local include:

• A dedicated Organization Unit (OU).
• Group policy inheritance that is blocked for the applicable Group Policy Object (GPO).
• A user account that has all rights to the OU in the Active Directory.
• Machines must not be joined to Active Directory before deployment.

Note

• You can use your existing process to meet the above requirements. The script used in this article is optional and is provided to simplify the preparation.
• When group policy inheritance is blocked at the OU level, enforced GPO's aren't blocked. Ensure that any applicable GPO, which are enforced, are also blocked using other methods, for example, using WMI Filters.

To manually assign the required permissions for Active Directory, create an OU, and block GPO inheritance, see Custom Active Directory configuration for your Azure Local, version 23H2.

Prerequisites

Before you begin, make sure you've done the following:

• Satisfy the prerequisites for new deployments of Azure Local.

• Download and install the version 2402 module from the PowerShell Gallery. Run the following command from the folder where the module is located:

  Install-Module AsHciADArtifactsPreCreationTool -Repository PSGallery -Force
  

  Note

  Make sure to uninstall any previous versions of the module before installing the new version.

• You have obtained permissions to create an OU. If you don't have permissions, contact your Active Directory administrator.

• If you have a firewall between your Azure Local system and Active Directory, ensure that the proper firewall rules are configured. For specific guidance, see Firewall requirements for Active Directory Web Services and Active Directory Gateway Management Service. See also How to configure a firewall for Active Directory domains and trusts.

Active Directory preparation module

The New-HciAdObjectsPreCreation cmdlet of the AsHciADArtifactsPreCreationTool PowerShell module is used to prepare Active Directory for Azure Local deployments. Here are the required parameters associated with the cmdlet:

Parameter	Description
-AzureStackLCMUserCredential	A new user object that is created with the appropriate permissions for deployment. This account is the same as the user account used by the Azure Stack HCI deployment. Make sure that only the username is provided. The name should not include the domain name, for example, contoso\username. The password must conform to the length and complexity requirements. Use a password that is at least 12 characters long. The password must also contain three out of the four requirements: a lowercase character, an uppercase character, a numeral, and a special character. For more information, see password complexity requirements. The name cannot be exactly the same as the local admin user. The name can use admin as the username.
-AsHciOUName	A new Organizational Unit (OU) to store all the objects for the Azure Stack HCI deployment. Existing group policies and inheritance are blocked in this OU to ensure there's no conflict of settings. The OU must be specified as the distinguished name (DN). For more information, see the format of Distinguished Names.

Note

• The -AsHciOUName path doesn't support the following special characters anywhere within the path: &,",',<,>.
• Moving the computer objects to a different OU after the deployment is complete is also not supported.

Prepare Active Directory

When you prepare Active Directory, you create a dedicated Organizational Unit (OU) to place the Azure Local related objects such as deployment user.

To create a dedicated OU, follow these steps:

1. Sign in to a computer that is joined to your Active Directory domain.

2. Run PowerShell as administrator.

3. Run the following command to create the dedicated OU.

   New-HciAdObjectsPreCreation -AzureStackLCMUserCredential (Get-Credential) -AsHciOUName "<OU name or distinguished name including the domain components>"
   
   

4. When prompted, provide the username and password for the deployment.

   1. Make sure that only the username is provided. The name should not include the domain name, for example, contoso\username. Username must be between 1 to 64 characters and only contain letters, numbers, hyphens, and underscores and may not start with a hyphen or number.
   2. Make sure that the password meets complexity and length requirements. Use a password that is at least 12 characters long and contains: a lowercase character, an uppercase character, a numeral, and a special character.

   Here is a sample output from a successful completion of the script:

   PS C:\work> $password = ConvertTo-SecureString '<password>' -AsPlainText -Force
   PS C:\work> $user = "ms309deployuser"
   PS C:\work> $credential = New-Object System.Management.Automation.PSCredential ($user, $password)
   PS C:\work> New-HciAdObjectsPreCreation -AzureStackLCMUserCredential $credential -AsHciOUName "OU=ms309,DC=PLab8,DC=nttest,DC=microsoft,DC=com"    
   PS C:\work>
   

5. Verify that the OU is created. If using a Windows Server client, go to Server Manager > Tools > Active Directory Users and Computers.

6. An OU with the specified name should be created and within that OU, you'll see the deployment user.

   

Note

If you are repairing a single machine, do not delete the existing OU. If the machine volumes are encrypted, deleting the OU removes the BitLocker recovery keys.

Next steps

• Download Azure Stack HCI OS, version 23H2 software on each machine in your system.