Menu Close

Updating Windows Azure Active Directory with PowerShell

In a previous blog, I showed how to use PowerShell and a CS file to create and provision security groups in a SharePoint Online site collection. Recently, a client requested that we also provision a set of users at the tenant level. This requires updating the Windows Azure Active Directory (AD) for the tenant.

There are several approaches for this task. With proper administrative permissions, you can add tenant users in the Office 365 admin center under Users and Groups. You can add either one user at a time, or by clicking the “Bulk Add” icon, open a page for importing a CSV file that contains bulk user information.


On the “Bulk add users page”, you have options for downloading a sample CSV file, or browsing for a file you already created.


This starts a series of steps (see the left navigation) that you can follow to import, create, and confirm a set of tenant users. While this works well, I will show you how to use PowerShell to add multiple users to a tenant even more efficiently. The first time through the process will require some setup, but subsequent runs should be much faster.

We will use the PowerShell cmdlet New-MsolUser to add new users to Windows Azure AD. This cmdlet has a number of parameters, most of which are optional. You can provision users with as few as 2 or as many as about 30 parameters. In this blog, we will use 10 parameters. For a detailed description of how to use the cmdlet, see this TechNet article.


Before using the New-MsolUser cmdlet, you will need certain software prerequisites. Please read this article for details. For running PowerShell, you can use either PowerShell ISE v3 or SharePoint Online Management Shell. I recommend using ISE; just make sure you load the Microsoft.Online.SharePoint.PowerShell module with the following cmdlet:

      Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking

As mentioned, you can provision users with only 2 parameters; however most users will need to access tenant services, which require assigning a license (using the LicenseAssignment parameter). In order to do that, you will need to log into the SPO tenant and use the Get-MsolAccountSku cmdlet to get a list of the licenses currently available on the tenant. Make a note of this information, as you will need it later.


Create the CSV File

We are now ready to create the CSV file. Follow these steps:

1. Open Excel and add the following items to the first row:


Note that of the above fields, only DisplayName and UserPrincipalName are required; the remaining are optional. As described in the TechNet article, there are about 20 other parameters that can be used with this cmdlet. Add or subtract from the above list according to your organization’s needs.

2. In the second row, add data entries for the first user you wish to provision. Examples are given below:

      FirstName: Alex
      LastName: Darrow
      DisplayName: Alex Darrow
      UserPrincipalName: alexd@<tenant>
      LicenseAssignment: <tenant>:PROJECTONLINE_PLAN_2
      UsageLocation: US
      JobTitle: Product Manager
      Department: Sales and Marketing
      Office: B100-206

3. Repeat the last step until you have added data for all the users.

4. Save the file as c:\scripts\UserFile.csv. If you do not have a c:\scripts directory, create one, or save the file to any other location on your local machine.

Create the PowerShell Script

You will now create a PowerShell script. I recommend you use PowerShell ISE, though you can also use NotePad or another text editor. The script will (1) connect to a SharePoint Online tenant; (2) display the license SKU(s); (3) display the current users; (4) create new users from the CSV file; (5) export a CSV file with the list of new users; and (6) display the new users on the screen.

Follow these steps to create the script:

1. Start PowerShell ISE or NotePad as an administrator.

2. Copy the following text and paste it into the script window:

$cred = Get-Credential
Connect-MsolService -Credential $cred
Get-MsolUser | Sort-Object -property DisplayName |Format-Table -AutoSize
$userfile = “c:\scripts\UserFile.csv”
Import-Csv -Path $userfile | ForEach-Object {
   New-MsolUser `
    -FirstName $_.FirstName `
    -LastName $_.LastName `
    -UserPrincipalName $_.UserPrincipalName `
    -DisplayName $_.DisplayName `
    -LicenseAssignment $_.LicenseAssignment `
    -UsageLocation $_.UsageLocation `
    -Title $_.JobTitle `
    -Department $_.Department `
    -Office $_.Office `
    -Password “Pass@temp2”
    } | Export-Csv -Path C:\Scripts\Provisioned_users.csv -Append
write-host “Updated users”
Get-MsolUser | Sort-Object -property DisplayName |Format-Table -AutoSize

 Notes: if you saved the CSV file to another location, change the path as needed. If you include the Password parameter and are enforcing strong passwords (which is the default), be sure it conforms to the standards for strong passwords as stated in the TechNet article. By default, the user will be forced to change passwords at first logon; this can also be changed if desired by a separate parameter.

3. Save the script as c:\scripts\MsolActiveDir.ps1. You can use any other filename, but be sure to use the .ps1 extension. Close the editor.

Once the CSV file has been created and your environment is ready, get administrative credentials for the tenant that you will be updating. For example, the login might be admin@<tenant>, and the password pass@word32. To run the script:

4. Open PowerShell ISE or SharePoint Management Shell with elevated permissions.

5. At the command prompt, in succession type the following and press ENTER.

      cd c:\scripts

6. You will get a login screen similar to the following. Enter the administrative user name and password, and then click OK.

7. When the script completes, you should see an output screen similar to the following. Note that Alex Darrow has been added to the list of users (yellow highlight), and that he has a license for Project Online, plan 2.

8. At this point, if you are done, it is good practice to disconnect from the tenant. At the command prompt, type the following and press ENTER:


9. Optionally, start Excel and open the exported CSV file listing the new users. You can also log into the tenant, navigate to the Office 365 admin center, click  Users and Groups, and confirm the users have been added.

You now have an example for how to provision Windows Azure Active Directory (AD) using a simple PowerShell script and a CSV file. You can easily modify both the CSV file and script as needed. Just be sure to follow the parameter naming conventions in the TechNet article I referenced earlier. I hope this blog is helpful to those who need an automated process for provisioning their Office 365 tenant users. That’s it for now!