Use PowerShell to Manage Office 365 Users


Summary: Microsoft Scripting Guy, Ed Wilson, talks about using Windows PowerShell to manage Office 365 users.

Microsoft Scripting Guy, Ed Wilson, is here. The weather here in Charlotte has been nearly perfect recently. I love spring. It offers hope, and it seems to be a time of renewed commitments. A quick trip to the garden center, and the Scripting Wife and I return with bundles of flowers and other stuff to plant. It is the very essence of hope. We hope they will thrive. We hope to enjoy their blooms in the future. We hope they will not overtake the rest of our garden. Ah, lots of hope.

     Note  This is the third in a series of Hey, Scripting Guy! Blog posts where I talk about using Windows PowerShell
     with Office 365.

  • In Getting Started with Office 365 and PowerShell, I talked about setting up a demo environment and installing the prerequisite software to enable Windows PowerShell management of the demo environment. I also walked through the installation of the management module.
  • In Use PowerShell to Explore Office 365 Installation, I talked about using Windows PowerShell to explore the settings and the capabilities of my Office 365 tenant installation.
  • In today’s post, I talk about finding unlicensed users, removing users, and modifying users.

In some respects, as IT pros, we invest in Office 365 technology in much the same way as I invest in flowers. We hope that in the future we will receive the promised benefit. We hope that Office 365 will be more stable, easier to manage, easier to maintain, and therefore provide a promised benefit to the bottom line. One of the keys to unlocking that promise is knowing how to use Windows PowerShell.

The first thing I need to do is to connect to Office 365. To do this, I am using the stored credential that I talked about in yesterday’s blog post, and then I use a cmdlet to make my connection to Office 365. The two commands are shown here:

$cred = Import-Clixml C:\fso\cred.xml

Connect-MsolService -Credential $cred

When I am connected, I like to user the Get-Command cmdlet to display available Windows PowerShell commands. This is shown in the image that follows:

Image of command output

Because this is Windows PowerShell, I can use standard Windows PowerShell techniques to discover commands that I need to use. Then when I have found the cmdlet, I can use Get-Help to find examples of use. Here are some ideas keep in mind:

  • Use Get-Command to find cmdlets. The main module to use is the MSOnline module.
  • Use Tab expansion to expand the names of cmdlets, and also the names of modules. Hit the Tab key, and it will cycle through available options.
  • To find Help, use the Get-Help cmdlet. If you are using Windows PowerShell 4.0 or Windows PowerShell 3.0, you need to first open the Windows PowerShell console with admin rights, and then use the Update-Help cmdlet to update all the Help for modules.
  • Use the Get-Member cmdlet to find object properties to use when filtering.
  • Use the Where-Object cmdlet to reduce or to filter returned information.
  • Use the Group-Object cmdlet to group returned objects by properties.
  • Use the Out-GridView to produce a usable control that permits filtering and sorting.
  • Use the Show-Command cmdlet to produce a floatable control that permits you to easily fill in options.
  • Use the Measure-Object cmdlet for counting.

Display and work with users

To display basic user information about the Office 365 users, use the Get-MsolUser cmdlet. To count the number of users, use the Measure-Object (measure is an alias) cmdlet. The use of these two cmdlets is shown in the image that follows:

Image of command output

It is pretty obvious from the previous image that I have 32 total users, but some are licensed and some are not. Therefore, I want to know how many of each type user exists. I can use the Group-Object cmdlet to figure this out. The best way to use Group-Object is to first sort the data and then group the data. The command is:

Get-MsolUser | Sort islicensed | group islicensed

This command displays the needed information, but the output is a bit clunky. This is because of the grouping information that says it is a bunch of user objects. I already knew that. Therefore, to clean up the list, I want to remove the element grouping information. To do that, I add the –noelement switch to the command. The output from the two commands is shown here:

Image of command output

I want to get a good list of users that are not licensed. I can do this by piping my list of users to Where-Object and filtering on the islicensed property. I come up with the following command:

Get-MsolUser | where {-not $_.islicensed}

But then I start thinking…

Dude, this is a lot of work. And not only that—it is inefficient. This is because it needs to get the list of users, and then filter them. So I use the Get-Command cmdlet, and I find that there is a switch parameter that I can use. The command is shown here:

Get-Command Get-MsolUser | select -expand Definition

The output from the command is shown here:

Image of command output

I re-run the command using the LicenseReconciliationNeededOnly switch parameter, and I see the output is exactly the same.

Note  The switch parameter is really long, so please do not fool with trying to type it. Use Tab expansion until it appears. This will ensure that it is spelled correctly, and save at least 30 seconds of typing.

The output from the two commands is shown here:

Image of command output

Remove unlicensed users

I know that I said Windows PowerShell is Windows PowerShell is Windows PowerShell. But not always…

Unfortunately, this is not always exactly true. For example, I would have expected the Remove-MsolUser cmdlet to implement ShouldProcess, so that I could use the –whatif parameter to see what a cmdlet would do. But unfortunately, it does not.

What the cmdlet does do, is default to using –confirm, but there is no –confirm parameter available either. So when I try to run the following command, it prompts for each of the user objects:

Get-MsolUser -LicenseReconciliationNeededOnly | Remove-MsolUser

This is no good for automation. So I try a couple of things, and I eventually find that the cmdlet actually uses the –Force parameter to suppress confirmation messages.

So, here is the command I ended up using:

Get-MsolUser -LicenseReconciliationNeededOnly | Remove-MsolUser –Force

Now I check to see if the command actually worked:

PS C:\> Get-MsolUser -LicenseReconciliationNeededOnly

PS C:\>

Yep, they are gone.

Luckily, Office 365 has a Recycle Bin, and it is easy to recover the deleted users via the admin tool. This is shown here:

Image of menu

There is also a Restore-MsolUser cmdlet, but unfortunately, there is no obvious way to find all the users in the Recycle Bin. Therefore, I would need to know each UPN to restore the users. In this case, for me, using the GUI is easier. If I had kept a log of the user objects that I deleted, I could have more easily reactivated the users.

That is all there is to using Office 365 cmdlets. Office 365 Week will continue tomorrow when I will talk about more cool stuff.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy


Discussion is closed.

Feedback usabilla icon