Managing SharePoint Online with PowerShell

Posted by Mikhail Rodionov on December 5, 2017
No ratings yet.

Some people still consider PowerShell as something that you need to employ only for scripting and automation scenarios, but, when it comes to Microsoft Technology stack, PowerShell evolved into the preferable way of configuring and managing your systems irrespectively of availability of corresponding graphical user interface (GUI). In fact, PowerShell is your primary tool for day to day administration and even some one-off tasks are no longer an excluded use case for PowerShell.

Today, PowerShell is not only an easier way to do some one-off changes or configuration tasks, sometimes it is the only way you can do them. There are a lot of situations when there is no parity in what you can do in GUI and PowerShell, and if in the early days of PowerShell, you sometimes could have a problem of not being able to do something available in GUI with PowerShell, nowadays we have rather the opposite situation – GUI often miss some basic things which available to you only in PowerShell.

All this especially true when it comes to administering and configuring cloud or hybrid environments based on Microsoft technology stack.

I was doing some work with SharePoint Online recently and bumped into this problem of not being able to do certain things using SharePoint Online web UI. As a result, I’ve spent some time figuring out how to connect and manage SharePoint Online via PowerShell. In this article, I want to share what I’ve learned in the process.

First, you normally get SharePoint Online as a part of Office 365 software suite, and for everything included in Office 365 we have four administration tools options: Office 365 Admin Center, Office 365 Admin App, PowerShell for Office 365 and Office 365 Management API. In this article, I will focus on the PowerShell for SharePoint Online.

PowerShell allows you to do everything that Office 365 Admin Center can do plus more. To put it simple Office 365 Admin center geared towards common administrative tasks whereas PowerShell adds its “power” of filtering and automation, which comes in handy when working with objects en masse, and allows you to perform less common administrative tasks and manipulate with settings which are not available in Office 365 Admin Center.

Let’s see how we can work with PowerShell for SharePoint Online. As usual, there are certain prerequisites we should take care of first. Requirement number one is Office 365 Global Admin rights for the account you are using to connect to SharePoint Online from your PowerShell session. That means that your account should have “Global administrator” role assigned as shown below.

K2 Service - Edit user roles

Yes, you read it right, Office 365 Global Administrator. To use SharePoint Online Management Shell, you must be Office 365 Global Admin and neither User or SharePoint Online administrator role memberships are enough. In case your account has SharePoint Online Administrator role, configured as shown below:

K2 Service - Edit user roles - Customized administrator -SharePoint administrator

You going to get “(401) Unauthorized” error upon an attempt to connect to SharePoint Online Management Shell:

SharePoint Online Management Shell - (401) Unauthorized

Interestingly, Exchange Online Management Shell is by default enabled for all users and any user created with default settings can connect, though there is obviously not much they can do there with their default rights and permissions.

In addition to Office 365 Global Admin rights, your workstation should have at least PowerShell 3.0 (which is a part of WMF 3.0), which most likely already in place if you use the current version of Windows client or server operating system. That’s requirement is rather easy to check – just launch PowerShell console, type Get-Host, hit Enter and see your PS version in Get-Host output:

Windows PowerShell - Get-Host

Another way to do the same check is to check $PSVersionTable.PSVersion variable value, but to my taste, it is a too lengthy thing to type when compared with Get-Host:

Windows PowerShell - $PSVersionTable

Anyhow as you can see I have PowerShell 5 on my system, so we are good to go here, as “PowerShell 3.0 minimum” requirement is met.

If you have experience of working with on-premise versions of Microsoft products developed with PowerShell in mind (nowadays this is the case for all Microsoft products), you already know that they have their own “shells”, for example – Exchange Management Shell, SharePoint Management Shell. But what these “shells” are? Essentially, they are just shortcuts for PowerShell instances which start with preloaded product specific PowerShell module. The same is the case with SharePoint Online, it has its own Management Shell/PowerShell module.  And because of that, our third prerequisite here is SharePoint Online Management Shell which you need to download and install. At the time I write this, most current version of SharePoint Online Management Shell is 16.0.7018.1200 and it is available for download from Microsoft site. Depending on the operating system you use, you can download 32 or 64-bit MSI package:

SharePoint download package

Once MSI package is downloaded you just need to launch it, accept license terms and click Install:

SharePoint Online Management Shell Setup - License Agreement

After the installation process completes we just click Finish and we are finally ready to start using SharePoint Online Management Shell. After installation you can invoke SharePoint Management Shell by clicking on the respective icon from Start menu:

SharePoint Online Management Shell - Desktop app

But remember that I have mentioned that any “management shell” it is just a product-specific PowerShell module? So, the second way to run it is just to fire off regular PowerShell session window and load respective module from there by issuing Import-Module Microsoft.Online.SharePoint.PowerShell:

Windows PowerShell - Import-Module

Once a module is loaded all SharePoint Online related cmdlets are available to us. The naming convention for SharePoint Online cmdlets is “<verb> -SPO<noun>”, so we can quickly look at all SharePoint Online cmdlets by means of issuing Get-Command *-SPO*:

Windows PowerShell - Get-Command

Using Measure-Object cmdlet we can also establish a number of SharePoint Online cmdlets available to us:

Windows PowerShell - Get-Command - Measure-Object

As you can see we have 91 cmdlets for SharePoint Online, and if we look at the number of cmdlets in SharePoint 2016 on-premise module we will see that it has the significantly larger number of cmdlets (around 837 commands). In case you wonder why there is such a big difference, the answer is quite simple. With on-premise SharePoint, we have cmdlets to install, configure and update SharePoint plus cmdlets to manage Web Applications, Site Collections, SPWeb, SPList, SPItem. With SharePoint Online, you don’t need to install, configure or update SharePoint, and you also do not manage Web App itself, hence PowerShell for SharePoint Online cmdlets allow you to manage Tenant, Site Collection and allows very limited management of SPWeb.

By now we are dealt with all the pre-requisites and we also clear on a number of commands available. But before we can use them for real we need to connect to SharePoint Online instance. Let’s do that.

We already have our PowerShell instance with SharePoint Online module loaded, next, for the sake of convenience, we first need to save our Global Admin credentials into $credentials variable by means of typing $credentials = Get-Credential:

Windows PowerShell - Get-Credential request window

Once we typed incorrect credential and saved them into variable $credentials we can use it with Connect-SPOService cmdlet:

Windows PowerShell - #credentials - Connect-SPOService

In case you made a mistake when typing in your credentials, you will get quite self-explanatory error message – “The sign-in name or password does not match one in the Microsoft account system”, and to correct this just fire off $credentials = Get-Credential again and re-type your username and password.

As you also can see in the screenshot above in addition to credentials we also need to provide SharePoint Online admin URL as a parameter for Connect-SPOService cmdlet. SharePoint Online Admin URL always looks as follows

SharePoint Online admin URL

Important thing to note about SharePoint Online URLs is that even if you have some custom domain configured for Office 365 tenant (in my case I have “” domain configured) all your SharePoint Online sites URLs (including SharePoint Online admin URL) are still different, as they formed based on tenant name you provided while creating it. This is something you want to know well in advance, as once you set up your Office 365 tenant with some name, there is no way to change it, except for creating new tenant with new name, adding nice custom domain for your Office 365 (and this is something you always do after setting up your tenant) does not change your tenant name and your SharePoint Online sites always going to have URLs, so think carefully what you specify there. For the more vivid description of this problem just refer to this blog post.

If credentials and admin URL provided is correct you will be connected to your SharePoint Online instance and finally start interacting with it via PowerShell.

After perusing the list of available commands, we can see that we have cmdlets for working with apps, managing deleted site collections, users, groups, commands for connecting and disconnecting to SharePoint Online instance and we even have one cmdlet to manage web app (Get-SPOWebTemplate). In addition to this, we have two sets of cmdlets for managing site collections and SharePoint Online tenant.

As a first command to try we can use Get-SPOSite which just lists all site collections:

Windows PowerShell - Get-SPOSite

As with any cmdlet, you can go beyond with it doing all sorts of filtering and selecting additional properties. Let’s check all the methods and properties available for Get-SPOSite cmdlet by piping it into Get-Member cmdlet:

Windows PowerShell - Get-SPOSite - Get-Member

As we can see we can access to quite interesting properties of every site collection, for example, we can easily select information on current storage usage and content last modified date and if necessary filter our site collections using different criteria against any exposed property:

Windows PowerShell - Get-SPOSite - Select

In the past for similar use of this cmdlet without “-Detailed” switch you might not get values for all properties you wanted to see, as this cmdlet as many other were optimized for speed and were not pulling all the properties by default. Nowadays things have changed, all properties are pulled without this switch and if you try to use it you will get a warning which says that “The -Detailed parameter will be deprecated for bulk enumeration”:

Windows PowerShell - Get-SPOSite - Select warning

Windows PowerShell - Get-SPOSite - Select - where

Before we move on to modifying site collections cmdlets let’s have a look at one more example of getting site collections information. We can filter them and see which one is our app catalog. If you created new app catalog accepting default setting (create new) it will be created on URL using APPCATALOG#0 template, so we can get its URL if we filter our sites by the template:

Windows PowerShell - Get-SPOSite - Select APPCATALOG#0

Nothing special, just standard use of Where-Object cmdlet (on the screenshots above we just using its alias “where”) and PowerShell comparison operators. Note that in case you’ve created your app catalog selecting existing site then it may have some other template, for example, EHS#1 (Team Site – SharePoint Online Configuration) or STS#0 (Team Site Classic Experience). You can use Get-SPOWebTemplate cmdlet to view all available templates (though interestingly APPCATALOG#0 is not returned by this cmdlet):

Windows PowerShell - Get-SPOWebTemplate

I have noticed that both EHS#1 and APPCATALOG#0 templates have “Delete Site” option removed from Site properties, and I believe this is the only difference when it comes to STS#0 and EHS#1 templates. How you delete them then? Easy – either using SharePoint Online Admin Center Manage site collections section or PowerShell for SharePoint Online.

We looked at how to get information about our Site Collections, but we can also easily modify them. For that it is convenient to store our site collection into a variable so that we don’t have to modify it every time we need to manipulate it:

Windows PowerShell - Get-SPOSite cmdlet

Once we did this we can easily perform different manipulations with this site collection, for example, change its title using Set-SPOSite cmdlet:

Windows PowerShell - summary

In a similar fashion, we can change site owner or, let’s say control site sharing options. I hope you remember these “Invite people”, “Get a link” options available if you click on ¨Grant Access¨ for specific document in SharePoint Online?

SharePoint Online - Share - Invite people

For example, we can disable site sharing completely (this will switch off anonymous or external users sharing) or disable anonymous sharing only (it removes “Get a link option”) or enable all sharing options (allows get a link and sharing with external users):

Windows PowerShell - Disable Site Sharing Completely

Another thing, you may need while working with SharePoint Online at some point, is deleting site collections, which can be done using Remove-SPOSite cmdlet (remember that some templates):

Windows PowerShell - Remove-SPOSite

You may also need to use Remove-SPODeletedSite or Restore-SPODeletedSite cmdlets to remove or restore deleted site collections from SharePoint Online recycle bin (just because it is something that sometimes may be required and yet not exposed in SharePoint Online GUI):

Windows PowerShell - Restore-SPODeleteSite

For those people, who are discouraged by a small number of cmdlets you have for SharePoint Online, there is some good news too: you can use them in conjunction with Client Side Object Model (CSOM) in PowerShell which enables us to do much more things with SharePoint Online. Essentially when you use CSOM for SharePoint Online in addition to PowerShell cmdlets you are getting more than one thousand options as essentially you with CSOM you get access to SharePoint Online APIs. When you need to work with CSOM you first need to get client context (the i.e. class that manages interaction between script and SharePoint Online server) and only then you can do the action. Working with that is a bit more complex than with plain PowerShell and may require yet another separate blog post to cover, but spending more time to learn it is justified considering added capabilities you are getting with CSOM.

I’ve started this article saying that it PowerShell is not only about automation, but we simply cannot omit that part here. Once you’ve mastered managing SharePoint Online and other separate Office 365 components with PowerShell you can create quite advanced automation scripts. For example, you can automate canonical new employee onboarding process where HR adds new employee data to SharePoint Online list and your script, running regularly on schedule, detects new entry there, creates user in AAD based on template, provisions Exchange Online mailbox, adds this user to relevant groups and distribution lists and sends him welcome email using Exchange Online. Here I’m really tempted to quickly compare this with K2 Five which is often used to automate the same type of scenario. In case you have K2 Five you obviously have more power with customizing your welcome emails as well as more flexibility in building end user UI with K2 SmartForms and what’s most important you can use simple visual designers to achieve that without writing single line of code or scripts. Despite PowerShell script can cover quite well employee onboarding process, it requires quite advanced scripting and use of templates, whereas K2 Five enables you to do all the same plus much more without writing any scripts or code. As you can see, the same tasks, but different ways of accomplishing depending on what technology you have or going to use. Fully going through such scenario or comparison is probably a good topic for another blog post.

To conclude PowerShell allows automation and at times is the only tool available for you which provides access to advanced functions and configuration settings of your SharePoint Online environment. Best way to learn more on this topic is to practice, i.e. to set up your own SharePoint Online instance and try to accomplish different tasks using PowerShell, and you can complement it with reading vendor documentation, for example, ¨Office 365 PowerShell for SharePoint Online¨ section of  Office 365 for Administrators documentation. I hope this article was a good introduction to get you started with PowerShell for SharePoint Online.


Related materials:

Views All Time
Views Today
Return to all posts

Introducing Azure Automation
Microsoft is Looking for your VMware Workloads, Announcing Azure Migrate

Please rate this

The following two tabs change content below.

Leave a Reply

You must be logged in to post a comment.