Skip to main content

ACRM Office 365 Setup

Csaba Daniel
  • Updated

To allow the ACRM Exchange Connector access to mailboxes in Office 365, follow these steps:

 

Step 0: Pre-requisites

  1. The administrative user (App owner) needs a Microsoft basic license and a mailbox. If no such license exists, the following error will be issued:

Error  ;  61128704; 8848;0  ;CollectedMailboxesFilter.Filter Loaded mailbox: Smtp: max.mustermann@musterag.net

2024.12.04;13:29:36;   0;update.connector ;Error  ;  61128704; 8848;0  ;CollectedMailboxesFilter.Filter ----------------------------------------------------------

2024.12.04;13:29:38; 1297;update.connector ;Error  ;  69885952; 8848;50,26392;EwsService.Connect For EWS version Exchange2013_SP1 exception caught: Type = SCEwsToolkit.EwsService.Exceptions.EwsServiceResponseException, Message = The SMTP address has no mailbox associated with it.

  1. The administrative user requires the Exchange Administrator role:

Step 1: Set up OAuth Authentication in Microsoft Entra

  1. Navigate to the Microsoft Entra Admin Center
  1. Register Your Application
    • In the left-hand navigation, select Identity → Applications → App Registrations.

  • Click New registration.

  • On the Register an application page, fill in the following details:

    • Name: Enter a name for your application.
    • Supported account types: Choose one:
      • Single Tenant
      • Multitenant
    • Redirect URL: Change the dropdown to Public client (mobile & desktop) and set the value to urn:ietf:wg:oauth:2.0:oob
  • Click Register.

  1. Save Application Details
    • On the next page, copy the Application (client) ID and Directory (tenant) ID. Save these for later use with the ACRM Exchange Connector.
  1. You can access this information anytime via: Identity → Applications → App Registrations → All Applications.

 

Step 2: Configure API Permissions

  1. Add API Permissions
    • Select API Permissions from the left-hand menu.

  • Click Add a permission and go to the APIs my organization uses tab.
  • Search for and select Office 365 Exchange Online. (This option will appear only if the account has an active Office 365 subscription with Exchange.)

  1. Grant Application Permissions
    • Choose Application permissions and check full_access_as_app.
    • Click Add permissions.
    • Grant admin consent by selecting Grant admin consent for and confirming the consent dialog.

 

Step 3: Create a Client Secret

  1. Generate a Client Secret
    • In the left-hand navigation, go to Certificates & Secrets.
    • Select New client secret, add a short description, and click Add.
    • IMPORTANT: Copy the value of the client secret and save it. Once you close this screen, you won’t be able to access it again. If lost, you will need to create a new client secret.

 

Step 4: Set Up ACRM Exchange Connector Credentials

  1. Open the update.Users.exe application in the connector installation folder:
    <ACRM installation folder>\update.connector+.

  2. Select UserType: EWS Impersonation User, then click Edit User.

  1. Fill in the following details:

    • User: The email address for your Office 365 account.
    • Password: Leave blank.
    • Client ID: Enter the Application (client) ID.
    • Client Secret: Enter the saved client secret.
    • Tenant: Enter the Directory (tenant) ID.
    • Scopes: https://outlook.office.com/.default.

 

Step 5: Grant Application Access to Mailboxes

The above steps enable the application to use the Exchange Web Services (EWS) API. To grant access to specific or all mailboxes, assign the appropriate role:

  1. Connect to Exchange Online
    • Ensure you have the necessary permissions in Exchange Online and Azure AD.
    • Open a cloud shell and run:

Connect-ExchangeOnline

  1. Enable Organization Customization (if required)
    • If custom role assignments are not already enabled, execute:

Enable-OrganizationCustomization

This step can take several minutes.

  1. Retrieve the Application Object ID
    • Go to Azure → Enterprise applications and locate your application.
    • Copy the Application ID.
    • Copy the Object ID.

Create the Service Principal (if required)

The Application ID should sync automatically to Exchange Online as a Service Principal. However, in some cases, delays or issues with synchronization may prevent it from being recognized. If the New-ManagementRoleAssignment command fails with an error like "Couldn't find a service principal with the following identity" create the service principal using this command:

New-ServicePrincipal -AppId <Application-ID> -ObjectId <Object-ID>

Replace <Application-ID> with the Application ID and <Object-ID> with the Object ID. This step ensures the Service Principal is properly registered with Exchange Online.

  1. Assign the Role
    • Run the following PowerShell command:

New-ManagementRoleAssignment -Role "Application EWS.AccessAsApp" -App <Application-Object-ID>

  • Replace <Application-Object-ID> with the copied Object ID.

  1. Verify the Role Assignment
    • Confirm the role assignment by running:

Get-ManagementRoleAssignment -Role "Application EWS.AccessAsApp"

 

Key Notes

  • Enable-OrganizationCustomization is mandatory for tenants without custom RBAC (Role-Based Access Control) configurations.
  • Ensure the application has necessary permissions in both Azure AD and Exchange Online.
  • Both Application ID (AppId) and Object ID (ObjectId) are required for creating the Service Principal if it isn’t recognized by Exchange Online.
  • The Application ID should sync automatically, but delays in Azure AD synchronization with Exchange Online can occasionally cause issues.

 

References

 

Related articles