The Exch-Rest module is a PowerShell module for the Office 365 and Exchange 2016 REST API that allows you to access the functionality provided by the Graph API ** New ** To jump to the How Can I one-liner QandA samples see this (Make sure you have connected to the mailbox first before running)
The Module is available from the PowerShell Gallery at https://www.powershellgallery.com/packages/Exch-Rest and can be installed on Windows, Azure Cloud Shell or Linux where Power Shell Core has been installed
Install-Module Exch-Rest
Import-Module Exch-Rest
Or you can use the following steps to download and install the module from the GitHub repo
# Set constants
$SourceCodeURL = "https://codeload.github.com/gscales/Exch-Rest/zip/master"
$UserModuleHome = "~\Documents\WindowsPowerShell\Modules"
# Download a zip of the source code
Invoke-WebRequest -Uri $SourceCodeURL -OutFile "~\Exch-Rest-master.zip"
# Unblock the downloaded file
Unblock-File "~\Exch-Rest-master.zip"
# Extract the zip
Expand-Archive "~\Exch-Rest-master.zip" -DestinationPath $UserModuleHome
# Remove "-master" from the name
Move-Item "$UserModuleHome\Exch-Rest-master" "$UserModuleHome\Exch-Rest"
# Delete the downloaded source code
Remove-Item "~\Exch-Rest-master.zip"
# Import the module
Import-Module -Name Exch-Rest
To connect to a Mailbox which will start the authentication process that will allow you to then use the cmdlets defined in the module use the following
Windows
Connect-EXRMailbox -MailboxName gscales@datarumble.com
Linux and Azure Cloud Shell
$Cred = Get-Credential -UserName username@domain.com
Connect-EXRMailbox -MailboxName mailbox@domain -Credential $Cred
Using the ADAL Authentication Library
By Default the Module uses its own Native Script based oAuth Authentication scripts however to support a greater range of Authentication scenarios the ADAL library is also distributed with the Module and available for use
To use the ADAL libraries for Logon use the following
connect-exrmailbox -MailboxName gscales@datarumble.com -useADAL
To use the Never Prompt to use the ADAL Cache
connect-exrmailbox -MailboxName gscales@datarumble.com -useADAL -Prompt Never
For connecting using the currently logged on credentials use
connect-exrmailbox -MailboxName gscales@datarumble.com -useADAL -useLoggedOnCredentials -AADUserName gscales@datarumble.com
(The -AADUserName variable is optional but usually required read the GitHub link in the second bullet point)
Certificate Authentication - If you wish to use App Only token using certificate based Authentication then see the certificate Authentication document
The Office 365 / Exchange 2016 REST API uses OAuth 2.0 to authenticate users. This means that people using an application that use this API do not need to give you their username/password. Instead, they authenticate against a central authentication system (e.g. Azure AD, Active Directory) and you get back a token which is then passed to the API endpoint for authentication. You can then give your application permission to use that token to do a limited number of things for a specific period of time.
However, to use OAuth tokens you must register an application in Azure before you can use the Exch-Rest functions.
You have two options when it comes to doing this, the most secure option is to register your own Application and assign just the permissions (or Permission Grants) you want the Module cmdlets to have based on what data you want to access using the module. The other option is to use one of the default Application registrations that have been registed for use in a Tenant that is owned by the module's Author Glen Scales. If no ClientId is specified when using Connect-EXRMailbox a menu will be presented with the different Application Registration options and the permissions they will need. eg
If you select one of these Id's the first time you run this in a Tenant it will prompt for administrative consent for the permissions that the cmdlet will need to access the Mailbox Items (or OneDrive, Directory,Report etc) eg you should see a screen similar to
If you want to create your own Application registration and permission grants (which is recommended) there is a good walk through of the application registration process is provided by Jason Johnston at https://github.com/jasonjoh/office365-azure-guides/blob/master/RegisterAnAppInAzure.md.
The following is an overview of the steps you can take to create an application registration:
- Browse to http://dev.office.com/app-registration and login into your Azure tenant
- Click
+ New application registration, fill out the options, and clickCreate- Name:
<Name-of-app-users-will-see> - Application type:
Native - Sign-on URL:
http://localhost
- Name:
- Click your newly created application and note the
Application ID. You will need this later as yourClient ID. - Click
Redirect URIs, you should seehttp://localhost. Replace that entry withurn:ietf:wg:oauth:2.0:oob - Click
Required permissionsand then click+ Add - Click
1 Select an API, clickOffice 365 Exchange Online (Microsoft.Exchange), and then clickSelect - Check off all the permissions that you wish to use, and then click
Select. (Note: there seems to be a bug with the CheckAll button so you may have to individually check off each permission) - Click
Done
- Click
Once you have done this you can set the Id you created to be the default Application registration everytime you use Connect-EXRMailbox (saving your from needing to enter it again). To do this select the Number 5 Option from the below menu
It will the prompt you to enter the clientId that was created when you registered the application and the redirectURI (generally this will be urn:ietf:wg:oauth:2.0:oob if you have used a native app) eg
Once the default Application has been set the console menu will no longer show when you use the Connect-EXRMailbox cmdlet. If you want to show the menu again, just add the -ShowMenu switch eg
Connect-EXRMailbox -Mailbox gscales@datarumble.com -ShowMenu
Once you have succesfully authenticated and your token has been cached locally you can start using the cmdlets defined in the module.
Because this module has a large number of cmldets to help simplify every day tasks to make the documentation more useful I've created a How Can I page which simple lists a one word question and one/two line example taking into account that you have authenticated with a Application registration that has sufficient rights. see How Can I examples
Most cmdlets have a -MailboxName switch which will control which mailbox a cmdlet is run against eg let's look an example
In the above example No MailboxName is used so the Mailbox that was used in the orginal Connect-EXRMailbox cmd will be used. This is because that MailboxName is cached in the AccessToken.
If you want to connect to a particular Mailbox you should use the -MailboxName parameter as follows
Cmdlets that don't connect to a specific Mailbox don't need the Mailboxname passed in eg like Get-EXRUsers which will retrieve all the user objects in the Azure Directory eg
Get-EXRLastInboxEmail -MailboxName gscales@datarumble.com -Focused
Get-EXRLastInboxEmail -MailboxName gscales@datarumble.com -Other
To Export the contacts in a user's Contacts folder you can use the Export-EXRContactFolderToCSV cmdlet
Export-EXRContactFolderToCSV -mailboxname mec@datarumble.com -FileName c:\temp\MailboxContacts.csv
Find-EXRRooms
New-EXRFolder -MailboxName gscales@datarumble.com -ParentFolderPath '\Inbox' -DisplayName "My New Folder for Processing"
Get-EXRFolderFromPath -MailboxName gscales@datarumble.com -FolderPath \Inbox -PropList (Get-EXRItemRetentionTags)
The Microsoft graph API provides access to the Office 365 usage reports for tenants and the module allows access to these reports eg getting the Mailbox Sizes and usage for the last 7 days
To vary the report duration you can pass in a different duration in the -PeriodType parameter eg to use 30 days instead of the default 7 use
