Joanne: This guest post is written by my mentee, Sheldon Appleyard. I’ve invited Sheldon to be a guest blogger at joannecklein.com and encouraged him to write content and share knowledge about practical things he’s learned for an audience just starting out in Microsoft 365. Creating user accounts using PowerShell is a fundamental task and the focus of this post by Sheldon.
Sheldon: Hello, my name is Sheldon Appleyard and I’m an IT Pro who has worked in the IT industry for 10 years. Like many, I have been branching out into the Microsoft Cloud over the past 4 years and have been learning as much as I can as I go along. Joanne has graciously offered to mentor me and has invited me to post blogs on her site as I start my adventures in the Microsoft Cloud. Join me as I post about the things I learn and how to implement them for your own use. Feel free to reach out to me on my LinkedIn profile.
In my previous post, Creating a Microsoft 365 User Account the GUI way, I showed how to create a Microsoft 365 user account using the Admin portal. In this post, I’ll demonstrate how to achieve the same result with just a few lines of PowerShell code. Using PowerShell to create a user account can be a much more efficient way to create an account. It removes all the screens used in the Admin portal and replaces them with a few cmdlets. More importantly, a reusable script can be created using the cmdlets to automate the process. Automating the creation of user accounts makes the process quicker, prevents human error, and can be set up to handle multiple locations. Read on to learn about the commands used for adding a new user and assigning licenses and roles to an account.
Requirements
Permissions… to add an account to AzureAD, you will need either the Global Admin role or User Admin role.
AzureAD module… the commands we will be using to add the new user are part of the AzureAD module which needs to be installed ahead of time.
Creating a user account
To begin, we will need to connect to AzureAD through PowerShell. If you need to know how to do this, check out my previous post on connecting to AzureAD called Connecting PowerShell to Office 365. Once you have connected to AzureAD, we can run the New-AzureADUser cmdlet for adding the new user. This cmdlet takes in all the parameters needed for creating a user account except it does not allow you to assign licenses or add admin roles. We will need to use separate commands to do that. A key thing to understand before using the New-AzureADUSer cmdlet is that it requires the password to be passed to it using a Password Profile object. This object contains your password along with other properties such as if you want to force the user to change the password upon first login. I will go into this in more detail later. Understanding that you need a password profile object informs us that our first steps will be to create this object using the following commands
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = “P@55word”
With these two simple commands we have created the basic password profile needed to create our new user. Next we will create the new user.
The required properties for the New-AzureADUser cmdlet are as follows:
- DisplayName
- UserPrincipalName
- AccountEnabled
- PasswordProfile
The full command is as follows.
New-AzureADUSer -DisplayName “DISPLAYNAME” -PasswordProfile $PasswordProfile -UserPrincipalName “EMAILADDRESS” -AccountEnabled $true
As you see in the screenshot, I created a new user account using the required properties including the pre-created password profile. Once the command has been successfully run, it will display the basic information for the account in the PowerShell Window. Although this created the user account with the basic required properties, in most cases you will need to supply much more than that. Let’s create an account closer to what we did in my previous GUI post.
First we will need to expand on the password profile object. Along with a password property there are two other properties:
- EnforceChangePasswordPolicy
- ForceChangePasswordNextLogin
It is recommended to force the user to reset their password as soon as possible so we are going to use ForceChangePasswordNextLogin property to do this, which will enable the option to force a user to change their password at next login. To do this, we add the following command when we are creating the password profile object.
$PasswordProfile.ForceChangePasswordNextLogin = $true
Let’s expand on the New-AzureADUser cmdlet which has many more properties we can use. We are going to focus on the ones for the new account’s name, country and other profile location data.
- GivenName
- SurName
- MailNickName
- City
- State
- Country
- UsageLocation *
* Note: Usage Location expects a two-letter country code.
These new properties allow you to pass in profile information for the user as well as set the usage location which is important when assigning a license. You can approach this in two ways. If you are just typing at the command line you can enter in the strings for each parameter or you can store the data in variables which is the more common way of doing things if you are using a script to create a new user. This allows for a level of automation in your script and the opportunity to prompt a user for the data to store in these variables such as the user’s name and branch office. Our new command will look like this.
New-AzureAdUser -DisplayName “DISPLAYNAME” -GivenName “FIRSTNAME”
-SurName “LASTNAME” -PasswordProfile $PasswordProfile
-UserPrincipalName “EMAILADDRESS” -MailNickName “NICKNAME” -City “CITYNAME” -State “STATEPROVINCENAME” -Country “COUNTRY” -UsageLocation “COUNTRYCODE”
See screen shot below for all the commands put together.
Assign Licenses
Now that we have our users created, we need to add license(s) to them. To do this we will be using Set-AzureADUserLicense cmdlet. This cmdlet accepts 2 parameters:
- ObjectId
- AssignedLicenses
Before we can use this cmdlet, an Assigned Licenses object needs to be created with the correct license. To do this, we first need to look up the Sku Part Number for the license(s) we need to assign. We will do this by selecting the Sku Part Number with the Get-AzureADSubscribedSku cmdlet which will display all the available licenses. Find the Sku Part Number you want to assign and store it in a string variable. This will be used to assign a Sku id to an assigned license object.
The next step will be to create an Assigned License object to store each license we are going to assign to the user. Use the following commands to achieve this.
$License = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicense
$License.SkuId = (Get-AzureADSubscribeSku | Where-Object -Property SkuPartNumber -Value $LicenseName -EQ).SkuID
Now we are ready to assign the licenses for the user by creating the Assigned Licenses object needed for the Set-AzureADUserLicense cmdlet. This is different from the previous object created. The previous object is used for storing the license based on the Sku id and you can also provide a list of service plans you do not want enabled if you need to customize the available products. This new object is used to store the license and then assign it to the user when called in the Set-AzureADUSerLicense command. It will also disable all the service plans listed in the list also attached to that object. We are going to run the following commands to create and populate the Assigned Licenses object.
$LicensesToAssign = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicenses
$LicenseToAssign.AddLicenses = $License
We now assign the license to the user by running the following command.
Set-AzureADUserLicense -ObjectId “EMAILADDRESS” -AssignedLicenses $LicensesToAssign
You can see all the steps together in the screen shot below.
Assign an Admin Role
The last thing I want to go over is assigning an Admin Role to the user. To assign roles in PowerShell, we use the Add-AzureADDirectoryRoleMember cmdlet. This cmdlet accepts the object id for the Admin Role we need to add and an object id for the user we are assigning the role to.
- ObjectId
- RefObjectId
Before using the command, you will need to do a few steps to get the object id’s needed. First let’s get the object id for the Admin role. We are going to assume the role you are wanting to assign is already instantiated and available to assign and we are going to use the following command to get the object id and store it in a variable. To see all the Admin roles, go to Microsoft’s reference site. Make sure to pay attention to the notes if there are any as some roles have different names in PowerShell.
$Role = Get-AzureADDirectoryRole | Where-Object { $_.displayName -eq “ADMINROLE”}
The above command looks for a specific role and assigns it to the variable for use later. Now let’s get the object id for the user we need to assign this role to. Use the following command below to do this.
$User = Get-AzureADUser -ObjectId “EMAILADDRESS”
This command searches for a user and assigns the user object found to the variable for use later. Now we have what we need to add the role to the user:
Add-AzureADDirectoryRoleMember -ObjectId $Role.ObjectId -RefObjectId $User.ObjectId
Screen shot below shows all the commands together.
Another task done
This post demonstrated how to create a new user through PowerShell just like you would by using the Admin Portal GUI. I strongly urge you to use this knowledge to create scripts to automate the creation of new users in your environment.
-Sheldon
Awesome – thank you for a clear explanation and instructions…On the point of licensing, for bulk users, I would instead choose Group based licensing (i.e. create a security group, assign it the appropriate licenses and then assign the group to the users)…not to say what you have done is wrong by any means!