Most of the scripts I’ve published to the Technet Code Gallery support OAuth, which means they can access mailboxes that have MFA enabled. But one requirement for OAuth is that an application is registered in Azure Active Directory, which is something that most of the scripts don’t do themselves.
The scripts do have a default application Id that they can use which should work for other tenants, but you’d need to grant consent for the application first.
The following guide shows how to register an application with Azure AD and then use ApplicationImpersonation to access a mailbox (the ApplicationImpersonation role needs to be granted in the Exchange Admin Centre for this to work).
Registering the Application
- Log on to the Azure Portal and open Azure Active Directory.
- In the left pane, click App Registrations:
- Click New registration, and enter the following, and click Register:
- The next step is to configure the permissions the application needs. The EWS scripts require the EWS.AccessAsUser.All permission. To configure this, select the API Permisions node, then click Add a permission:
- Scroll down and select Exchange (listed under Supported Legacy APIs).
- Select Delegate Permissions, then EWS.AccessAsUser.All:
- Click Add permissions to complete the process.
- The final step is to grant consent for the application to access all the tenants mailboxes, which can be done by clicking the Grant admin consent button:
- That’s it for the application registration. You’ll need to take a note of the Application (client) ID and the Directory (tenant) ID for the application, both of which can be found on the Overview page. These values will need to be passed into the script so that it can use them when authenticating.
The application registration above allows the authenticating user to access any mailbox to which they usually have permissions. This also applies for ApplicationImpersonation permissions (which can be granted using RBAC or in the Exchange Admin Center), so if we grant that role to a user then we can run the script against any user’s mailbox.
The easiest way to configure impersonation is in the Exchange Admin Center, so we’ll do it that way:
- Open the Exchange Admin Center (which can be accessed easily from the Office Portal:
- From the navigation on the left of the Admin Centre, select permissions:
- Click the + to add a new role. Enter the following information to the new role window (except for the role members, which should consist of any accounts you need to grant impersonation rights to):
- Once done, click Save. The specified users/accounts will now be able to impersonate others.
Running the Script
Once the above two processes have been completed, you can run scripts. Here is an example using impersonation and the Search-Appointments.ps1 script (which can be used to search, export, and/or delete appointments from mailboxes).
- Download the Search-Appointments.ps1 script and extract to a folder on your machine.
- For OAuth, we also need the ADAL dll. ADAL can be downloaded from Github, but only as source code (which needs to be compiled). For convenience, I’ve already done this and the compiled Microsoft.IdentityModel.Clients.ActiveDirectory.dll ready for download. Place the .dll in the same folder as the script.
- Finally, we need the EWS Managed API. This is also published on Github, and as source only. There is an older version available from Microsoft Download Centre, which works fine. You can either install the EWS API (the script will find it), or simply copy the dll to the same folder as the script.
- We’re now ready to run the script. To do so, start a PowerShell console (no admin rights needed), and change the current folder to wherever the script was placed.
- Run the script using the relevant parameters, but ensuring to specify -OAuth, -OAuthClientId and -OAuthTenantId. When prompted to log-in, authenticate as the account that has impersonation rights: