The New-MgUser cmdlet allows you to create new users in your Azure Active Directory. As you can imagine, there are many different attributes you can set when creating a new user, all of which can be found in the Microsoft Graph PowerShell reference documentation.
In this tutorial, I am going to show you how to create a new user (and multiple new users) using Microsoft Graph PowerShell.
Pre-requisites
For this tutorial, you must have the Microsoft Graph PowerShell module installed. If you do not have it installed already, check out my guide on How To Install the Microsoft Graph PowerShell Module. The guide will also walk you through how to update your module to the latest version if it has been a while since you have updated.
About the New-MgUser cmdlet
The New-MgUser cmdlet can be found in the Microsoft.Graph.Users module, so to use the command, the module must first be imported into the current PowerShell session. This can be done with the following command:
Import-Module Microsoft.Graph.UsersThere are also many different permissions which cover the use of this cmdlet, with the least permissive being User.ReadWrite.All.
You can use the following command to view which permissions enable you to use the New-MgUser cmdlet:
(Find-MgGraphCommand -command New-MgUser -apiversion v1.0 | `
select Permissions).permissionsYour output will look like the below:
What attributes are required for creating a new user?
When creating a new user account in your Azure Active Directory (or Microsoft 365), there is a minimum amount of information you must define, for your user creation request to be successful.
The following Attributes must be defined always when using the New-MgUser cmdlet:
- -DisplayName “String”
- -PasswordProfile @{HashTable}
- -AccountEnabled
- -MailNickName “String”
- -UserPrincipalName “String”
How to create a password profile
An important part of creating a new user is defining the password settings that will apply. These password settings, as you can see written above, are defined within a hash table.
There are 3 settings you can define within the hash table, which you can see an example of below:
$PasswordProfile = @{
Password = 'Helo123!'
ForceChangePasswordNextSignIn = $true
ForceChangePasswordNextSignInWithMfa = $true
}Password – This is the password that is assigned to the user when the account is created. This is the only required value pair within the hash table, which means the other settings are optional but recommended.
ForceChangePasswordNextSignIn – When this value is set to $true, when the user next signs in, they will be forced to update their password. If this option is not specified, the default setting is $false.
ForceChangePasswordNextSignInWithMfa – This is the same as the above settings, however this time, the user will be forced to complete MFA registration or a challenge before being asked to change their password. If this option is not specified, the default setting is $false.
How to create a new user with Microsoft Graph PowerShell
To create your new user using the New-MgUser cmdlet, you can copy the example below and change the information between every quote.
Connect-MgGraph -scope User.ReadWrite.All
New-MgUser -DisplayName ‘New User’ -PasswordProfile $PassProfile `
-AccountEnabled -MailNickName ‘NewUser’ `
-UserPrincipalName '[email protected]’
To copy and paste the full script, you can use the below:
##Import the Microsoft Graph Users module
Import-Module Microsoft.Graph.Users
##Connect to Microsoft Graph with the user read/write permission
Connect-MgGraph -scope User.ReadWrite.All
##Define the password profile settings within a hash table
$PasswordProfile = @{
Password = "Helo123!"
ForceChangePasswordNextSignIn = $true
ForceChangePasswordNextSignInWithMfa = $true
}
##Create the new user account
New-MgUser -DisplayName "New User" -PasswordProfile $PasswordProfile `
-AccountEnabled -MailNickName "NewUser" `
-UserPrincipalName "[email protected]"How to create multiple users from a CSV
Often you may find that you need to create multiple new users accounts at once. The simplest way to do this is to ask the hiring or similar department to provide you with a list of users with all the desired user information in an excel file or CSV file.
You can use the example CSV file I have available on my GitHub here.
Below you will find the full example script to create multiple users with Microsoft Graph PowerShell from a CSV.
##Import the Microsoft Graph Users module
Import-Module Microsoft.Graph.Users
##Connect to Microsoft Graph with the user read/write permission
Connect-MgGraph -scope User.ReadWrite.All
##Import csv user list
$newusers = Import-CSV "C:\temp\newusers.csv"
##Define the password profile settings within a hash table
$PasswordProfile = @{
Password = "Helo123!"
ForceChangePasswordNextSignIn = $true
ForceChangePasswordNextSignInWithMfa = $true
}
##Loop through and create each user
ForEach ($user in $newusers){
New-MgUser -DisplayName $user.displayname `
-PasswordProfile $PasswordProfile `
-AccountEnabled `
-MailNickName $user.mailnickname `
-UserPrincipalName $user.userprincipalname `
-Department $user.department `
-JobTitle $user.jobtitle `
-Mobile $user.mobile `
-Birthday $user.birthday `
-Country $user.country
}Now you have created your user accounts, you can also take a look at:
How can we add the manager to this as well as group memberships? I cannot tell what the expected input for manager is, is it their full upn? For Group membership we have dynamic licensing based on group but I don’t see where I could add that as well as we are currently doing for our on prem then hybrid AD sync.
You can’t with the New-MgUser cmdlet, it is a bit daft as the -manager parameter is documented by Microsoft, however, the documentation is auto-generated and poor.
You can add a manager with the Set-MgUserManagerByRef cmdlet.
$NewManager = @{
“@odata.id”=”https://graph.microsoft.com/v1.0/users/$ManagerUserId”
}
Set-MgUserManagerByRef -UserId $UserId -BodyParameter $NewManager
Ahh that’s too bad. So it will have to be a 2 step process. We onboard 20-30 users a week so that really kills our current process. Is this the same for adding to 365 groups as well?