Managing tenants using Powershell

by Steve Galloway | Dec 22, 2014

Whereas Powershell’s implicit security complicates connectivity to remote servers, authentication provides network administrators with utilities that extend far beyond GUI driven interfaces like Exchange Administration Console (EAC). This article explains how to initiate and terminate remote sessions to third party tenants.

When Powershell is properly configured, network administrators need three commands to open a session, and one command to close a session. Once connected, administrators assign a variable to call tenant ID which in turn enables connectivity to client servers.

Opening a Powershell Session

Import-Module MSOnline

Connect-MsolService

$tenID=(get-msolpartnercontract -domain domainname.com).tenantId.guid

To terminate a session:

Remove-PSSession $Session

Connection script

An unsigned script which automates the commands above and additionally calls the snap-in module for Exchange is available at ComStat’s Script page. If loaded to local drive c:\script, the Powershell command looks like:

c:\script\EXO-Connect.ps1

To test the snap-ins are loaded on sign in, run this command:

get-mailbox

Remember to sign out of sessions using

Remove-PSSession $Session.

Explanation & Concepts

Administrators can handle common management function with Office 365 and Exchange control panels. Occasionally, delegated network administrators need to configure client side processes that Office 365 and EAC does not provide for. Also, Powershell can run one command across several servers simultaneously.

For guidance on Microsoft’s current provisions for advanced management of client tenancies, check here.

Windows PowerShell cmdlets for Office 365

Before using Powershell with Office 365 for the first time, Powershell needs some utilities.  Users need to install “MS Online Service Sign-in Assistant for IT Professionals”. Also, the commands that Powershell relies on for Office 365 management are housed in “Azure Active Directory Module for Windows Powershell”. Follow the guidance here to install these services. Another useful download is “Windows PowerShell Module for Lync Online” here.

Cmdlt modules do not install directly into Powershell. Instead, these “snap-ins” sit in a separate directory and called when they are needed for sessions. Modules are managed this way to enable users to rapidly update Powershell’s main cmdlt library, which is updated frequently and is available for download by running this update command:

update-help -force

Using Powershell as a tenant’s global administrator

Delegated administrators can login to client tenants with a tenant’s global administrator credentials if they are available. From a security standpoint, this is not good practice. However, to test Powershell is adequately equipped and session execution policy permissions (more about this below) are properly set, it is worth running a simple script to test the Powershell. For instance, the following script can be used to view basic tenant information on either caistar.com or comstation.co.uk. The script, together with other scripts listed in this article, are available at ComStat’s Sharepoint script site.

c:\script\MSOLTenantDetails.ps1

– more information about this script is available here. At time of writing, this script is unsigned. Depending on your Powershell environment, you may need to run this command:

Set-ExecutionPolicy Unrestricted

Powershell imposes a strict security policy. The policy requires scripts to be “trusted”, and by default Powershell will not execute unsigned scripts. Signing scripts can be done within Powershell. This prevents scripts being tampered with, for example with additional commands that may be malicious. Since the scripts used here are short and can be quickly previewed, another approach when opening Powershell is to run the following command:

Set-ExecutionPolicy Unrestricted

For access to a client’s tenant, follow the guidance below.

Establishing a remote Session

Open Powershell and run the following commands:

Import-Module MSOnline

Connect-MsolService

When prompted, enter the credentials that you use to log into Office 365 portal (MOP) and that allow you to manage Office 365 on behalf of your customers.

Once logged in to Caistar or Comstation, the session will provide for connectivity to other servers to which delegated administration is granted. Commands are run as if executing on the administrator’s server, however each command is programmed to call a variable which points to the target server.

$tenID=(get-msolpartnercontract -domain domainname.com).tenantId.guid

In this case, we establish a variable called “tenantID”. The variable is assigned using the command $tenID= and then a sub routine is executed to call the client’s tenant ID by reference to the domain name associated with the account. Office 365 tenant IDs are longer than credit card numbers, so by calling the tenant ID from client’s domain name and then calling the output “tenantID”, this saves a lot of keystrokes. Here is an example, using hafodrenewables.co.uk (tenant ID = acc617f5-9d4a-4ea9-8823-2385e7d5271a)

$tenID=(get-msolpartnercontract -domain hafodrenewables.co.uk).tenantId.guid

Succesful command execution returns the user to the command prompt. From now, on, commands executed with -tenantID $tenID will execute functions on client servers. To test connectivity, try running this command after assigning a client to a variable to find users on a client server:

get-msoluser -tenantID $tenID

The important point to understand is that Powershell executes commands on a tenant ID, not a domain name. Also, the variable that references the client’s tenant ID must be called with each command, or commands will be executed on the host server. Lastly, by assigning multiple tenant IDs to one variable, administrators can simultaneously run one command across multiple servers and compile output in either formatted tables or even .html. In this way, tasks that might take hours or days can be run in seconds.

Exchange Commands

List Office 365 users:

get-msoluser -tenantID $tenID

Change a user password which never expires:

Set-MsolUser -UserPrincipalName alias@domainname.com -PasswordNeverExpires $true -tenantID $tenID

Test password change:

Get-MSolUser -UserPrincipalName alias@domainname.com -tenantID $tenID |