/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:
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 $PasswordProfileReplace 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:
| Parameter | Notes |
|---|---|
| -AccountEnabled | Switch; include it to create an enabled account |
| -DisplayName | Name shown in address lists |
| -MailNickname | Mail alias, no spaces |
| -UserPrincipalName | Sign-in name; the domain must be verified in the tenant |
| -PasswordProfile | Hashtable 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:
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-ObjectOutput
PasswordProfile type: IMicrosoftGraphPasswordProfile AccountEnabled type: SwitchParameter ForceChangePasswordNextSignIn ForceChangePasswordNextSignInWithMfa Password
| Property | Meaning |
|---|---|
| Password | Initial 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):
$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
Import-Csv .\users.csv | ForEach-Object {
New-MgUser -DisplayName $_.DisplayName -MailNickname $_.Alias -UserPrincipalName $_.UPN `
-AccountEnabled -UsageLocation $_.Country `
-PasswordProfile @{ Password = $_.InitialPassword; ForceChangePasswordNextSignIn = $true }
}Sources
Related pages
commands · microsoft-graphSet-MgUserLicense: assign or remove Microsoft 365 licenses with Microsoft Graph PowerShellSet-MgUserLicense -UserId -AddLicenses @{SkuId=...} -RemoveLicenses @() assigns a license. Get SKU IDs from Get-MgSubscribedSku; set UsageLocation first.errors · microsoft-graphMicrosoft Graph PowerShell: Insufficient privileges to complete the operation (Authorization_RequestDenied)Graph returned 403: the token lacks the permission the call needs, or the user lacks the Entra role. Reconnect with the right -Scopes or grant the app role.commands · microsoft-graphConnect-MgGraph -Scopes: which permissions to request in Microsoft Graph PowerShellConnect-MgGraph -Scopes requests delegated Graph permissions such as User.Read.All. Find the scope a cmdlet needs with Find-MgGraphCommand; app-only differs.