Prepare Exchange resources
ARM reads information from Exchange via a remote PowerShell connection.
Preparations for Exchange Online
For Exchange Online, we strongly recommend using Modern Authentication. To set up, follow all the steps in the appendix of the following Microsoft "App-only authentication for unattended scripts" guide (© 2022 Microsoft, https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-1-register-the-application-in-azure-ad, obtained on October 12, 2022). With the setup you get an application ID and a thumbprint, which you then use as user name and password during the configuration in ARM.
In step 3 of the instructions, you create a certificate and store it in the personal store location (-CertStoreLocation "cert:\CurrentUser\My"
). This way, the certificate cannot be used in the context of another user. In the following example script, the certificate is stored in personal (cert:\LocalMachine\My
) and in root (cert:\LocalMachine\Root
). In the first command, the DNS name must be adjusted. The domain of the collector where the scan is executed should be entered here. Alternatively, you can also enter a list of computer names (FQDN).
# Scripts are not supported under any SolarWinds support program or service.
# Scripts are provided AS IS without warranty of any kind. SolarWinds further
# disclaims all warranties including, without limitation, any implied warranties
# of merchantability or of fitness for a particular purpose. The risk arising
# out of the use or performance of the scripts and documentation stays with you.
# In no event shall SolarWinds or anyone else involved in the creation,
# production, or delivery of the scripts be liable for any damages whatsoever
# (including, without limitation, damages for loss of business profits, business
# interruption, loss of business information, or other pecuniary loss) arising
# out of the use of or inability to use the scripts or documentation.
#
# create certificate under personal
$mycert = New-SelfSignedCertificate -DnsName "domain1.local", "domain2.local" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(100) -KeySpec KeyExchange
# export certificate to .cer file to upload to azure
$mycert | Export-Certificate -FilePath c:\temp\ExoCert.cer
# Export certificate to .pfx file to install the certificate on other machines
$mycert | Export-PfxCertificate -FilePath c:\temp\ExoCert.pfx -Password (Get-Credential).password
# install certificate for root
Import-Certificate -FilePath c:\temp\ExoCert.cer -CertStoreLocation cert:\LocalMachine\Root
The script creates two files under C:\Temp. ExoCert.cer is necessary for uploading to Azure. ExoCert.pfx can be used to install the certificate on other computers as well.
ARM access to Exchange Online via Modern Authentication/App Registration allows to enable multi-factor authentication for Azure accounts. Please note that if necessary, Modern Authentication should also be set up for ARM access to SharePoint Online to avoid any restrictions on access to SharePoint Online.
The registered application is granted full access to Exchange Online. It is not possible to set up read-only access with Modern Authentication.
Not recommended: Alternatively, you can still use the username/password combination for Exchange Online:
-
Create a user with email address as a service account or select an existing (service) account with email address.
-
Add the account to the View-Only Organization Management group for read-only access or to Organization Management for modify access.
-
If the account is newly created, you must log in to the Office365 environment once with this account before you can use it.
Preparations for Exchange on-premise
An Exchange scan can be performed by any collector. The connection is established using a client access server (CAS) or a database availability group (DAG).
Prepare the PowerShell website
The Exchange Client Access Server (CAS) hosts a site within the IIS, that allows users to access the Exchange Server. It is called "Default Web Site" (2010) or "Exchange Back End" (2013 and higher) and includes the sub-site "PowerShell". This must be configured to allow ARM access to Exchange.
Screenshots property of © 2020 Microsoft.
Start the IIS Manager on the CAS.
As of ARM version 2020.2.7, the PSLanguageMode FullLanguage in no longer needed.
Screenshots property of © 2020 Microsoft.
Navigate to "Powershell". In Exchange 2010 this can be found under "Default Web Site". In Exchange 2013 it is found under "Exchange Back End". Double-click "Application Settings".
Screenshots property of © 2020 Microsoft.
- Select "PS LanguageMode"
- Click "Edit"
- Enter the value "FullLanguage".
As of ARM version 2020.2.7, the PSLanguageMode FullLanguage in no longer needed.
Please note that cumulative Exchange updates may reset this setting!
Screenshots property of © 2020 Microsoft.
Activate the desired authentication method.
You must later select the same authentication method in the Exchange configuration that you activate here.
For additional information see the article IIS for Beginners Part 4: Authentication and Authorization with the IIS (© 2020 Microsoft, https://blogs.technet.microsoft.com/bernhard_frank/2011/04/08/iis-fr-einsteiger-teil-4-authentifizierung-und-autorisierung-mit-dem-iis/, obtained on January 29, 2020).
Alternatively you can activate the authentication with PowerShell.
For example: Activate Windows-authentication (Kerberos)
Get-PowerShellVirtualDirectory | Set-PowerShellVirtualDirectory -WindowsAuthentication $true
You must restart the IIS in order to apply any changes.
For example in the command prompt or PowerShell:
iisreset
Set up required permissions
The service account that is used to scan Exchange requires the following access rights:
- Administrator privileges on the collector server
- Membership in the Exchange security group "View-Only Organization Management"
- Impersonation rights to scan deputy rules. See the section: Exchange Web Service - impersonation
- Its own mailbox to scan public folders
The service account that you want to use to modify Exchange requires additional different rights:
- Membership in the Exchange security group "Organization Management"
Deny rights applied to mailbox content may hinder successful scans.
MFA (multi-factor authentication) is not supported for scanning or modifying Exchange on-premise.
Exchange Web Services - Impersonation
PowerShell allows you to load administrative information from Exchange, such as the structure and permissions of objects, e.g. mailboxes and public folders. Substitution rules can only be read via the Exchange Web Service.
Access to the Exchange Web Service always happen in context with the mailbox user. This requires that the scan account (service account) has the right to impersonate.
Impersonation only works with active Active Directory accounts.
Examples for the configuration of impersonations via PowerShell can be found here:
- Exchange 2010: Configuring Exchange Impersonation in Exchange 2010 (© 2020 Microsoft, https://docs.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/bb204095(v=exchg.140), obtained on January 29, 2020).
- Exchange 2013 or higher, online and Office 365: How to: Configure impersonation (© 2020 Microsoft, https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-configure-impersonation, obtained on January 29, 2020).
Alternatively to the process described by Microsoft you can use the GUI of the Exchange Admin Center:
Screenshots property of © 2021 Microsoft.
-
Log in to the Exchange admin center.
-
Select Admin roles.
-
Click Add role group.
Screenshots property of © 2021 Microsoft.
-
Give the new role an appropriate name and description. Select the new role.
-
Click Assigned.
-
Assign the account to be used for Exchange scanning to the role.
Screenshots property of © 2021 Microsoft.
-
Click Permissions.
-
Enable the ApplicationImpersonation permission for the new role.
Test the connection to Exchange PowerShell
Use the following process to test the connection to PowerShell:
- Start a power shell console with the credentials that are also used for the remote session. (CTRL+SHIFT+right-click on the PowerShell-Icon -> "Run as different user")
- Create a credential object:
$cred = get-credential
- Create a SessionOption object (turn off all checks for the test):
$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
- Create a session. Adjust the URI, Authentication (authentication mechanism) and encryption http(s):
$session = New-PSSession -configurationname Microsoft.Exchange -connectionURI https://srv-ex01/PowerShell/ -Credential $cred -SessionOption $so -Authentication Default
- Enter the session. You can execute cmdlets (which ones, depends on their rights):
Import-PSSession $session