Skip to main content
Matrix42 Self-Service Help Center

Configuring Microsoft Azure settings for the E-mail Robot service connection

  1. Last updated
  2. Save as PDF

Overview

If you wish to set up the E-mail Robot that will connect to an Exchange / Office 365 or Exchange / Microsoft Graph mailbox, you need to configure the access to the Microsoft Azure portal.

The configuration steps are as follows:

  1. Setting up the authentication and authorization for ESM in Microsoft Azure portal.
  2. Creating a tenant in Enterprise Service Management.
  3. Adding a capability for the Microsoft Entra ID service in ESM.
  4. Create a service connection in Enterprise Service Management.

 Configuring the authentication and authorization in Microsoft Azure portal

To configure the integration settings in Microsoft Azure portal, you will need to register your Enterprise Service Management application on the portal.

Registering an application

Information about required permissions to create and manage a Registered App in Azure is available here (external link).

  1. On the Microsoft Azure Portal home page, go to the Azure services or use the Search resources search bar and open App registrations.
    01Azure_app_registration.png
    Microsoft Azure Portal: App registrations
  1. On the opened page, run the New registration action.
  2. Configure your application:
  • Provide a name for the application integration. The DWP users will see the display name when applying the Setup Authentication for the configured Service Connection.
  • Choose Supported account types.
  • Add a Redirect URI: select Web and enter Redirect URI (in the following format: https://{your_domain_name}/wm/externalAuth/redirect.html).
  1. Click Register.
    02_register_an_app.png
    Microsoft Azure Portal: Register an application

Assigning permissions

Permissions of two types can be granted in Azure for data access:

  1. Delegated permissions (access on behalf of a user)
  2. Application permissions (access independent from a user)

Please make sure you understand the impact of each permission type and configure the type of permissions that suits you best. Specific information provided by Microsoft is available here (external link).

For all "delegated" permissions you have granted to the registered App, it is required that the user who authenticates the created Service Connection in Enterprise Service Management needs to have the corresponding access rights in Azure.

For all "application" permissions you have granted to the registered App, the access rights of the authenticating user are not effective.

Only Application permissions can be used with direct E-mail Robot configuration (without using a service connection).  For details, please refer to Mail box settings.

If a service connection is configured using application permissions, any mailbox of any user in the company can be accessed by E-mail Robot. However, this can be remedied by limiting application permissions on Azure via PowerShell (external link).

Granting permissions for the Exchange / Office 365 connection type

Azure Portal does not provide Office 365 Exchange Online permissions in the permission list for new application registrations. To assign such permissions, you need to edit Application Manifest manually.

Microsoft strongly suggests using Microsoft Graph over EWS for Exchange Online, so Microsoft Graph connection is recommended for accessing cloud Exchange mailboxes.

Delegated permissions

  1. In your registered application, go to Manifest, locate the requiredResourceAccess property in the manifest and add the following code inside the square brackets ([]):
{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
            "type": "Scope"
        }
    ]
}

Edit Application Manifest

  1. Click Save, go to the API permissions section and check that the EWS.AccessAsUser.All permission is listed.
  2. Then click Grant admin consent for <organization> and accept the consent dialog.

Edit Application Manifest

Application permissions

  1. In your registered application, go to Manifest , locate the requiredResourceAccess property in the manifest and add the following code inside the square brackets ([]):
{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
            "type": "Scope"
        }
    ]
}

Edit Application Manifest

  1. Click Save, go to the API permissions section and check that the full_access_as_app permission is listed.
  2. Then click Grant admin consent for <organization> and accept the consent dialog.

Edit Application Manifest

Granting permissions for the Exchange / Microsoft Graph connection type

Delegated permissions

  1. In your registered application, go to the API permissions section and click + Add a permission.
  2. Choose Microsoft Graph > Delegated permissions and add the following permissions:
  • Mail.ReadWrite.Shared (or Mail.ReadWrite if you do not require the E-mail Robot to access shared mailboxes)
  • offline_access
  • User.Read
  1. Then click Grant admin consent for <organization> and accept the consent dialog.

clipboard_e78da2d331624958cad7df3adaf949234.png

The Exchange / Microsoft Graph connection with delegated permissions can only access mailboxes (personal and shared) which are available to the user who is authenticated for the Service Connection (the user logged in while performing "Setup Authentication" action before saving Service Connection).

Application permissions 

  1. In your registered application, go to the API permissions section and click + Add a permission.
  2. Choose Microsoft Graph > Application permissions and add the Mail.ReadWrite permission.
  3. Then click Grant admin consent for <organization> and accept the consent dialog.

05_access_web_api.png

Creating a secret key

  1. Go to the Certificates & secrets section of the new application.
  2. Run the New client secret action to create a secret key.
  3. Provide the description and expiration date for the key and click Add.
  4. After a new key is displayed, copy its value immediately. Later it will be encrypted.

Save the secret key value. It will be used to create a service connection in Matrix42 Enterprise Service Management.

04_client_secret1.png

Retrieving the client ID and tenant ID

Client ID and tenant ID of your registered application are required for creating a service connection. You can find these values in the Overview section of the registered application.

03_client_tenant_ids1.png

For more information about app registration, see also Microsoft Documentation Quickstart: Register an application with the Microsoft identity platform. 

Creating a tenant

In Matrix42 Enterprise Service Management, you need to create a tenant for the service connection.

  1. Go to the Administration application and open the Integration > Service Connections > Tenants navigation item.
  2. Run the Add Tenant action. A new tenant dialog opens.
  3. Provide an appropriate name for your tenant from the Microsoft Azure portal.
  4. Select Microsoft Entra ID in the Service field.
  5. Fill in the Client ID, Tenant and Client Secret fields with the data from Microsoft Azure.
  6. Save the dialog.

Adding a capability for the Microsoft Entra ID service

To set up delegated permissions in Matrix42 Enterprise Service Management, you need to add a capability for the default Microsoft Entra ID service. If you wish to use application permissions, skip this step.

To add the capability:

  1. Go to the Administration application and open the Integration > Service Connections > Services.
  2. Find and open for editing the Microsoft Entra ID service.
  3. In the Capabilities grid, add a record with the following values:
  • Scope: offline_access+User.Read+Mail.ReadWrite.Shared+EWS.AccessAsUser.All (replace ReadWrite.Shared with Mail.ReadWrite if you do not require the E-mail Robot to access shared mailboxes)
  • Validate Uri: https://graph.microsoft.com/v1.0/me

Add_Capability.png

  1. Save changes for the capability and the service.

MsEntraIdService.png

For additional information on how to add a scope, see also Microsoft Documentation Quickstart: Configure an application to access a web API.

Creting a service connection

Next, create a service connection to your company's Microsoft Azure portal.

  1. In the Administration application, go to Integration > Service Connections > Connections.
  2. Run the Add Service Connection action. A new connection dialog opens.
  3. In the Service field, select Microsoft Entra ID - E-mail Robot for delegated access or Microsoft Entra ID - Microsoft Entra ID (Application) for application access.
  4. In the Tenant field, select the tenant record that you have created earlier.
  5. Click Setup authentication.
  6. Provide the credentials for your company's Microsoft Azure portal and save the dialog in case of delegated access. The application based access will be authenticated immediately.

The user account that is used for authenticating needs to have a M365 license.

This service connection can now be used when configuring Mail box settings for the E-mail Robot.