Export (0) Print
Expand All

Connect to all Office 365 services in a single Windows PowerShell window

 

Topic Last Modified: 2015-07-27

Summary: Connect Windows PowerShell to all Office 365 services in a single Windows PowerShell window.


There’s a commercial airing on TV these days in which an adult moderator asks a group of elementary school children, “Who thinks more is better than less?” The children all say that more is better, and the narrator agrees with them. “It’s not complicated,” says the narrator. “More is better.”

To be honest, we hate to play Grinch to a bunch of elementary school children, but we have to do what we have to do: kids, you’re wrong. And it’s not complicated: the truth is, more is not always better than less.

Case in point? Using PowerShell to manage Office 365. Each of the five Office 365 services (Office 365 admin center, SharePoint Online, Exchange Online, Skype for Business Online, and the Compliance Center) require you to use a different connection method. With Office 365 and SharePoint Online, you typically start their respective management shells. With Skype for Business Online, you start a local session of Windows PowerShell and then use the New-CsOnlineSession cmdlet to connect to your Office 365 organization. With Exchange Online and the Compliance Center, you start a local session of Windows PowerShell and then use the New-PSSession cmdlet to connect to your Office 365 organization.

That is complicated. But does any of it really matter to an Office 365 administrator?

As a matter of fact, it does: with five different connection methods, it would appear that you need to use five different Windows PowerShell instances in order to manage all Office 365 services. In other words, if you want to use Windows PowerShell to simultaneously manage Office 365, SharePoint Online, Exchange Online, Skype for Business Online, and the Compliance Center, your computer desktop would need to look like this:

Five Windows PowerShell consoles running at once

Like we said, more is not always better than less.

That’s obviously not an optimal situation (among other things, you can’t easily exchange data among those five windows). That also brings up an important question: is there any way that you can manage Office 365, Skype for Business Online, Exchange Online, SharePoint Online, and the Compliance Center using just one instance of Windows PowerShell?

You know, we were hoping that someone would ask that question.

Contents

Before you begin

The short version (instructions without explanations)

The long version (instructions with detailed explanations)

Step 1: Open Windows PowerShell as an administrator

Step 2: Create a Windows PowerShell credentials object

Step 3: Connect to Office 365

Step 4: Connect to SharePoint Online

Step 5: Connect to Skype for Business Online

Step 6: Connect to Exchange Online

Step 7: Connect to the Compliance Center

Step 8: Gracefully end your PowerShell sessions

Before we explain how to manage all of Office 365 from a single instance of Windows PowerShell, consider the following prerequisites:

Assuming you’ve taken care of all that, then you just need to follow these eight steps in order to set up a single Windows PowerShell window that lets you simultaneously manage Office 365, Skype for Business Online, Exchange Online, SharePoint Online, and the Compliance Center.

Return to top

This section presents the connection steps without fanfare or superfluous explanation. If you have questions or want more information, you can read rest of the topic. The step numbers here match the step-numbered sections in the rest of the topic:

  1. Open Windows PowerShell as an administrator (use Run as administrator).

  2. Run this command, and enter your Office 365 work or school account credentials.

    $credential = Get-Credential
    
  3. Run these commands to connect to Office 365.

    Import-Module MsOnline
    
    Connect-MsolService -Credential $credential
    
  4. Run these commands to connect to SharePoint Online. Replace domainhost with the actual value for your domain. For example, for litwareinc.onmicrosoft.com, the domainhost value is litwareinc.

    Import-Module Microsoft.Online.SharePoint.PowerShell -DisableNameChecking
    
    Connect-SPOService -Url https://domainhost-admin.sharepoint.com -credential $credential
    
  5. Run these commands to connect to Skype for Business Online. A warning about increasing the WSMan NetworkDelayms value is expected the first time you connect and should be ignored.

    Import-Module LyncOnlineConnector
    
    $sfboSession = New-CsOnlineSession -Credential $credential
    
    Import-PSSession $sfboSession
    
  6. Run these commands to connect to Exchange Online.

    $exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "https://outlook.office365.com/powershell-liveid/" -Credential $credential -Authentication "Basic" -AllowRedirection
    
    Import-PSSession $exchangeSession -DisableNameChecking
    
  7. Run these commands to connect to the Compliance Center.

    $ccSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ -Credential $credential -Authentication Basic -AllowRedirection
    
    Import-PSSession $ccSession -Prefix cc
    
    NoteNote:
    The text prefix "cc" is added to all Compliance Center cmdlet names so you can run cmdlets that exist in both Exchange Online and the Compliance Center in the same Windows PowerShell session. For example, Get-RoleGroup becomes Get-ccRoleGroup in the Compliance Center.
  8. When you are ready to close down, run this compound command before you close the Windows PowerShell window.

    Remove-PSSession $sfboSession ; Remove-PSSession $exchangeSession ; Remove-PSSession $ccSession ; Disconnect-SPOService
    

Technically, you don’t have to start here: you could kick things off by starting the Windows Azure Active Directory Module for Windows PowerShell or the SharePoint Online Management Shell instead. But we’re going to start completely from scratch, which means running "plain old" Windows PowerShell as an administrator.

If you're running Windows 8, Windows 8.1, Windows Server 2012 R2, or Windows Server 2012 R2, do this:

  1. Use any of these methods to find the shortcut for Windows PowerShell:

    • On the Start screen, click an empty area, and type Windows PowerShell.

    • On the desktop or the Start screen, press the Windows key+Q. In the Search charm, type Windows PowerShell.

    • On the desktop or the Start screen, move your cursor to the upper-right corner, or swipe left from the right edge of the screen to show the charms. Select the Search charm, and enter Windows PowerShell.

  2. In the results, right-click Windows PowerShell, and select Run as administrator.

  3. If the User Account Control dialog box appears, select Yes to verify that you want to run Windows PowerShell under administrator credentials.

If you’re running Windows 7 SP1 (or Windows Server 2008 R2 SP1), do this:

  1. On the Start menu, select All Programs > Accessories > Windows PowerShell. Right-click Windows PowerShell, and then select Run as administrator.

  2. If the User Account Control dialog box appears, select Yes to verify that you want to run Windows PowerShell under administrator credentials.

And yes, you absolutely must run Windows PowerShell as an administrator. If you don’t, you’re going to get an error message similar to this when you try to import one of the required modules.

The specified module 'Microsoft.Online.SharePoint.Online.PowerShell' was not loaded because no valid module file was found in any directory.

Admittedly, that’s not the clearest error message ever written: the problem really isn’t that the module file couldn’t be found; the problem is that you can’t import a module unless you’re running as an administrator. The only way to remedy the situation is to close Windows PowerShell and restart it as an administrator. Here's a quick and easy way to tell if you're running Windows PowerShell as an administrator: the prompt is PS C:\Windows\System32>, not PS C:\Users\UserName>.

Return to top

The credentials object provides an encrypted way to pass your user name and password to Windows PowerShell. To create a credentials object, type the following command in Windows PowerShell and press Enter.

$credential = Get-Credential
NoteNote:
$credential is a variable that will store the credentials object. You don’t have to name the variable $credential, but doing so makes it easier to remember which variable contains the credentials object. (And that’s important, because we’ll reuse this variable several times.) That will also make it easier for you to follow our examples, because this article will always use $credential to represent the credentials object.

Windows PowerShell will then display a dialog box that looks like this.

Blank Credentials request dialog box.

Type your work or school account user name in the User name box, using the format username@domainname (for example, kenmyer@litwareinc.onmicrosoft.com); type your password in the Password box; and then click OK:

Completed Credentials request dialog box.

Note that, as is often the case, you won’t see any sort of confirmation that the credentials object was created. (Windows PowerShell typically tells you when things go wrong but doesn’t always tell you when things go right.) If you want to verify that the credentials object was created, type the following in Windows PowerShell and then press Enter.

$credential

You should then see something similar to this on the screen.

UserName                               Password
--------                               --------
kenmyer@litwareinc.onmicrosoft.com     System.Security.SecureString

One thing to keep in mind here is that the Get-Credential cmdlet only creates the credentials object; it does not authenticate you or otherwise verify that the user name and password you supplied are correct. For example, suppose you mistyped the user name as eknmyer@litwareinc.onmicrosoft.com. If you do that, Get-Credential will create a credentials object using that user name, and without checking to see if that is actually a valid user name. You won't know whether you have created a truly valid credentials object until you actually use that object to try to connect to the Office 365 services.

Speaking of which, that’s exactly where we are in our process: we’re ready to connect to Office 365.

Return to top

We’ll start by connecting to Office 365 itself. Again, we don’t have to start here; we can connect to the various services in any order. But we have to start somewhere.

The first thing we need to do here is import the Office 365 module (the Windows Azure Active Directory Module for Windows PowerShell). To do that, run this command in Windows PowerShell.

Import-Module MsOnline

Admittedly, nothing will seem to have happened. If that worries you, and if you want to verify that the module was imported, run this command.

Get-Module

Somewhere in the list of modules that are returned by this command you should see something that looks like this: Manifest 1.0 MSOnline {Add-MsolForeignGroupToRole, Add-MsolG...}.

If you see MSOnline listed, that means that everything went according to plan.

With the credentials object created (see Step 2: Create a Windows PowerShell credentials object) and with the MsOnline module loaded, we can now connect to Office 365 by using the Connect-MsolService cmdlet and the following command.

Connect-MsolService -Credential $credential

Notice that all you have to provide is the credentials object ($credential). Based on those credentials, Office 365 will automatically connect you to the correct domain. You do not have to specify your domain name when running Connect-MsolService.

As usual, nothing will seem to have happened after the Connect-MsolService cmdlet finishes running. To verify that you really are connected to Office 365, run this command.

Get-MsolDomain

In return, you should get back something similar to this.

Name                         Status          Authentication
----                         ------          --------------
litwareinc.onmicrosoft.com   Verified        Managed

That’s one Office 365 service down, and four to go.

Return to top

Next up: SharePoint Online. Once again, we need to import the correct Windows PowerShell module before we can do anything else. Fortunately, that’s easy to do; just type this command in Windows PowerShell, and then press Enter.

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

The DisableNameChecking switch suppresses this ignorable warning.

WARNING: The names of some imported commands from the module 'Microsoft.Online.SharePoint.PowerShell' include unapproved verbs that might make them less discoverable. To find the commands with unapproved verbs, run the Import-Module command again with the Verbose parameter. For a list of approved verbs, type Get-Verb.

In order to connect to SharePoint Online, you need to supply two pieces of information: your credentials and the URL of your SharePoint Online admin site. The credentials part is easy: we’ve already stored that in the variable $credential (see Step 2: Create a Windows PowerShell credentials object). As for the URL of your admin site, that’s easy enough to determine, as well. Suppose your Office 365 domain name is litwareinc.onmicrosoft.com.

To determine the admin site URL, do this:

  1. Start by using the prefix https://.

  2. Add the domain host portion of your domain name. For example, for litwareinc.onmicrosoft.com, the domain host name is litwareinc. For contoso.onmicrosoft.com, the domain host name is contoso.

  3. Add a hyphen (-) followed by admin.sharepoint.com.

In other words:

https:// + litwareinc + -admin.sharepoint.com = https://litwareinc-admin.sharepoint.com

After you’ve constructed the URL, you can then use that URL and your credentials object to connect to SharePoint Online. Just call the Connect-SPOService cmdlet, using a command similar to this one.

Connect-SPOService -Url https://litwareinc-admin.sharepoint.com -credential $credential

To verify that the connection has been made, type the following command in Windows PowerShell, and press Enter.

Get-SPOSite

You should get back a list of all your SharePoint Online sites.

Url                                       Owner          Storage Quota
---                                       -----          -------------
http://litwareinc-public.sharepoint.com/                 1000
https://litwareinc.sharepoint.com/                       1000
https://litwareinc.sharepoint.com/search                 1000

But here’s the best part: your Office 365 commands (the ones described in Step 3: Connect to Office 365) will still work. (Try running Get-MsolUser, and see for yourself.) That means that you can now manage both Office 365 and SharePoint Online from the same instance of Windows PowerShell. And that’s good. But it’s not quite good enough.

Return to top

Connecting to Skype for Business Online (and to Exchange Online or the Compliance Center) isn’t very hard, but it's a tiny bit trickier than connecting to Office 365 or to SharePoint Online. That’s because the Skype for Business Online and Exchange Online cmdlets don’t get installed on your computer like the Office 365 and the SharePoint Online cmdlets do. Instead, each time you sign in, the appropriate cmdlets are temporarily copied to your computer. When you sign off, those cmdlets are then removed from your computer.

In order to connect to Skype for Business Online, you need to import the Lync Online (Skype for Business Online) module. To do that, run this command.

Import-Module LyncOnlineConnector

Note that the first time you do this, you might see the following warning message, which you can safely ignore.

WARNING: WSMan NetworkDelayms has been set to 30000 milliseconds. The previous value was 5000 milliseconds.
WARNING: To improve the performance of the Lync Online Connector, it is recommended that the network delay be set to
30000 milliseconds (30 seconds). However, you can use Set-WinRMNetworkDelayMS to change the network delay to any
integer value.

And then, after the module has been imported, run this command.

$sfboSession = New-CsOnlineSession -Credential $credential

What’s going on here? Well, what’s going on here is that we’ve created a remote PowerShell session. In this case, that means that we’ve connected to an instance of Windows PowerShell running on one of the Office 365 servers. However, just creating that session does very little for us. For example, try running this Skype for Business Online command.

Get-CsMeetingConfiguration

That command is going to fail, and you’ll get the following error message.

Get-CsMeetingConfiguration : The term 'Get-CsMeetingConfiguration' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

Why did the call to Get-CsMeetingConfiguration fail? That’s easy: because the Get-CsMeetingConfiguration cmdlet doesn’t exist anywhere on your computer. Although we’ve made a connection to Office 365, we haven’t downloaded the scripts, cmdlets, and other items needed to manage Skype for Business Online. To do that, we have to run this command.

Import-PSSession $sfboSession

When you import the Windows PowerShell session, you should see a progress bar similar to the following, a progress bar that reports on all the Skype for Business Online cmdlets being imported to your computer.

Lync Online progress bar.

When the progress bar disappears, you should then see output similar to the following.

ModuleType Version    Name               ExportedCommands
---------- -------    ----               ----------------
Script     1.0        tmp_swc5mp4v.1ck  {Copy-CsVoicePolicy, Disabl...

Now try running Get-CsMeetingConfiguration and see what happens. You should get back something similar to this.

Identity                        : Global
PstnCallersBypassLobby          : True
EnableAssignedConferenceType    : False
DesignateAsPresenter            : Company
AssignedConferenceTypeByDefault : True
AdmitAnonymousUsersByDefault    : True
RequireRoomSystemsAuthorization : False
LogoURL                         :
LegalURL                        :
HelpURL                         :
CustomFooterText                :
AllowConferenceRecording        : True
AllowCloudRecordingService      : False
EnableMeetingReport             : False
UserUriFormatForStUser          :

That’s more like it. Now let's get Exchange Online added to our Windows PowerShell session.

Return to top

After we connect to Exchange Online, we’ll be able to use a single Windows PowerShell session to manage four out of five Office 365 services. With that in mind, run this command, which creates a remote Windows PowerShell session with Exchange Online.

$exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "https://outlook.office365.com/powershell-liveid/" -Credential $credential -Authentication "Basic" -AllowRedirection

Admittedly, this is a slightly more complicated command than some of the other commands we’ve run. But that’s okay, because you can copy the command and run it exactly as is, even though there is a URI included in the command: https://outlook.office365.com/powershell-liveid/. However, that URI is always the same, regardless of the name of your domain. Therefore, copy, paste, run: it’s that easy.

NoteNote:
Why is the command for connecting to Exchange Online more complicated than the command to connect to Skype for Business Online? Technically, it’s not: both commands do the exact same thing. However, the Skype for Business Online team created its own cmdlet—New-CsOnlineSession—that hides some of the parameters (like Authentication and AllowRedirection) that are used when connecting to Exchange Online. Instead of requiring you to type that information yourself, the Authentication and AllowRedirection parameters are effectively built in to the New-CsOnlineSession cmdlet. You have to type those parameters when connecting to Exchange Online because Exchange Online uses the standard New-PSSession cmdlet to connect to Office 365. The disadvantage to that? You have a little more typing to do. The advantage? You don’t have to download and install an Exchange Online module.

All you have to do now is import this remote session, just like we did with Skype for Business Online.

Import-PSSession $exchangeSession -DisableNameChecking

And then, if all goes well, you’ll see something similar to this on the screen.

ModuleType Version  Name             ExportedCommands
---------- -------  ----             ----------------
Script     1.0      tmp_nweiqjvl.geu {Add-AvailabilityAddressSpace...

Now try running this command.

Get-AcceptedDomain

In return, you should see information about your Office 365 domains that are configured for email addresses in Exchange Online.

Name            DomainName          DomainType      Default
----            ----------          ----------      -------
litwareinc.com  litwareinc.com      Authoritative   True

If that command succeeds, all that's left to do is add the Compliance Center to our Windows PowerShell session.

Return to top

The Compliance Center is a service in Office 365 that lets you to manage compliance features from one location. For more information, see Office 365 Compliance Center.

The connection instructions for the Compliance Center are very similar to those for Exchange Online, but with an added twist, which you'll see in a moment.

Run this command, which creates a remote PowerShell session with the Compliance Center.

$ccSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ -Credential $credential -Authentication Basic -AllowRedirection

So what's different about this command compared to the command that connected us to Exchange Online? Only the ConnectionUri value. Everything else is exactly the same. But, the different ConnectionUri value is a clear indicator that we're connecting to a different remote PowerShell environment.

Now run this command:

Import-PSSession $ccSession -Prefix cc

Again, this command is very similar to the command for Exchange Online. The DisableNameChecking switch isn't required because there are no unapproved verbs in the Compliance Center. But what about that additional -Prefix cc parameter and value? That's the added twist we told you about.

Exchange Online and the Compliance Center share some cmdlets that have exactly the same names and provide the same functionality. Get-RoleGroup is an example.

So what happens if you try to import two sessions that contain cmdlets with the same name? They collide. You'll get a big yellow warning message that says, WARNING: Proxy creation has been skipped for the following command: followed by the list of conflicting cmdlets that couldn't be imported. The end result? You can run Get-RoleGroup in Exchange Online because you connected there first, but you can't run Get-RoleGroup in the Compliance Center because you connected there last and the conflicting cmdlets refused to import.

The easiest way to deal with this problem is to add an arbitrary text prefix to the imported Compliance Center cmdlets. We did that using the Prefix parameter with the value "cc" on the Import-PSSession cmdlet. What did that do for us? It eliminated the conflicts by (slightly) changing the Compliance Center cmdlet names for this session. All of the imported Compliance Center cmdlets now start with "cc" in the noun part of the cmdlet name (to the right of the "-"). For example, the contentious Get-RoleGroup cmdlet becomes Get-ccRoleGroup for the Compliance Center so it doesn't conflict with Get-RoleGroup for Exchange Online.

The downside? All Compliance Center cmdlet names receive the "cc" prefix—even unique cmdlets that don't need it. For example, Get-ComplianceSearch becomes Get-ccComplianceSearch even though there is no such cmdlet in Exchange Online. It's a bit of a pain, but not too bad when you consider the benefits of managing all Office 365 services in a single Windows PowerShell session. Just remember to add "cc" to the cmdlet names for all procedures in the Compliance Center.

If all goes well, you'll see something similar to this:

ModuleType Version  Name             ExportedCommands
---------- -------  ----             ----------------
Script     1.0      tmp_xbbx5exr.ehm {Add-ccRoleGroupMember, Get-ccAdminAuditLogConfig, Get-ccA...

Now you are free to manage all Office 365 services in a single Windows PowerShell session.

Return to top


You might be wondering why we even bothered to include this step. After all, how hard can it be to end a Windows PowerShell session: you just close the Windows PowerShell window, and everything disappears. Case closed.

And that’s true: everything will disappear. However, that doesn’t necessarily mean that your remote sessions have been properly disposed of. For example, even if you close the Windows PowerShell window, your Skype for Business Online remote connection will remain active for the next 15 minutes or so. That could prove to be a problem. Why? Because Skype for Business Online limits the number of simultaneous connections that any one person or any one domain can have open. With Skype for Business Online, an individual administrator can have, at most, three open connections at one time, and a domain can have a maximum of nine open connections. If you sign in to Skype for Business Online and then exit without properly closing the session, that session remains open for the next 15 minutes or so. As a result, that’s one fewer connection available to you or to other administrators in your domain.

Which means that this time the kids are right: having more available connections is better than having less available connections. In turn, that means that it’s a good idea to close your sessions after you’re done with them.

To start with, let’s close the remote sessions for Skype for Business Online, Exchange Online, and the Compliance Center. Before we do that, run this command.

Get-PSSession

The Get-PSSession cmdlet should show you that you have at least three remote sessions open, one for Skype for Business Online, one for Exchange Online and one for the Compliance Center (it’s possible you could have more than three remote sessions running, depending on whether you’ve used this instance of Windows PowerShell to connect to something else besides the Office 365 services). At any rate, you should see something similar to the following.

Id Name     ComputerName     State   ConfigurationName    Availability
-- ----     ------------     -----   -----------------    ------------
 1 Session1 webdir0a.onl...  Opened  Microsoft.PowerShell    Available
 2 Session2 outlook.offi...  Opened  Microsoft.Exchange      Available
 3 Session3 ps.complianc...  Opened  Microsoft.Exchange      Available

To close these three sessions, run these commands one at a time. The first command closes the Skype for Business Online session, the second closes the Exchange Online session, and the third closes the Compliance Center session.

Remove-PSSession $sfboSession
Remove-PSSession $exchangeSession
Remove-PSSession $ccSession

If you now run the Get-PSSession cmdlet, you should see nothing at all (unless, of course, you have other remote sessions up and running).

Windows PowerShell console with no remote sessions
NoteNote:
If you’d prefer to close all your remote sessions at the same time, you can use this command:
Get-PSSession | Remove-PSSession

If you now try running a cmdlet from any of these closed sessions (for example, Get-CsMeetingConfiguration in Skype for Business Online) you'll get an error message that's similar to this one.

Get-CsMeetingConfiguration : The term 'Get-CsMeetingConfiguration' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

We get that error message because the cmdlets for Skype for Business Online, Exchange Online, and the Compliance Center were deleted when we closed the remote sessions.

To close the SharePoint Online session, type this command.

Disconnect-SPOService

Again, it won’t look like anything has happened. But if you try to run the Get-SPOSite cmdlet, you’ll get an error message like this.

get-sposite : No connection available. Use Connect-SPOService before running this CmdLet.

You can’t retrieve site information because you’re no longer connected to SharePoint Online.

As for your connection to Office 365 itself, well, although there’s a Connect-MsolService cmdlet, there’s no corresponding Disconnect-MsolService cmdlet. So for Office 365, you'll just have to close the Windows PowerShell window. Nevertheless, it’s still a good idea to do this last so you can properly disconnect from SharePoint Online, Skype for Business Online, Exchange Online, and the Compliance Center.

Return to top

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft