Exchange Online OAuth Configuration

All the EWS scripts in this repository require the EWS Managed API. This can be downloaded and compiled from the EWS Managed API Github Repository, or alternatively you can download and use the compiled binary I have included in this repository. Place the EWS API dll in the same folder as the script (that is where it looks first). If the EWS API is not found in the current folder, the script will search Program Files for it (it is often installed with Office), but this will add a possibly significant start-up delay.

To be able to successfully use any of the scripts in this repository against Exchange Online, you must set up an application registration in your tenant with the relevant access and permissions. The application information can then be passed to the relevant script using the -OAuth parameters. The OAuth parameters are common across all the scripts:

-OAuth: this switch must be included to enable OAuth for the script.

-OAuthClientId: The application Id as registered in Azure AD.

-OAuthTenantId: The tenant Id in which the application is registered. If missing, application is assumed to be multi-tenant and the common log-in URL will be used (note that all scripts may not support this, please confirm in the script docs or code itself).

-OAuthRedirectUri: The redirect Uri of the Azure registered application (defaults to http://localhost/code).

-OAuthSecretKey: Secret key to be used when obtaining access token (as generated in Azure AD). If this is specified, then application permissions are requested and no user log-on will be required. You will also need to use -Impersonate switch with this OAuth flow (as the application uses impersonation to access the mailboxes).

-OAuthCertificate: The OAuth certificate to be used when obtaining access token (this flow requires access to the private key of the certificate uploaded to Azure AD). Application permissions are requested in this scenario. You can obtain a certificate from your own certificate store using the thumbprint:

Get-Item Cert:\CurrentUser\My\50B510B4AE120D9B0EE3F059B6DD494469CD6D3B.

The scripts require no external libraries to use OAuth except when using certificate authentication. In that case, the scripts require MSAL (just place the current version of the MSAL library in the same folder as the script if you need to use certificate authentication).

Configuring the application

The full guidance for registering an application in Azure AD for it to be able to access mailboxes using EWS is documented here: Register Your Application

The below guide gives the steps to register an application for use with scripts in this repository using application access with secret key. This access does not require consent (the consent is implicit when the permissions are granted). The scripts also work with delegated authentication (which is granted via the Azure AD application registration).

Register your application

1. Open a browser and navigate to the Azure Active Directory admin center and login using an account with appropriate permissions to add an application registration (e.g. tenant administrator).

2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.

3. Select New registration. On the Register an application page, set the values as follows.

   • Set Name to a friendly name for your reference.
   • Set Supported account types to the choice that makes sense for your scenario.
   • For Redirect URI, change the dropdown to Public client (mobile & desktop) and set the value to http://localhost/code.

4. Choose Register. On the next page, copy the values of the Application (client) ID and Directory (tenant) ID and save them - these become the values for the -OAuthClientId and -OAuthTenantId parameters respectively when calling the script.

Configure secret key

1. Select Certificates & Secrets in the left-hand navigation under Manage.

2. Select New client secret, enter a short description and select Add.

3. Copy the Value of the newly added client secret and store it securely. This will be the value that is passed to the -OAuthSecretKey parameter when calling a script.

Configure application permissions

1. To grant ApplicationImpersonation rights, follow this guide: Application RBAC, and assign the Application EWS.AccessAsApp role.

Calling the script

Once the above steps are completed, you should be able to test the appropriate script. For example, to use the above details with the Remove-DuplicateItems.ps1 script, you would use the following command from PowerShell:

.\Remove-DuplicateItems.ps1 -Mailbox [email protected] -Office365 -RecurseFolders -MatchEntireMailbox -OAuth -OAuthClientId f61d7821-7aaf-4d24-b34f-ca50528bcc7b -OAuthTenantId fc69f6a8-90cd-4047-977d-0c768925b8ec -OAuthSecretKey xx -Impersonate -WhatIf

There is no need to pass in the -OAuthRedirectUrl parameter as we configured the default value for the script when registering the application.