en-us/about_Exch-Rest.help.txt

TOPIC
    about_Exch-Rest
     
SHORT DESCRIPTION
    Explains how to use the Exch-Rest powershell module
     
LONG DESCRIPTION
    Exch-Rest
 
A PowerShell module for the Office 365 and Exchange 2016 REST API.
 
Setup
 
Application registration
 
The Office 365 / Exchange 2016 REST API uses OAuth 2.0 to authenticate users. This means that people using your app do not need to give you their username/password. Instead, they authenticate against a central authentication system (e.g. Azure AD, Active Directory) and get back a token. They 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. 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 click Create
Name: <Name-of-app-users-will-see>
Application type: Native
Sign-on URL: http://localhost
Click your newly created application and note the Application ID. You will need this later as your Client ID.
Click Redirect URIs, you should see http://localhost. Replace that entry with urn:ietf:wg:oauth:2.0:oob
Click Required permissions and then click + Add
Click 1 Select an API, click Office 365 Exchange Online (Microsoft.Exchange), and then click Select
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
Module installation
 
The Module is availble from the PowerShell Gallery at https://www.powershellgallery.com/packages/Exch-Rest and can be installed on Windows 10 using
 
Install-Module Exch-Rest Import-Module Exch-Rest
 
Or you can use the following to download and use the following steps can be used to 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
EndPoint
 
The Module support either usings the Microsoft Graph or Outlook REST EndPoints, by default the Outlook REST endpoint outlook.office.com will be used to specify the Microsoft Graph Endpoint use the -ResourceURL when generating the Access Token. The endpoint will the be generated based on the URL that is stored in the Access Token
 
Authentication
 
You can either authenticate as a user or as an application.
 
Example 1: authenticating as a user (supplying the ClientId and redirectUrl you created during application registration)
 
$Token = Get-AccessToken -MailboxName mailbox@domain.com `
                         -ClientId 5471030d-f311-4c5d-91ef-74ca885463a7 `
                         -redirectUrl urn:ietf:wg:oauth:2.0:oob
Example 1a: authenticating as a user (supplying the ClientId and redirectUrl you created during application registration) against the Microsoft Graph Endpoint
 
$Token = Get-AccessToken -MailboxName mailbox@domain.com `
                         -ClientId 5471030d-f311-4c5d-91ef-74ca885463a7 `
                         -redirectUrl urn:ietf:wg:oauth:2.0:oob
                         -ResourceURL graph.microsoft.com
Example 2: authenticating as a user can and supplying a ClientSecret
 
$Token = Get-AccessToken -MailboxName mailbox@domain.com `
                         -ClientId 1bdbfb41-f690-4f93-b0bb-002004bbca79 `
                         -redirectUrl 'http://localhost:8000/authorize' `
                         -ClientSecret 1rwq9MmrSMu4SGhMEfGb9ggktWjzPYtW5lcAxXLzEtU=
 
Example 2a: authenticating as a user can and supplying a ClientSecret against the Microsoft Graph Endpoint
 
$Token = Get-AccessToken -MailboxName mailbox@domain.com `
                         -ClientId 1bdbfb41-f690-4f93-b0bb-002004bbca79 `
                         -redirectUrl 'http://localhost:8000/authorize' `
                         -ClientSecret 1rwq9MmrSMu4SGhMEfGb9ggktWjzPYtW5lcAxXLzEtU=
                         -ResourceURL graph.microsoft.com
Example 3: authenticating as an application using a certificate
 
$Token = Get-AppOnlyToken -CertFile "c:\temp\drCert.pfx" `
                          -ClientId 1bdbfb41-f690-4f93-b0bb-002004bbca79 `
                          -redirectUrl 'http://localhost:8000/authorize' `
                          -TenantId cbdbfb41-f690-4f93-b0bb-002004bbca79
Example 3a: authenticating as an application using a certificate against the Microsoft Graph Endpoint
 
$Token = Get-AppOnlyToken -CertFile "c:\temp\drCert.pfx" `
                          -ClientId 1bdbfb41-f690-4f93-b0bb-002004bbca79 `
                          -redirectUrl 'http://localhost:8000/authorize' `
                          -TenantId cbdbfb41-f690-4f93-b0bb-002004bbca79
                          -ResourceURL graph.microsoft.com
Note that example 3 is typically used for administrative purposes to manage mulitple mailboxes. This type of authentication requires different steps to register an application. See http://gsexdev.blogspot.com.au/2017/03/using-office365exchange-2016-rest-api.html for more information.
 
Example 4: authenticating as a user with PSCredentials (supplying the ClientId and redirectUrl you created during application registration)
 
$Token = Get-AccessTokenUserAndPass -MailboxName mailbox@domain.com `
                         -ClientId 5471030d-f311-4c5d-91ef-74ca885463a7 `
                         -redirectUrl urn:ietf:wg:oauth:2.0:oob
Example 4a: authenticating as a user with hard coded PSCredentials(supplying the ClientId and redirectUrl you created during application registration) against the Microsoft Graph Endpoint (this method is not recommended because of potential security issues)
 
$secpasswd = ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("username", $secpasswd)
$Token = Get-AccessTokenUserAndPass -MailboxName mailbox@domain.com `
                         -ClientId 5471030d-f311-4c5d-91ef-74ca885463a7 `
                         -redirectUrl urn:ietf:wg:oauth:2.0:oob
                         -ResourceURL graph.microsoft.com
                         -Credentials $mycreds
Usage
 
After you have authenticated and received a token you can use that token with the Exch-Rest functions to access the Office 365/Exchange REST API.
 
Example 1: get information about the inbox of a mailbox
 
Get-Inbox -MailboxName mailbox@domain.com -AccessToken $Token
 
KEYWORDS
    Exch-Rest