Microsoft Exchange Online

Connecting Microsoft Exchange Online to vScope lets you inventory mailboxes and mailbox permissions. The connection uses an app registration with certificate-based, app-only authentication and read-only access to Exchange Online PowerShell.

Prerequisites

Windows inventory target: A Windows machine configured for remote PowerShell access from the vScope server or Discovery Proxy.
PowerShell: Windows PowerShell 5.1 must be available on the Windows inventory target, with .NET Framework 4.7.2 or later and a Windows version supported by ExchangeOnlineManagement. See Microsoft’s compatibility requirements.
Required modules: ExchangeOnlineManagement, PowerShellGet, and PackageManagement must be available to the inventory account on the Windows inventory target.
Windows account: An account that can connect to the target and run the inventory. It must also have access to the certificate’s private key once the certificate is configured.
Setup permissions: Access to create an app registration, grant administrator consent, and assign the required Exchange permissions.

To check the PowerShell version and confirm that the required modules are available, run the following commands in Windows PowerShell on the Windows inventory target, using the inventory account.

Check the PowerShell version:

$PSVersionTable.PSVersion

Check that all three required modules are available:

Get-Module -Name ExchangeOnlineManagement, PowerShellGet, PackageManagement -ListAvailable |
    Select-Object Name, Version

The output should include all three modules and their versions. If a module is missing from the results, it isn’t available in that PowerShell environment. Install the missing module or make it available to the inventory account, then repeat the check.

For installation instructions, see Microsoft’s module setup guide, which also links to the PowerShellGet setup instructions.

Configure an app registration

vScope uses an app registration to authenticate to Exchange Online. You can reuse an existing registration or create a new one for Exchange Online inventory. In either case, add the Exchange Online API permission described below.

Use an existing app registration

If you already have an app registration configured for Azure RM inventory, you can reuse it for Exchange Online and continue to Configure API permissions.

Create a new app registration

Create a new app registration if you do not have one to reuse or prefer a separate registration for Exchange Online inventory.

You can create the app registration in either the Azure portal or the Microsoft Entra admin center.

Navigate to App registrations in the tenant you want to inventory.
Select New registration to create an application for Exchange Online inventory.
Enter a descriptive name, for example vScope Exchange Online.
Under Supported account types, select Accounts in this organizational directory only (Single tenant) to limit the application to your tenant.
Select Register to create the app registration.
On the application’s Overview page, copy the Application (client) ID and save it for use during setup.

Configure API permissions

Configure the app registration with the Exchange.ManageAsApp application permission to allow vScope to authenticate to Exchange Online PowerShell without a signed-in user.

Open the new or existing app registration and go to API permissions > Add a permission.
Select APIs my organization uses.
Search for and select Office 365 Exchange Online.
Select Application permissions.
Under Exchange, select Exchange.ManageAsApp and add the permission.
Grant Admin consent for your tenant to allow the application to use the permission.

Configure the certificate

Install a certificate on the Windows inventory target and upload its public certificate to the app registration to authenticate the application to Exchange Online without an interactive user sign-in.

To configure certificate-based authentication, create a new certificate or use an existing one that meets the requirements below. The following certificate types are supported:

Self-signed: Generated locally using PowerShell or another tool.
Internally issued: Issued by your organization’s internal Certificate Authority (CA).
Externally issued: Issued by a commercial Certificate Authority.

Certificates used for authentication must meet the following requirements:

Setting	Requirement
Certificate format	X.509 certificate with an RSA key.
Key provider	Must use a legacy CSP provider, not CNG.
Private key	Must have an accessible private key.
Key length	Recommended key length: 2048 bits or higher.
Validity	Must be valid and not expired.
Certificate store	Must be installed on the Windows inventory target in `Cert:\CurrentUser\My` for the account used to connect, or in `Cert:\LocalMachine\My`. The examples in this guide use `LocalMachine\My`.
Account permissions	The Windows account performing the inventory must have permission to access the private key.

To use an existing certificate, install it with its private key on the Windows inventory target in one of the certificate stores listed above.

Generate a self-signed certificate (optional)

If an existing certificate meets the requirements above, skip this step and continue to Configure private-key access.

The command below creates a self-signed certificate and saves it to Cert:\LocalMachine\My, as defined by -CertStoreLocation.

Replace <certificate-name> in -DnsName with a descriptive name and adjust -NotAfter to the required expiry date. The example uses AddMonths(6) for a validity period of six months.

Run the modified command on the Windows inventory target in PowerShell as Administrator:

$cert = New-SelfSignedCertificate `
    -DnsName "<certificate-name>" `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -NotAfter (Get-Date).AddMonths(6) `
    -KeySpec KeyExchange `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyExportPolicy Exportable `
    -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider"

Configure private-key access

For both existing and newly generated certificates, the Windows account performing the inventory needs read access to the private key on the Windows inventory target.

For a certificate in Cert:\LocalMachine\My:

On the Windows inventory target, open Manage computer certificates (certlm.msc) as Administrator.
Go to Personal > Certificates and locate the certificate created or chosen for Exchange Online authentication.
Open the certificate and check that the General tab indicates an associated private key. If the key is missing, install the certificate with its private key before continuing.
Right-click the certificate and select All Tasks > Manage Private Keys.
Check that the inventory account has Read permission under Allow, either directly or through a group. If access is missing, select Add, enter the inventory account, grant Read, and save the changes.

For a certificate in Cert:\CurrentUser\My, the certificate and private key must be installed in the store of the account performing the inventory. A certificate installed only in an administrator’s CurrentUser store is not available to a different inventory account.

Find and save the certificate thumbprint

Save the thumbprint of the certificate intended for Exchange Online authentication. It is used to export the public certificate and later to configure the Exchange Online credential in vScope.

Use the following command to list all certificates stored in Cert:\LocalMachine\My and Cert:\CurrentUser\My on the Windows inventory target. Run it as the inventory account to include that account’s CurrentUser store:

Get-ChildItem -Path Cert:\LocalMachine\My, Cert:\CurrentUser\My |
    Select-Object Subject, Thumbprint, NotAfter

Locate the certificate in the results and copy and save its Thumbprint.

Export the public certificate

The command below exports the public certificate to a .cer file for upload to the app registration.

Replace the placeholders before running the command on the Windows inventory target:

<thumbprint>: The full Thumbprint value saved for the certificate. Keep the surrounding path and quotation marks.
<export-path>: The output file’s path and name, ending in .cer. For example, .\certificate.cer saves to the current working directory, while C:\Certificates\certificate.cer saves to an existing C:\Certificates folder.

For a certificate in the inventory account’s CurrentUser store, replace Cert:\LocalMachine\My with Cert:\CurrentUser\My and run the command as that account.

$cert = Get-Item "Cert:\LocalMachine\My\<thumbprint>"

Export-Certificate `
    -Cert $cert `
    -FilePath "<export-path>"

Keep the exported .cer file for upload in the next section.

Upload the certificate

Upload the exported .cer file to the app registration used for Exchange Online authentication.

Open the app registration and go to Certificates & secrets > Certificates.
Select Upload certificate to add the public certificate to the app registration.
Browse to the .cer file saved during the export and select it.
Select Add to register the certificate with the application.

Configure Exchange Online permissions

Assign read permissions to the app registration to allow vScope to collect Exchange Online data. The Exchange.ManageAsApp API permission configured earlier enables authentication; the role assignment determines which data the application can access.

Choose one of the following methods:

Exchange service principal and RBAC role group (recommended): Manage the application’s Exchange permissions through a role group for more granular control.
Microsoft Entra role: Assign a built-in role with the required read permissions directly to the application.

Option 1: Use an Exchange service principal and RBAC role group (recommended)

Register the application as a service principal in Exchange Online and add it to a role group. Use the built-in View-Only Recipients management role for read access to Exchange Online data.

1. Register the service principal in Exchange Online

Open PowerShell and connect to Exchange Online using an administrator account with permission to manage service principals and role groups. Replace <administrator-upn> with that account’s User Principal Name (UPN):

Connect-ExchangeOnline -UserPrincipalName "<administrator-upn>"

Copy the following values for the app registration used for Exchange Online authentication:

Variable	Value
`$appId`	Application (client) ID from the app registration’s Overview page.
`$enterpriseObjectId`	Object ID of the corresponding application under Enterprise applications.

In the connected PowerShell session, replace the placeholders below with these values and register the service principal in Exchange Online:

$appId = "<application-client-id>"
$enterpriseObjectId = "<enterprise-application-object-id>"

New-ServicePrincipal `
    -AppId $appId `
    -ObjectId $enterpriseObjectId `
    -DisplayName 'vScope Exchange Reader'

2. Create the role group

In the same PowerShell session, create a role group with the recommended View-Only Recipients management role to provide read access to Exchange Online data:

New-RoleGroup `
    -Name 'vScope Exchange Reader' `
    -Roles 'View-Only Recipients'

3. Add the service principal to the role group

Continue in the same session and retrieve the service principal using the $enterpriseObjectId value defined earlier. The command stores the result in $sp:

$sp = Get-ServicePrincipal -Identity $enterpriseObjectId

Use $sp.Identity to add the service principal to the vScope Exchange Reader role group and grant the application the group’s Exchange read permissions:

Add-RoleGroupMember `
    -Identity 'vScope Exchange Reader' `
    -Member $sp.Identity

Continue to Add the Exchange Online credential in vScope. Option 2 is an alternative to this method.

Option 2: Assign a Microsoft Entra role

Assign a built-in Microsoft Entra role to the Enterprise Application associated with the app registration. The application uses the Exchange permissions included in that role to access data. Choose a role from Microsoft’s supported application roles that allows the application to read Exchange Online data without making changes.

The role assignment can be configured through either the Azure portal or the Microsoft Entra admin center.

Open the tenant’s Roles & admins page to view the available directory roles.
Open the role intended for Exchange Online read access and review its permissions.
Select Add assignments to choose the application that will receive the role.
Search for the app registration by name and select its corresponding Enterprise Application. Use the application configured earlier for Exchange Online authentication, whether newly created or reused.
Select Add to save the role assignment.

Add the Exchange Online credential in vScope

In vScope, go to Discovery > Credentials and create a credential for the Exchange Online platform.

Select the Credential type for connecting to the Windows inventory target and configure the account details for that alternative:

Credential type	Configuration
User & Password Credential	Enter the Windows account’s Username and Password under Details, or use Reuse Credential to select an existing credential.
No Authentication	Use OS-managed authentication, for example a gMSA. Do not enter a username or password in the credential. Configure the vScope Server or Proxy service identity and Windows access as described in Using gMSA.
LAPS	Let vScope retrieve the target’s local administrator password from Active Directory. Configure the service account’s password-read permissions and the other prerequisites in Using LAPS. Optionally enter a Local Administrator Username. If the field is left empty, vScope uses `.\Administrator`.

Confirm that the chosen credential type uses the Windows account prepared earlier. For LAPS, inventory runs as the target’s managed local account; the service account retrieves its password from Active Directory.
Optional: add a Note to describe the credential, for example Exchange Online mailboxes.
Under Advanced settings, configure Use HTTPS, Port, and JEA Endpoint Name only if required by the target’s remote PowerShell configuration. These settings control the Windows connection for any credential type. See Windows PowerShell advanced settings.

Under Authentication settings, enter the app registration and certificate values below. These values are required for all three credential types:

Credential field	Value to enter
Exchange Online Application ID	Application (client) ID from the app registration’s Overview page.
Exchange Online Organization	Tenant’s primary `onmicrosoft.com` domain, for example `contoso.onmicrosoft.com`.
Exchange Online Certificate Thumbprint	Thumbprint of the certificate installed on the Windows inventory target. See Find and save the certificate thumbprint.

Under Select targets, select the Windows machine prepared for inventory with the chosen authentication method, module, and certificate. Use Add new target if the machine is not listed.
Click the lightning-bolt icon in the target’s Test column to test the credential in vScope.
Save the credential and run discovery.

Troubleshooting

The credential test reports a missing module

Run the module availability check on the Windows target using the inventory account and PowerShell environment.
If ExchangeOnlineManagement, PowerShellGet, or PackageManagement is missing from the results, install it or make it available to that account.
Check the installed versions against Microsoft’s compatibility requirements and repeat the credential test in vScope.

The certificate cannot be found

Compare Exchange Online Certificate Thumbprint in the credential with the value from Find and save the certificate thumbprint.
Confirm the certificate is installed on the selected Windows target in a supported store. For CurrentUser certificates, inspect the store belonging to the account performing the inventory.
Correct the thumbprint or certificate location and repeat the credential test.

Access to the certificate’s private key is denied

Follow Configure private-key access to confirm that the certificate includes its private key and grant the inventory account Read access. For LAPS, configure access for the managed local account on the target. Repeat the credential test after changing permissions.

The certificate has expired or is about to expire

Check NotAfter on the Windows target and the certificate’s expiry date under the app registration’s Certificates & secrets > Certificates. Where possible, complete the replacement before the certificate expires.

Obtain a replacement certificate that meets the certificate requirements and install it on the Windows inventory target.
Configure private-key access for the account performing the inventory.
Save the new thumbprint, export the public certificate, and upload the .cer file to the same app registration. Keep the old certificate registered during the change if it is still valid.
In the vScope credential, update Exchange Online Certificate Thumbprint with the new thumbprint.
Test the credential against the Windows target and run discovery to confirm inventory works with the replacement.
After successful discovery, remove the old certificate from the app registration and Windows target only when it is no longer used by any other credentials or applications.

Exchange permission errors

Confirm administrator consent is granted for the Exchange.ManageAsApp application permission on the app registration used by the credential.
For the role-group approach, confirm the Exchange service principal uses the Enterprise application Object ID and is a member of vScope Exchange Reader.
Confirm the assigned role allows the application to read Exchange Online data, whether using a role group or a Microsoft Entra role.
Repeat the credential test in vScope and run discovery after correcting the assignments.