Analyzing Exchange Online scripts

Posted on May 25, 2022 by Michel de Rooij

Since the original announcement on deprecation of Basic Authentication, organizations had time to analyze their environment which may include Exchange-related procedures and tools. These usually also contain scripts or commands, which depend on the Exchange Online Management module. A previous blog on its history and how version 2 of this module lends itself for unattended operation with certificate-based modern authentication support can be found here.

The initial release of the Exchange Online Management v2 – or EXOv2 – module offered a an additional small set of cmdlets which utilized REST-based services. Apart from the functional discrepancies, such as having to specify a property set to indicate which properties to return, the big advantage of these added commands was that they did not depend on the Windows Remote Management (WinRM) client using Basic Authentication for token exchange. Disabling Basic Authentication on WinRM client lead to messages such as:

Connecting to remote server outlook.office365.com failed with the following error message : The WinRM client cannot process the request. Basic authentication is currently disabled in the client configuration.

This dependency makes it challenging for organizations to turn off Basic Authentication altogether, or lead to problems when they did. Fast forward to the present, where the Exchange Online Management module in its current release is offering nearly all Exchange cmdlets in REST-based form, with full functional parity.

While I expect Microsoft to reach full command parity before they flick the Basic Authentication switch to off, there are also other use cases for which analyzing scripts might be helpful:

Ths initial purpose was identifying commands which require RPS (Remote PowerShell), and thus thus require WinRM Basic Authentication enabled. Because the Exchange Team did an amazing job in catching up in the last few months, only 4 Exchange Online cmdlets are still lacking REST support in my tenant at this moment. But then again, your mileage may vary.
New Exchange Online commands may not receive immediate REST support.
Organizations might want to cross-reference commands with scripts.
Identifying Exchange Online commands and parameters in scripts helps in determining the minimum set of permissions required to run the script.

To analyze and report on Exchange Online scripts, I created a simple script Analyze-ExoScript.ps1. This script, which is available on GitHub here, does the following:

Connect to Exchange Online using RPS and inventory the commands available. Note that this requires the UseRPSSession switch when connecting, which is only available per 2.0.6-Preview3 of the module. If your organization only runs GA versions of the module, this script cannot be used.
Connect to Exchange Online using REST and inventory the commands available. It will re-use the account used for authenticating the RPS session, which should prevent receiving another authentication dialog or MFA challenge.
Cache cmdlet information in an external file to prevent having to connect to Exchange Online for every run. The file is named EXO-CmdletInfo.xml and will be stored in the same folder as the script.
Process the script and report on the Exchange-related commands used.

Usage
Calling Analyze-ExoScript is straightforward:

.\Analyze-ExoScript.ps1 [-File <FileName[]>] [-ShowAll] [-Refresh]

Where:

Filename is the name of one or more files which you cant to analyze. Note that the script accepted pipeline output, so you can also feed it filenames using Get-ChildItem for example.
The ShowAll switch tells the script to output all found commands, not only the Exchange ones.
The switch Refresh tells the script to ignore saved command information, trigger reconnecting to Exchange Online in order to refresh the command sets.

When asked to authenticate, make sure your role has the necessary Exchange-related permissions as that will determine the Exchange Online cmdlets available to you, and consequently also the commands which Analyze-ExoScript will recognize in scripts to process.

For example, to process a script Fix-MailboxFolders.ps1, use:

.\Analyze-ExoScript.ps1 -File .\Fix-MailboxFolders.ps1

The script can accept files via the pipeline. For example, to process multiple scripts use something like:

Get-ChildItem -Path C:\temp*.ps1 | Analyze-ExoScript.ps1

The output consists of objects, which allow for further filtering:

The returned properties are:

Command is the Exchange Online command identified
Type will tell you if the command supports REST, if it requires RPS, or it requires RPS but can be refactored (MAP) to a REST-based command, and which one that would be.
Parameters are the parameters used together with the command. This includes common parameters, which might be less usable for role assignment purposes.
File and Line are the file containing the command and on which line it is located.

AST
To analyze code, I leveraged PowerShell feature called Abstract Syntax Tree, which was an interesting exploration in itself. PowerShell AST can be used to decompose PowerShell code into tokens. This is way better than simply looking for strings, and does away with having to interpret code to see if it really is a command, comment or just some string. AST allows for analysis of these tokens, in this case filtering on commands which are related to Exchange Online. If you want to get started on AST, check out this article, or plunge in the PowerShell SDK straightaway.

Final Words
When every Exchange Online command discovered is found to be offering REST support, you can turn off Basic Authentication on the client, for example through GPO or by reconfiguring WinRM:

winrm set winrm/config/client/auth @{Basic="false"}

Only thing you might need to refactor is if and how the script connects to Exchange Online, as Basic Authentication allowed for connecting to Exchange Online using (stored) credentials for example. Examples on how to use more secure Modern Authentication-based methods to connect can be found in an earlier article here.

Security Updates Exchange 2013-2019 (May2022)

Posted on May 10, 2022 by Michel de Rooij

The Exchange PG released May updates for Exchange Server 2013, 2016 and 2019.

Note that per this cycle, Security Updates will be packaged in an executable wrapper. This should trigger the running elevated prompt, thus preventing any potential issues from simply double-clicking the .MSP file. More about the new package format, options for logging and command-line switches are mentioned in an article dedicated to the change of distribution method here.

The vulnerability addressed in the Security Updates for May is:

Vulnerability	Category	Severity	Rating
CVE-2022-21978	Elevation of Privilege	Important	CVSS:3.1 8.2 / 7.1

The following Security Updates address this vulnerability:

Exchange	Download	Build	KB
Exchange 2019 CU12	Download	15.2.1118.9	KB5014261
Exchange 2019 CU11	Download	15.2.986.26	KB5014261
Exchange 2016 CU23	Download	15.1.2507.9	KB5014261
Exchange 2016 CU22	Download	15.1.2375.28	KB5014261
Exchange 2013 CU23	Download	15.0.1497.36	KB5014260

The SU also fix the following issue:

KB5013118 Exchange Service Host service fails after installing March 2022 security update

Important: As mentioned in the announcement, you must run /PrepareAllDomains after deploying the SU because of hardening measures. Exception is when you have multiple domains and some of them are never prepped; in that case prepare the individual domains required. Using your currently deployed binaries, run the following command, where the /IAccept switch you need to use depends on the Exchange version deployed and whether you provide diagnostics information:

& $exbin\setup.exe /PrepareAllDomains /[IAcceptExchangeServerLicenseTerms|IAcceptExchangeServerLicenseTerms_DiagnosticDataON|IAcceptExchangeServerLicenseTerms_DiagnosticDataOFF]

Be advised that these security updates are Cumulative Update level specific. You cannot apply the update for Exchange 2019 CU12 to Exchange 2019 CU11. Also, the security update download has the same name for different Cumulative Updates, and I would suggest tagging the file name with the CU level, e.g. Exchange2019-CU10-KBXXXXXX-x64-en.msp.

Exchange servers running as part of hybrid deployment are running services, and thus need to be included in the patch cycle. If you are running Exchange 2019 CU12 Management Tools-only (for recipient management), you do not need to deploy this SU.

On a final note, as with any patch or update, I’d recommend to apply this in a test environment first, prior to implementing it in production. However, it is not recommended to wait for regular maintenance cycles when it concerns security updates, and follow a more agile approach; the ratings are an indication of the urgency.

The Last Exchange Server

Posted on May 5, 2022 by Michel de Rooij

In the announcement of the most recent set of Cumulative Updates for Exchange Server 2019 and 2016, Microsoft introduced some changes – features if you will – as well, which were received with enthusiasm. An overview of these Cumulative Updates and the features introduced was given in an earlier article. In this article however, I would like to zoom in on one of those features, which also happens to be a popular topic among customers running Exchange Hybrid deployments, “The Last Exchange Server”.

Up to Exchange 2019 CU12 (2022 H1), customers that migrated to Exchange Online were still required to leave Exchange-related components running on-premises. Even today, with all the information published around this topic, I am surprised this still surprised customers. This Exchange server running on-premises is to be used for managing recipients which have their source of authority in Active Directory, leveraging Active Directory Connect to propagate objects to Azure Active Directory and thus Exchange Online. Also, when there is a need to relay messages from applications or multi-functional devices, customers often need to have an Exchange server on-premises to accept these messages, as Exchange is the only supported mail relay product for hybrid deployments.

Click here to read the full article on ENow Solutions blog.

Exchange Updates (and more) – H1 2022

Posted on April 20, 2022 by Michel de Rooij

20220423: Added TLS 1.3 note.

The Exchange Team released the ~~quarterly~~ half-yearly Cumulative Updates for Exchange Server 2019 and Exchange 2016. You read that right, half-yearly updates are replacing the cadence of quarterly update servicing model for Exchange Server. Effectively, this will be Exchange 2019 only, as Exchange 2016 will be out of mainstream support in H2 of 2022, and will therefor only receive Security Updates after this round. Note that this change also alters the effective ‘current’ state (n-1 or later) of your Exchange Server environment from half year to one year.

And that’s not the only good news that comes with these sets of updates. In short:

If you run Exchange 2019 in Hybrid only for the purpose of managing recipients, you can now use Exchange 2019 CU12’s Exchange Management Tools to accomplish this; no more need to have an Exchange server running just for this. More details here.
Exchange 2019 CU12 will reintroduce the Hybrid Key option. Its Hybrid Configuration Wizard supports this licensing method.
Exchange 2019 CU12 support managing the Hybrid Agent with MFA-enabled accounts.
Exchange 2019 CU12 adds support for Windows Server 2022, both for its underlying operating system, as well as deployment in environments running Windows Server 2022 Domain Controllers.
Note that while Windows Server 2022 supports TLS 1.3, Exchange 2019 CU12 on WS2022 does not yet support it. Adding support is scheduled for somewhere next year.
The supportability matrix has been updated for the supported Windows Server 2022 scenarios.
Exchange Server is now also part of Microsoft’s Bounty Program, which is an indication of continued focus for customers still running Exchange Servers on-premises.

Links to the updates as well as a description of changes and fixes are described below. The column Schema and AD indicate if the CU contains Schema (/PrepareSchema) and Active Directory (PrepareAD) changes compared to the previous CU. Refer to the Exchange Schema page for schema and related versioning information.

Version	Build	KB	Download	UMLP	Schema	AD
Exchange 2019 CU12	15.2.1118.7	KB5011156	Download		N	Y
Exchange 2016 CU23	15.1.2507.6	KB5011155	Download	UMLP	N	Y

Apart from DST changes and the fixes mentioned below, these Cumulative Updates also contain a change which will not allow using UNC paths with several cmdlets. More information about this change and cmdlets affected can be found here: KB5014278.

Exchange 2019 CU12 fixes:

5012757 “Migration user… can’t be found” error when using Start-MigrationUser after batch migration fails
5012758 Start-MailboxAssistant is not available in Exchange Server 2019
5012760 You can’t access OWA or ECP after installing the July 2021 security update
5012761 External attendees see “Send the Response Now” although no response was requested in Exchange Server
5012762 PST creation is unexpectedly triggered again during multiple mailbox export
5012765 Email stuck in queue starting from “2022/1/1 00:01:00 UTC+0” on all Exchange on-premises servers
5012766 Transport Services fail repeatedly because of * Accepted Domain
5012768 Start-MigrationUser and Stop-MigrationUser are unavailable for on-premises Exchange Server 2019 and 2016
5012769 Invalid New Auth Certificate for servers that are not on UTC time zone
5012770 No response from public folder for users migrating to Microsoft Exchange 2019
5012772 Items are skipped at the start of a new search page request
5012773 OWAMailboxPolicy is bypassed and high resolution profile images can be uploaded
5012774 Can’t change default path for Trace log data in Exchange Server 2019 and 2016
5012775 No additional global catalog column in the address book service logs
5012776 Exchange Server 2019 help link in OWA redirects users to online help for Exchange Server 2016
5012777 Can’t find forwarded messages that contain attachments in Exchange Server 2019
5012778 Exchange Server stops responding when processing PDF files with set transport rule
5012779 Invalid new auth certificate for servers that are not on UTC time zone
5012780 Disable-Mailbox does not remove LegacyExchangeDN attribute from on-premises Exchange 2019
5012781 Exchange Server 2019 and 2016 DLP doesn’t detect Chinese resident ID card numbers
5012782 MS ExchangeDiagnostic Service causes errors during service startup and initialization in Microsoft Exchange 2019
5012783 Can’t restore data of a mailbox when LegacyDN is empty in the database
5012784 Exchange 2016 CU21 and Exchange 2019 CU10 cannot save “Custom Attributes” changes in EAC
5012785 Read Only Domain Controllers (RODCs) in other domains do not get desired permissions
5012786 Forwarded meeting appointments are blocked or considered spam
5012787 Download domains created per CVE-2021-1730 don’t support ADFS authentication in OWA
5012789 Can’t use Copy Search Results after eDiscovery & Hold search
5012790 OWA doesn’t remove the “loading” image when a message is opened in Chrome and Edge browsers
5012791 MailboxAuditLog doesn’t work in localized (non-English) environments

Exchange 2016 CU23 fixes:

5012757 “Migration user… can’t be found” error when using Start-MigrationUser after batch migration fails
5012760 You can’t access OWA or ECP after installing the July 2021 security update
5012761 External attendees see “Send the Response Now” although no response was requested in Exchange Server
5012765 Email stuck in queue starting from “2022/1/1 00:01:00 UTC+0” on all Exchange on-premises servers
5012768 Start-MigrationUser and Stop-MigrationUser are unavailable for on-premises Exchange Server 2019 and 2016
5012769 Invalid New Auth Certificate for servers that are not on UTC time zone
5012774 Can’t change default path for Trace log data in Exchange Server 2019 and 2016
5012779 Invalid new auth certificate for servers that are not on UTC time zone
5012780 Disable-Mailbox does not remove LegacyExchangeDN attribute from on-premises Exchange 2019
5012781 Exchange Server 2019 and 2016 DLP doesn’t detect Chinese resident ID card numbers
5012782 MS ExchangeDiagnostic Service causes errors during service startup and initialization in Microsoft Exchange 2019
5012783 Can’t restore data of a mailbox when LegacyDN is empty in the database
5012784 Exchange 2016 CU21 and Exchange 2019 CU10 cannot save “Custom Attributes” changes in EAC
5012786 Forwarded meeting appointments are blocked or considered spam
5012787 Download domains created per CVE-2021-1730 don’t support ADFS authentication in OWA
5012789 Can’t use Copy Search Results after eDiscovery & Hold search
5012791 MailboxAuditLog doesn’t work in localized (non-English) environments
5012829 Group metrics generation fails in multidomain environment

Notes:

If these Cumulative Updates contain schema changes compared to the Cumulative Update you currently have deployed, you need to run Setup with /PrepareSchema. If they contain Active Directory changes, you need to run /PrepareAD. Alternatively, permissions permitting, you can let Setup perform this step. Consult the Exchange schema versions page for schema and related versioning information.
When upgrading from an n-2 or earlier version of Exchange, or an early version of the .NET Framework, consult Upgrade Paths for CU’s & .NET.
Don’t forget to put the Exchange server in maintenance mode prior to updating. Regardless, setup will put the server in server-wide offline mode post-analysis, before making actual changes.
When using Exchange hybrid deployments or Exchange Online Archiving (EOA), support requires you to trail at most one version (n-1).
If you want to speed up the update process for systems without internet access, you can follow the procedure described here to disable publisher’s certificate revocation checking.
Cumulative Updates can be installed directly; no need to install RTM prior to installing Cumulative Updates.
Once upgraded, you can’t uninstall a Cumulative Update nor any of the installed Exchange server roles.
The recommended upgrade order is internet-facing, non-internet-facing servers first, followed by Edge Transports.

Caution:

As for any update, I recommend to thoroughly test updates in a test environment prior to implementing them in production. When you lack such facilities, hold out a few days and monitor the comments on the original publication or forums for any issues.

Basic Authentication: End of an Era

Posted on March 31, 2022 by Michel de Rooij

Back in September 2019, Microsoft announced it would start to turn off Basic Authentication for non-SMTP protocols in Exchange Online on tenants where the authentication protocol was detected as inactive. This is part of an overall movement to deprecate the less secure Basic Authentication, which is unfit to face the security challenges of the modern world, being subject to things like password spray attacks. It’s modern successor, modern authentication or OAuth2, uses a token and claim based mechanism contrary to sending accounts and passwords, and is the preferred authentication method. When combined with Azure AD for authentication, Modern Authentication also supports features such as Multi-Factor Authentication or Conditional Access.

The original date for disabling of Basic Authentication was October 13^th, 2020. Then the world had other matters to deal with, and Microsoft extended the timelines. After initially postponing turning Basic Authentication off to second half of 2021, the most recent – and final – start date for permanently turning the lights off for Basic Authentication is now set to October 1^st, 2022, as per this article on Docs and MC286990 in the Message Center. Mind the ‘start’ in start date, as flicking the switch for millions of tenants takes time before it becomes effective on your tenant. Organizations do need to anticipate on this change for the first of October.

Until October, organizations can still (re-)enable Basic Authentication when they have a need, using the self-help system in the Microsoft 365 admin center. After entering “Diag: Enable Basic Auth in EXO” in the problem search query, the request will be checked, and Basic Authentication will get enabled. But with the end of support for Basic Authentication, so will this temporary workaround. On a side note, per end of 2020, newly created tenants already have basic authentication disabled by means of security defaults – if those organizations require Basic Authentication for some reason, they will also need to reconfigure security defaults which by default is an all or nothing option for all protocols.

So, with the doomsday counter ticking away for Basic Authentication, what are the consequences for Exchange related workloads organizations might wonder. In this article, I will try to address some of these concerns.

Click here to read the full article on ENow Solutions blog.

The Missing Cmdlets Mystery

Posted on March 29, 2022 by Michel de Rooij

A short blog on something which I find still surprises admins and consultants working with Exchange Online Management module for Powershell. The Exchange Online Management v2 module has been offering support for REST for a while now. One of the benefits of using these REST-based cmdlets, apart from performance and resilience, is that it uses Modern Authentication to connect to Exchange Online, which is the way forward, as Basic Authentication gets directed to the exit.

Now the initial versions of the module supported a limited set of 9 cmdlets. The REST cmdlets used the EXO prefix, such as Get-EXOMailbox as counterpart of Get-Mailbox. I wrote an earlier blog about using EXOv2, configuring the app in Azure and alternative ways to authenticate here.

Per version 2.0.6, which is still in preview, around 250 additional cmdlets got REST support as well, but using their original name and parameter set. You can check the number of cmdlets available after connecting, e.g.

Install-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName <UPN>
((Get-Module).Where{ $_.ExportedCommands.'Get-Mailbox'} | Select-Object -ExpandProperty ExportedCommands).GetEnumerator() | Measure-Object

As you can see above, after connecting this version supports 397 cmdlets for my role in addition to the 31 available pre-connecting. Your exact number might vary, based on the roles assigned to your account.

The confusion usually starts when people enter commands or run scripts, and find cmdlets are “missing”. Often they find that the Set/New cmdlet is unavailable, while the Get is available, e.g.

Before, this could be an indication those commands were removed from the role assigned to you, such as the New-MailboxImportRequest cmdlet which only is available if you have mailbox import/export assigned. But in this situation, it could be that the cmdlet does not have a REST call (yet). In those cases, you need to connect using a regular Remote PowerShell session, by specifying -UseRPSSession:

Connect-ExchangeOnline -UserPrincipalName <UPN> -UseRPSSession

When connecting this way, I have 739 cmdlets at my disposal, including the ones which do not support REST. Note that cmdlets which support REST still will use REST; the commands that require Remote PowerShell will use the imported cmdlet. As a reminder, Remote Powershell requires Basic Authentication, and therefor must be enabled on the system you are connecting from.

Tip: Did you know you can view the release notes of the installed Exchange Online Management module by inspecting the ReleaseNotes property, e.g.

(Get-Module ExchangeOnlineManagement).ReleaseNotes

Security Updates Exchange 2013-2019 (Mar2022)

Posted on March 8, 2022 by Michel de Rooij

The Exchange PG released March updates for Exchange Server 2013, 2016 and 2019. More detailed information on patching and how to get current when running an earlier CU of Exchange, can be found at the original blog post here.

The vulnerabilities addressed in these security updates are:

Vulnerability	Category	Severity	Rating
CVE-2022-23277	Remote Code Execution	Critical	CVSS:3.1 8.8 / 7.7
CVE-2022-24463	Spoofing	Important	CVSS:3.1 6.5 / 5.7

These vulnerabilities are addressed in the following security updates below. The exception is KB5010324 which does not fix CVE-2022-24463 for Exchange 2013. If this is because of the severity classification or the problem being non-existent for Exchange 2013, has not been not disclosed.

Exchange	Download	Build	KB	Supersedes
Exchange 2019 CU11	Download	15.2.986.22	KB5012698	KB5008631
Exchange 2019 CU10	Download	15.2.922.27	KB5012698	KB5008631
Exchange 2016 CU22	Download	15.1.2375.24	KB5012698	KB5008631
Exchange 2016 CU21	Download	15.1.2308.27	KB5012698	KB5008631
Exchange 2013 CU23	Download	15.0.1497.33	KB5010324	KB5008631

Finally, KB5010324 also contains the following additional fix for Exchange 2013:

5012925 RFC certificate timestamp validation in Exchange Server 2013

Be advised that these security updates are Cumulative Update level specific. You cannot apply the update for Exchange 2019 CU11 to Exchange 2019 CU10. Also, the security update download has the same name for different Cumulative Updates, and I would suggest tagging the file name with the CU level, e.g. Exchange2019-CU10-KBXXXXXX-x64-en.msp.

As a reminder, run the Security Update from an elevated command prompt to prevent issues during installation. In other words: Do not just double-click on the .MSP file. And on a final note, as with any patch or update, I’d recommend to apply this in a test environment first, prior to implementing it in production. However, it is not recommended to wait for regular maintenance cycles when it concerns security updates, and follow a more agile approach; the ratings are an indication of the urgency.

Security Updates Exchange 2013-2019 (Jan2022)

Posted on January 11, 2022 by Michel de Rooij

Another year, another Patch Tuesday! A quick blog on January 2022’s security updates for Exchange Server 2013 up to 2019.

The vulnerabilities addressed in these security updates are:

Vulnerability	Category	Severity	Rating
CVE-2022-21969	Remote Code Execution	Important	CVSS:3.1 9.0 / 7.8
CVE-2022-21855	Remote Code Execution	Important	CVSS:3.1 9.0 / 7.8
CVE-2022-21846	Remote Code Execution	Critical	CVSS:3.0 9.0 / 7.8

Vulnerabilities mentioned in the table above are addressed in the following security updates.

Exchange	Download	Build	KB	Supersedes
Exchange 2019 CU11	Download	15.2.986.15	KB5008631	KB5007409
Exchange 2019 CU10	Download	15.2.922.20	KB5008631	KB5007409
Exchange 2016 CU22	Download	15.1.2375.18	KB5008631	KB5007409
Exchange 2016 CU21	Download	15.1.2308.21	KB5008631	KB5007409
Exchange 2013 CU23	Download	15.0.1497.28	KB5008631	KB5007409

More detailed information can be found at the original blog post here. The security update also fixes the OWA redirection problem for Exchange hybrid deployments introduced with the November security updates.

Annual Report 2021

Posted on January 9, 2022 by Michel de Rooij

Happy new year to all my dear readers and followers. While some thought after 2020 things would improve soon, 2021 proved to be another year of dealing with measures. That said, 2021 was not very different compared to 2020 from a work perspective, with many organizations now professionalizing their quickly adopted digital transformation, further normalization for work from home scenarios. The year again proved to be a challenge for those busy working on customer projects while catering to the community as well. In the end, it is all about finding a balance, especially if you are working from home and the rest of the household is as well.

Now, without further ado, here are some of this blog’s and GitHub’s top entries for 2021.

General Stats

Number of views: 271,751 (3,086,610 all-time)
Unique visitors: 168,011 (1,627,860 all-time)
Number of posts: 17 (647 total)
Followers: 508
Busiest day: March 4, 2021 (5,616)
Popular time of day: Wednesday, 3pm

Popular blogs

Not surprisingly, posts related to the Hafnium security updates lead the way in 2021:

POPULAR Blogs from 2021
Security Update Exchange 2010-2019 (Mar2021)
Security Updates Exchange 2013-2019 (Jul2021)
Security Recommendation Exchange 2016-2019
Security Updates Exchange 2013-2019 (Nov2021)
Security Updates Exchange 2013-2019 (Oct2021)

Popular scripts in 2021

While I published some additional scripts on my GitHub repository, some scripts like the script to download Ignite sessions or remove duplicate items from Exchange mailboxes remain popular. I performed a total of 144 updates on the scripts, and have 102 people following my GitHub profile.

Script
Connect-Office365Services
Get-EventSession
Remove-DuplicateItems
Remove-MessageClassItems
Invoke-Unarchive

Top Visitor Countries

Country
United States of America
Germany
United Kingdom
The Netherlands
India

Managed AutoResponder Notifications

Posted on December 13, 2021 by Michel de Rooij

A long overdue blog on a solution which was created per request of an Exchange fellow. The original scenario is an organization spinning off, thereby changing their primary e-mail domain. They wanted to inform relations and partners using the old e-mail addresses of this change. However, this solution might also be helpful to organizations after merger and acquisitions or rebranding.

For the sake of the example, let us suppose Fabrikam was acquired by Contoso. Targeted mailboxes are migrated from the Fabrikam tenant to the Contoso tenant. Fabrikam will contain Mail-Enabled Users forwarding messages to their Contoso mailbox counterparts. The migrated mailboxes now hosted in Contoso will be configured to send notifications to senders which sent mail to the old Fabrikam address.

While organizations can resort to 3rd party tools to set up an Exchange Transport Rule with a generic message, a little script might also do the job, offering a more granular and controlled solution.

Solution
The scripted solution is available on GitHub here. It will configure an Inbox rule on the targeted Exchange mailbox(es), which would be the new/migrated mailbox. The rule will trigger when messages land in the inbox which were sent to a specific e-mail address, i.e. the previous e-mail address. It will send out an automatic response, which can consist of a custom subject, message body with an optional embedded image. The configuration of the response is defined in an customizable external XML file:

<?xml version="1.0" encoding="ISO-8859-1"?>  
<config>
  <rule>Contoso Autoresponder</rule>
  <subject>Please update your email recipient to Contoso</subject>
  <body>Dear Sender,

Thank you for your message. Fabrikam is now a whole Contoso subsidiary, and the fabrikam.com e-mail address will change to contoso.com. Your e-mail was forwarded to my new e-mail address. 

Please update contact information, distribution lists, etc. to update [OldMail] e-mail references with my new [Identity] e-mail address. 
 
[logo] 
The Contoso Corporation is a multinational business with its headquarters in Paris.</body>
  <logo>Contoso.png</logo>
</config>

The elements that can be used in the config are:

<rule> defines the name of the Inbox rule to be created. When the script runs, it will update any existing previously created inbox rules of the same name.
<subject> defines the subject of the response.
<body> defines the message body. You can use the following macros here:
- [OldMail] will get replaced with the original e-mail address.
- [Identity] will get replaced with the new e-mail address.
- [Logo] will get replaced with the embedded image.
Optionally, <logo> refers to the file name of the image to embed.

Requirements
To run the script, you need the following:

Exchange Server 2013 SP1 or later, or Exchange Online.
Exchange Web Services (EWS) Managed API 2.21 or later (how to, NuGet package exchange.webservices.managed.api).
When using modern authentication or OAuth2, the MSAL library is required (NuGet package Microsoft.Identity.Client). Also, you need to have registered an App in Azure Active Directory with sufficient permissions (e.g. full_access_as_app). After registering the app, Tenant ID, Application ID and certificate or secret is what you need to use with the script to run successfully.
In addition to installing the NuGet packages, you can also store their DLLs in the same folder as the script for portability.

Usage
The syntax to run the script is as follows:

.\Set-AutoResponderNotification.ps1 -Identity <Identity> -TemplateFile <File> [-TenantId <TenantId> -ClientId <ClientId> [-CertificateThumbprint <ThumbPrint>] [-CertificateFile <File> -CertificatePassword <SecureString>] [-Secret <SecureString>]] [-Credentials <PSCredential>] [-Clear] [-Overwrite] [-Impersonation] [-TrustAll]

The available parameters and switches are as follows:

Identity specifies one or more e-mail addresses of mailboxes to process. Identity supports the pipeline (see examples).
OldMail specifies one or more old e-mail addresses to use when configuring the autoresponder message. When specifying multiple identities,
the number of OldMail entries need to match the number of identities.
Server specifies the Exchange Web Services endpoint, for example outlook.office365.com for Exchange Online. When omitted, Autodiscover will be used.
Impersonation to use impersonation when accessing the mailbox. When using modern authentication, impersonation is mandatory.
TrustAll to accept all certificates including self-signed certificates.
TenantId specifies the ID of the Tenant when using a mailbox hosted in Exchange Online.
ClientId to specify the Application ID of the registered application in Azure Active Directory.
Credentials to specify the Basic Authentication credentials for on-premises usage or against Exchange Online when modern authentication is not an option.
CertificateThumbprint is the thumbprint of the certificate to use for modern authentication. The certificate with the public key needs to stored with the registered application for authentication. The certificate with the private key should be present in the local certificate store.
CertificateFile and CertificatePassword can be used to specify a certificate file to use. The file should contain the private key; the password protecting the certificate file can be specified using CertificatePassword as a secure string.
Secret can be used to specify the secret to authenticate using the registered application. The secret needs to be provided as a secure string.
Template
specifies the XML template file to use when configuring or clearing the autoresponder inbox rule. The format has explained above.
Clear specifies if any you want to remove the inbox rules with name specified in the template. Use this when you want to remove autoresponder rules from mailboxes. When using Clear, you don’t need to specify OldMail.
Overwrite specifies if any existing inbox rules with name specified in the template should be overwritten. When omitted, the script will skip processing
mailboxes with inbox rules with conflicting names. Use this when you want to configure the autoresponder only on mailboxes which do not have the rule.

Note that usage of the Verbose, Confirm and WhatIf parameters are supported.

Examples
Nothing more explanatory than an example. When we want to configure the autoresponder on a single mailbox, we can use something like:

Here, the autoresponder will get configured on the specified mailbox, triggering when mail has been sent to michel@fabrikam.com using the configuration defined in template.xml. Modern authentication will be used for authentication, using variables for Tenant, Client and in this case secret.

When you want to configure autoresponder for multiple mailboxes, you can for example use a CSV file. It needs to contain two elements which will be passed through pipeline, Identity and OldMail:

Identity,OldMail
philip@contoso.com,p.mortimer@fabrikam.com
francis@contoso.com,f.blake@fabrikam.com

After defining the response in a file template.xml, we can use this CSV to configure inbox rules on the Contoso mailboxes identified by Identity, triggering when mail is sent to their OldMail addresses:

Import-CSV -Path Users.csv | .\Set-AutoResponderNotification.ps1 -Server outlook.office365.com -Impersonation -TemplateFile .\Template.xml -TenantId <TenantId> -ClientId <ClientId> -Overwrite -CertificateThumbprint <Thumbprint>

What will happen is that for every set of Identity and OldMail, the mailbox specified by Identity will be configured with an inbox rule. When an existing rule is found, which is determined using the <rule> element in the XML template, it will get overwritten. The specified certificate will be picked from the local certificate store to authenticate against Tenant with TenantId, as application specified by ClientId.

Note that when the user opens Manage Rules & Alerts in Outlook, the configured inbox rule will be visible. This allows the user to remove it when it is no longer required. After a certain period, administrators can centrally remove these rules as well running the script using the Clear switch.

And finally, an example of how this may looks to senders when they receive an autoresponse message, using the sample configuration from the beginning of this article.

Application Access Policy
When using the script with modern authentication, you can leverage features such as conditional access to set boundaries for script usage. Also, you can configure application access policies to scope the registered app (script) to a subset of mailboxes. To accomplish this, assign an ApplicationAccessPolicy to the app.

To be more convenient in managing permissions, you can define a distribution group and assign the Application Access Policy with group scope (PolicyScopeGroupId). You then only need to add/remove members as you need to configure mailboxes.

More information about Application Access Policies here. Note that the permissions mentioned to not include full_access_as_app as permission, but it works.

EWS, why not Graph?
Microsoft already announced back in 2018 that development on Exchange Web Services will halt in and focus will shift to Graph. As part of this move, a more recent statement announced deprecation of some least-used API per March 2022, stimulating organizations to switch to using Graph. However, the organization looking for a solution wished for an automatic response with HTML as well as an embedded logo. Because of this, I had to use a template as a reply action.

But where Exchange Web Services supports reply with a template, Graph does not offer this functionality. So, until there is more feature parity between Exchange Web Services and Graph, or EWS goes completely out of service, solutions may still be forced to have a look at EWS for certain tasks.