Migrating from New-AzureADUser to New-MgUser

As Microsoft deprecates the AzureAD module in favor of the Microsoft Graph PowerShell SDK, IT admins must begin transitioning their scripts to Graph equivalents. One of the most common provisioning tasks—creating a user account—was previously handled using New-AzureADUser. Going forward, this task is managed using the modern New-MgUser cmdlet.

In this article, we’ll guide you through the migration from New-AzureADUser to New-MgUser, show the syntax differences, and provide real examples for smooth script upgrades.

What You Did Previously with New-AzureADUser

In the AzureAD module, user creation was fairly straightforward and used named parameters.

Create a Single User

New-AzureADUser -DisplayName "John Doe" `
    -UserPrincipalName "john.doe@yourdomain.com" `
    -MailNickname "john.doe" `
    -PasswordProfile @{Password = "Password123"; ForceChangePasswordNextLogin = $true} `
    -AccountEnabled $true
                                        

Bulk User Creation

$users = Import-Csv -Path "Users.csv"
foreach ($user in $users) {
    New-AzureADUser -DisplayName $user.DisplayName `
        -UserPrincipalName $user.UserPrincipalName `
        -MailNickname $user.MailNickname `
        -PasswordProfile @{Password = $user.Password; ForceChangePasswordNextLogin = $true} `
        -AccountEnabled $true
}
                                        

This approach worked well but was tied to a legacy module that lacks support for the broader Microsoft Graph ecosystem.

What You Should Do Now with New-MgUser

With Microsoft Graph PowerShell, the modern replacement is New-MgUser. While the objective is the same—creating users—the Graph approach encourages more consistent and structured use of hashtables via the -BodyParameter.

Example 1: Create a User

New-MgUser -DisplayName "John Doe" `
    -UserPrincipalName "john.doe@yourdomain.com" `
    -MailNickname "john.doe" `
    -PasswordProfile @{Password = "Password123"; ForceChangePasswordNextSignIn = $true} `
    -AccountEnabled $true
                                        

Example 2: Bulk User Creation from CSV

$users = Import-Csv -Path "Users.csv"
foreach ($user in $users) {
    $userParams = @{
        DisplayName        = $user.DisplayName
        UserPrincipalName  = $user.UserPrincipalName
        MailNickname       = $user.MailNickname
        AccountEnabled     = $true
        PasswordProfile    = @{
            Password = $user.Password
            ForceChangePasswordNextSignIn = $true
        }
    }
    New-MgUser -BodyParameter $userParams
}
                                            

✅ Pro Tip: Microsoft Graph encourages the use of -BodyParameter to structure complex data input, especially when bulk processing users or passing nested data like PasswordProfile.

What’s Different with New-MgUser?

Old (New-AzureADUser)	New (New-MgUser)
Used -ForceChangePasswordNextLogin	Uses -ForceChangePasswordNextSignIn
Named parameters were common	Complex scenarios use -BodyParameter
Accepts user properties directly	Requires hashtable for nested objects
Part of AzureAD module (deprecated)	Part of Microsoft.Graph.Users module
Focused on Azure AD	Graph supports broader M365 capabilities

Conclusion

Migrating from New-AzureADUser to New-MgUser is an essential step in modernizing your M365 provisioning scripts. While the Graph syntax may initially seem verbose—especially with -BodyParameter—it provides far more control, extensibility, and compatibility with other Microsoft 365 services.

Start migrating today to future-proof your PowerShell workflows and stay aligned with Microsoft’s official best practices.