New-EntraUser
Creates a Microsoft Entra ID user.
Syntax
New-EntraUser
-DisplayName <String>
-AccountEnabled <Boolean>
-PasswordProfile <PasswordProfile>
[-City <String>]
[-UserStateChangedOn <String>]
[-CompanyName <String>]
[-PreferredLanguage <String>]
[-FacsimileTelephoneNumber <String>]
[-GivenName <String>]
[-Mobile <String>]
[-UsageLocation <String>]
[-PostalCode <String>]
[-AgeGroup <String>]
[-CreationType <String>]
[-ExtensionProperty <System.Collections.Generic.Dictionary`2[System.String,System.String]>]
[-ConsentProvidedForMinor <String>]
[-MailNickName <String>]
[-ImmutableId <String>]
[-Country <String>]
[-SignInNames <System.Collections.Generic.List`1[Microsoft.Open.AzureAD.Model.SignInName]>]
[-Department <String>]
[-PasswordPolicies <String>]
[-JobTitle <String>]
[-IsCompromised <Boolean>]
[-UserState <String>]
[-UserType <String>]
[-OtherMails <System.Collections.Generic.List`1[System.String]>]
[-PhysicalDeliveryOfficeName <String>]
[-UserPrincipalName <String>]
[-State <String>]
[-StreetAddress <String>]
[-TelephoneNumber <String>]
[-Surname <String>]
[-ShowInAddressList <Boolean>]
[<CommonParameters>] Description
The New-EntraUser cmdlet creates a user in Microsoft Entra ID.
Examples
Example 1: Create a user using MailNickName parameter
Connect-Entra -Scopes 'User.ReadWrite.All'
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Password>'
$userParams = @{
DisplayName = 'Avery Iona'
PasswordProfile = $PasswordProfile
UserPrincipalName = 'AveryI@contoso.com'
AccountEnabled = $true
MailNickName = 'averyi'
}
New-EntraUser @userParams
ObjectId DisplayName UserPrincipalName UserType
-------- ----------- ----------------- --------
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Avery Iona AveryI@contoso.com MemberThis command creates a new user.
Example 2: Create a user using AgeGroup parameter
Connect-Entra -Scopes 'User.ReadWrite.All'
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Password>'
$userParams = @{
DisplayName = 'Peyton Davis'
PasswordProfile = $PasswordProfile
UserPrincipalName = 'PeytonD@contoso.com'
AccountEnabled = $true
MailNickName = 'PeytonD'
AgeGroup = 'adult'
}
New-EntraUser @userParams
ObjectId DisplayName UserPrincipalName UserType
-------- ----------- ----------------- --------
bbbbbbbb-1111-2222-3333-cccccccccccc Peyton Davis PeytonD@contoso.com MemberThis command creates a new user.
Example 3: Create a user using City parameter
Connect-Entra -Scopes 'User.ReadWrite.All'
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Password>'
$userParams = @{
DisplayName = 'Blake Martin'
PasswordProfile = $PasswordProfile
UserPrincipalName = 'BlakeM@contoso.com'
AccountEnabled = $true
MailNickName = 'BlakeM'
City = 'New York'
}
New-EntraUser @userParams
ObjectId DisplayName UserPrincipalName UserType
-------- ----------- ----------------- --------
cccccccc-2222-3333-4444-dddddddddddd Blake Martin BlakeM@contoso.com MemberThis command creates a new user.
Example 4: Create a user using Department parameter
Connect-Entra -Scopes 'User.ReadWrite.All'
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Password>'
$userParams = @{
DisplayName = 'Parker Jones'
PasswordProfile = $PasswordProfile
UserPrincipalName = 'ParkerJ@contoso.com'
AccountEnabled = $true
MailNickName = 'ParkerJ'
Department = 'IT'
}
New-EntraUser @userParams
ObjectId DisplayName UserPrincipalName UserType
-------- ----------- ----------------- --------
dddddddd-3333-4444-5555-eeeeeeeeeeee Parker Jones ParkerJ@contoso.com MemberThis command creates a new user.
Example 5: Create a user using Mobile parameter
Connect-Entra -Scopes 'User.ReadWrite.All'
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Password>'
$UserParams = @{
DisplayName = 'Sawyer Miller'
PasswordProfile = $PasswordProfile
UserPrincipalName = 'SawyerM@contoso.com'
AccountEnabled = $true
MailNickName = 'SawyerM'
Mobile = '+18989898989'
}
New-EntraUser @UserParams
ObjectId DisplayName UserPrincipalName UserType
-------- ----------- ----------------- --------
eeeeeeee-4444-5555-6666-ffffffffffff Sawyer Miller SawyerM@contoso.com MemberThis command creates a new user.
Parameters
-AccountEnabled
Indicates whether the user's account is enabled.
| Type: | System.Boolean |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AgeGroup
This specifies the user's age group.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-City
Specifies the user's city.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CompanyName
This specifies the user's company name.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ConsentProvidedForMinor
Sets whether consent was obtained for minors.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Country
Specifies the user's country.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CreationType
Indicates whether the user account is a local account for a Microsoft Entra ID B2C tenant. Possible values are "LocalAccount" and null.
When creating a local account, the property is required and you must set it to "LocalAccount".
When creating a work or school account, don't specify the property or set it to null.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Department
Specifies the user's department.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisplayName
Specifies the user's display name.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ExtensionProperty
Add data to custom user properties as the basic open extensions or the more versatile schema extensions.
| Type: | System.Collections.Generic.Dictionary`2[System.String,System.String] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FacsimileTelephoneNumber
This specifies the user's telephone number.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-GivenName
Specifies the user's given name.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ImmutableId
This property is used to associate an on-premises user account to their Microsoft Entra ID user object. This property must be specified when creating a new user account in the Graph if you're using a federated domain for the user's userPrincipalName (UPN) property.
Important: The $ and _ characters can't be used when specifying this property.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IsCompromised
Indicates whether this user is compromised.
| Type: | System.Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-JobTitle
Specifies the user's job title.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MailNickName
Specifies the user's mail nickname.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Mobile
Specifies the user's mobile phone number.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OtherMails
A list of other email addresses for the user; for example: 'bob@contoso.com', 'robert@fabrikam.com'.
| Type: | System.Collections.Generic.List`1[System.String] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PasswordPolicies
Specifies password policies for the user. This value is an enumeration with one possible value being "DisableStrongPassword", which allows weaker passwords than the default policy to be specified. "DisablePasswordExpiration" can also be specified. The two might be specified together; for example: "DisablePasswordExpiration, DisableStrongPassword".
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PasswordProfile
Specifies the user's password profile.
The parameter type for this parameter is "PasswordProfile".
In order to pass a parameter of this type, you first need to create a variable in PowerShell with that type:
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
Then you can proceed to set the value of the password in this variable:
$PasswordProfile.Password = "<Password>"
And finally you can pass this variable to the cmdlet:
New-EntraUser -PasswordProfile $PasswordProfile ...
Other attributes that can be set in the PasswordProfile are
$PasswordProfile.EnforceChangePasswordPolicy - a boolean indicating that the change password policy is enababled or disabled for this user $PasswordProfile.
ForceChangePasswordNextLogin - a boolean indicating that the user must change the password at the next sign in.
| Type: | PasswordProfile |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PhysicalDeliveryOfficeName
Specifies the user's physical delivery office name.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PostalCode
Specifies the user's postal code.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreferredLanguage
Specifies the user's preferred language.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ShowInAddressList
If True, show this user in the address list.
| Type: | System.Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SignInNames
Specifies the collection of sign-in names for a local account in a Microsoft Entra ID B2C tenant.
Each sign-in name must be unique across the company/tenant.
The property must be specified when you create a local account user; don't specify it when you create a work or school account.
| Type: | System.Collections.Generic.List`1[Microsoft.Open.AzureAD.Model.SignInName] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-State
Specifies the user's state.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-StreetAddress
Specifies the user's street address.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Surname
Specifies the user's surname.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TelephoneNumber
Specifies a telephone number.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UsageLocation
A two letter country code (ISO standard 3166).
Required for users that are assigned licenses due to legal requirement to check for availability of services in countries.
Examples include: "US", "JP", and "GB".
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserPrincipalName
The user principal name (UPN) of the user.
The UPN is an Internet-style login name for the user based on the Internet standard RFC 822.
By convention, this should map to the user's email name.
The general format is "alias@domain". For work or school accounts, the domain must be present in the tenant's collection of verified domains.
This property is required when a work or school account is created; it's optional for local accounts.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserState
For an external user invited to the tenant using the invitation API, this property represents the invited user's invitation status.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserStateChangedOn
Shows the timestamp for the latest change to the userState property.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserType
A string value that can be used to classify user types in your directory, such as "Member" and "Guest".
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Related Links
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for