Azure Runbook – Create Active Directory accounts in hybrid environment

In this post, we will walk through how to properly provision Active Directory accounts in a hybrid environment. Using a lab environment configured with an on-premises Exchange Server and a Domain Controller, we’ll demonstrate how to create both the user account and the on-premises mailbox in a single step using the Exchange Admin Center (EAC) PowerShell command line.

Instead of using AD module commands like “New-ADUser” to provision the account, we will use EAC command line to create the mailbox AND the account at the same time. There are few different options available:

Prerequisites:

Exchange Admin Role: Before running EAC command to provision mailbox – the following role, Recipient Management or Organization Management. must be granted to the service account executing the command.

To configure roles for a service account [SVC_AD_Provision_01]:

EAC > permissions > admin role > Recipient Management > add user > hit save

Environment access: The service account also requires rights to execute EAC commands using Exchange management shell in a remote session.

PowerShell remote session to exchange management shell:

•Verify if user has remote access:
Get-User -Identity "SVC_AD_Provision_01" | Format-List RemotePowerShellEnabled

•Enables remote access with the command:
Set-User "SVC_AD_Provision_01" -RemotePowerShellEnabled $true

•Get list of all users with permission to remote access
Get-User -ResultSize unlimited | Format-Table Name,DisplayName,RemotePowerShellEnabled -AutoSize

Create the mailbox and account

Create the AD and mailbox from an established PS session with the command “New-RemoteMailbox”

Grab the connection url from here EAC > Virtual directories > Powershell

#Scriptblock to remote into exchange management shell:

#########################################

### Logs into management shell ###

$UserCredential = Get-Credential

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://exchange01.red929.com/powershell -Authentication Kerberos -Credential $UserCredential

Import-PSSession $Session -DisableNameChecking

#########################################

### Create User mailbox - use cmdlet "New-RemoteMailbox" ###

New-RemoteMailbox -Name "Test Mailbox_02" -FirstName "Test" -LastName "Mailbox2" -UserPrincipalName "Test.Mailbox2@red929.com" -RemoteRoutingAddress "Test.Mailbox2@red929.mail.onmicrosoft.com" 

#########################################

Results: The mailbox and AD account gets created and sync over to exchange.

Automate the process with Azure automation runbook hybrid worker group

Option 1: Get credential using Azure automation account credential asset from runbook script.

<# Runbook Script:
--------------------------
Goal:Connect to Exchange management shell to create and mailbox+ AD user.
*Script intended for azure runbook with hybrid worker group
--------------------------
Credentials is configured under shared resource in the automation account. AD service account creds can be passed on via $Credential
--------------------------
#>
########################################
# Get the credential asset
$credential = Get-AutomationPSCredential -Name 'SVC_AD'

########################################
# Logs into management shell with ps session
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://exchange01.red929.com/powershell -Authentication Kerberos -Credential $credential
	    
Import-PSSession $Session -DisableNameChecking

########################################
# Create User mailbox - use cmdlet "New-RemoteMailbox"
$password = (ConvertTo-SecureString -String 'Password16178!!' -AsPlainText -Force)
	
New-RemoteMailbox -Name "Test Mailbox_05" -FirstName "Test05" -LastName "Mailbox5" -UserPrincipalName "Test.Mailbox5@red929.com" -Password $password -RemoteRoutingAddress "Test.Mailbox5@red929.mail.onmicrosoft.com"

Results:

Connects to management shell without interactive prompt and creates the mailbox and AD account without issue.

Option 2: Get credential using Azure key vault from runbook script (Recommended). Key vault is centralized platform to store secrets, easy to audit. Retrieve the secret with managed identity for the azure arc machine.

#######################################
# Load the following modules:
Import-Module Az.Accounts

<# Ensures you do not inherit an AzContext in your runbook
By default, Azure PowerShell can automatically save your login context (subscription, tenant, account) so it persists across sessions.
Disable-AzContextAutosave turns that behavior off, meaning:
• Your Azure login context will not be saved after the session ends.
• You must re-authenticate when starting a new PowerShell session.
• Useful for: Automation scripts, CI/CD pipelines, Secure environments, Shared machines #>
    
Disable-AzContextAutosave -Scope Process
  
<# Connect to Azure with system-assigned managed identity.
(-Identity) tells Connect-AzAccount to authenticate using a Managed Identity instead of:
Username/password, Service principal secret or Interactive login.
This works in environments like Azure VM (with system/user-assigned identity), Azure App Service, Azure Functions, Azure Automations #>
  
$AzureContext = (Connect-AzAccount -Identity).context
  
<# Set and store context. 
Set-AzContext is a PowerShell cmdlet in the Az.Accounts module used to select the active subscription and tenant for your current Azure session in Microsoft Azure.#>
  
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

#######################################
# Begin script execution
#######################################

# Define variables for key vault
$vaultName  = "Az-KeyVault-Red929"
$secretName = "SVC-AD-Provision-929"
$userName   = "Red929\SVC_AD_Provision_01"

# Retrieve the secret directly as a SecureString
$securePassword = (Get-AzKeyVaultSecret -VaultName $vaultName -Name $secretName).SecretValue

# Create the PSCredential object
$credential = New-Object System.Management.Automation.PSCredential ($username, $securePassword)

# Logs into management shell with ps session
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://exchange01.red929.com/powershell -Authentication Kerberos -Credential $credential
Import-PSSession $Session -DisableNameChecking
        
# Create User mailbox - use cmdlet "New-RemoteMailbox"
$password = (ConvertTo-SecureString -String 'Password19187!!' -AsPlainText -Force)
New-RemoteMailbox -Name "Test Mailbox_06" -FirstName "Test06" -LastName "Mailbox6" -UserPrincipalName "Test.Mailbox6@red929.com" -Password $password -RemoteRoutingAddress "Test.Mailbox6@red929.mail.onmicrosoft.com"

Troubleshooting:

1. Cannot connect due to insufficient permission:

Resolution: EAC > permissions > admin role > Recipient Management or Organization Management role > add user > hit save

2. Get-mailbox not recognized as cmdlet

Resolution: Import the session variable over with “Import-PSSession $Session -DisableNameChecking”

3. Certificate error when using pssession

Resolution: Bypass certification check

$sessionOption = New-PSSessionOption -SkipRevocationCheck -SkipCACheck -SkipCNCheck
$url = "https://webmail.red929.com/powershell"
$Authentication = "Kerberos"

$EXOSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $URL -Credential $Credentials -Authentication $Authentication -AllowRedirection -SessionOption $sessionOption