Skip to content

/commands/microsoft-graph/new-mguser-passwordprofile

New-MgUser -PasswordProfile: create a Microsoft Entra user with PowerShell

verified onenvironmentlocal · windows 10.0.26200 arm64 · GNU bash 5.3.15 (Git Bash)updated
tool
Microsoft Graph PowerShell
versions
Microsoft.Graph.Users 2.41.2
os
windows, linux, macos

Create a cloud user with Microsoft Graph PowerShell. The password goes in a PasswordProfile hashtable:

powershell
Connect-MgGraph -Scopes "User.ReadWrite.All"

$PasswordProfile = @{
  Password                      = 'xWwvJ]6NMw+bWH-d'
  ForceChangePasswordNextSignIn = $true
}
New-MgUser -DisplayName 'Rene Magi' -MailNickname 'ReneMagi' `
  -UserPrincipalName 'ReneMagi@contoso.com' -AccountEnabled -PasswordProfile $PasswordProfile

Replace the example password with a generated one. Creating users requires the User.ReadWrite.All (or Directory.ReadWrite.All) permission and, for delegated sign-in, the User Administrator role or higher.

Required properties

The Graph API requires these properties to create a user:

ParameterNotes
-AccountEnabledSwitch; include it to create an enabled account
-DisplayNameName shown in address lists
-MailNicknameMail alias, no spaces
-UserPrincipalNameSign-in name; the domain must be verified in the tenant
-PasswordProfileHashtable with Password and ForceChangePasswordNextSignIn

PasswordProfile properties

-PasswordProfile is typed IMicrosoftGraphPasswordProfile; a hashtable with the same keys converts to it. The properties in module 2.41.2, checked offline:

powershell
Import-Module Microsoft.Graph.Users
$p = (Get-Command New-MgUser).Parameters
'PasswordProfile type: ' + $p['PasswordProfile'].ParameterType.Name
'AccountEnabled type:  ' + $p['AccountEnabled'].ParameterType.Name
[Microsoft.Graph.PowerShell.Models.MicrosoftGraphPasswordProfile].GetProperties().Name |
  Where-Object { $_ -ne 'EntityItem' } | Sort-Object

Output

PasswordProfile type: IMicrosoftGraphPasswordProfile
AccountEnabled type:  SwitchParameter
ForceChangePasswordNextSignIn
ForceChangePasswordNextSignInWithMfa
Password
PropertyMeaning
PasswordInitial password; must meet the tenant password policy
ForceChangePasswordNextSignIn$true makes the user set a new password at first sign-in
ForceChangePasswordNextSignInWithMfa$true also requires MFA registration before the change

Add a usage location and a license

A license can be assigned only when UsageLocation is set (a two-letter country code):

powershell
$user = New-MgUser -DisplayName 'Rene Magi' -MailNickname 'ReneMagi' -UserPrincipalName 'ReneMagi@contoso.com' `
  -AccountEnabled -PasswordProfile $PasswordProfile -UsageLocation 'US' -Department 'Sales'
Set-MgUserLicense -UserId $user.Id -AddLicenses @{SkuId = 'SKU_GUID'} -RemoveLicenses @()

See Set-MgUserLicense for finding the SKU ID.

Bulk creation from CSV

powershell
Import-Csv .\users.csv | ForEach-Object {
  New-MgUser -DisplayName $_.DisplayName -MailNickname $_.Alias -UserPrincipalName $_.UPN `
    -AccountEnabled -UsageLocation $_.Country `
    -PasswordProfile @{ Password = $_.InitialPassword; ForceChangePasswordNextSignIn = $true }
}

Sources