Skip to main content
Version: 7.9

EWS Gateway

Introduction​

The EWS Gateway allows you to connect your Resolve Actions Pro deployment with a Microsoft Office365 tenant or a Microsoft Exchange Server for the purpose of reading and writing PIM data like emails, calendar events, and contacts. It utilizes the Microsoft Office365 Exchange Online API to communicate with and oAuth to authenticate to the Office365 tenant.

The step-by-step instructions in this guide provide an example of how to set up the EWS Gateway to connect to a Microsoft Office365 tenant over OAuth.

note

The EWS gateway does not support encryption or decryption of email messages. The gateway will pull messages that were stored encrypted on the server in the same encrypted form. You can use custom ActionTask logic to decrypt and re-encrypt them as needed.

Actions Pro does not provide built-in APIs to decrypt or encrypt emails. Depending on the encryption method, you may want to introduce a third-party library that could do that.

Set Up an Azure Application​

Before you can connect your Office365 account with Actions Pro, you need to set up an Azure application for the EWS Gateway and take note of some if its details to later provide in Actions Pro.

Before you start, read this information by Microsoft and decide if you want to use Delegated Permissions or Application Permissions when assigning API permissions in your Azure application:

  • Delegated permissions are used by apps that have a signed-in user present. For these apps, either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making calls to Microsoft Graph. Some delegated permissions can be consented by non-administrative users, but some higher-privileged permissions require administrator consent.
  • Application permissions are used by apps that run without a signed-in user present. For example, apps that run as background services or daemons. Application permissions can only be consented by an administrator.

Take these steps to create an Azure application for the EWS Gateway:

  1. Log into the Microsoft Azure Portal.
  2. Under Azure services, open App Registrations.
  3. Click New registration and fill in the Register an application form:
    1. In Name, type in a name for your Azure app (for example, Resolve Actions PRO – EWS Gateway).
    2. Under Supported account types, select a security option to match your preferences.
    3. Under Redirect URI, leave the fields blank.
    4. Click Register.
  4. On the application's Overview page, take note of Application (client) ID and Directory (tenant) ID.
  5. In the left navigation, click Authentication and enable Allow public client flows.
  6. Take these steps if you selected the Application Permissions model:
    1. In the left navigation, click Certificates & secrets and then click New client secret.
    2. Type in a description.
    3. In Expires, specify when you want the secret to expire.
      note

      Before the client secret expires, you will need to generate another and reconfigure blueprint.properties in Actions Pro with the updated value.

    4. Click Add to generate the new client secret and immediately then take note of Value.
      caution

      This is the only time this value will be shown in clear text. If you fail to take note of it, you will have to generate a new client secret.

  7. In the left navigation, click API permissions and then click Add a permission.
  8. Click APIs my organization uses and select Office 365 Exchange Online.
  9. Take the following steps depending on which security model you have chosen:
    • When using Delegated Permissions:
      1. Click Delegated permissions to enable the EWS Gateway to access the mailbox as a signed-in user.
      2. Under Permissions, expand EWS and check the EWS.AccessAsUser.All box.
      3. Click Add Permissions.
        note

        You need to create a new EWS Address for each mailbox that you want to monitor or poll and provide the mailbox address and password to Actions Pro.

    • When using Application permissions:
      1. Click Application permissions to enable the EWS Gateway to grant admin-level access to all mailboxes.
      2. Under Permissions, expand Other permissions and check the full_access_as_app box.
      3. Click Add Permissions.
        note

        You need to create a new EWS Address for each mailbox that you want to monitor or poll and provide the mailbox address, but not the password, to Actions Pro.

  10. Finally, back on the API permissions screen, click Grant admin consent for....

Configure Actions Pro​

The EWS Gateway is enabled by default in Actions Pro but you still need to configure the app-specific authentication details in blueprint.properties and the gateway settings in the Actions Pro web interface.

Configuring blueprint.properties​

After you have the details from the Azure application, you can configure blueprint.properties on the Actions Pro side.

Take these steps to configure oAuth in Actions Pro:

  1. Stop RSRemote:
    <actions-pro-home>/bin/stop.sh rsremote
  2. Open blueprint.properties for editing:
    vi <actions-pro-home>/bin/blueprint.properties
  3. Ensure that the EWS gateway is enabled:
    rsremote.receive.ews.active=true
  4. Enable oAuth:
    rsremote.receive.ews.OAuth_Enabled=true
  5. Configure the Client ID and Tenant ID values from the Azure application:
    rsremote.receive.ews.client_id=<value-from-Azure>
    rsremote.receive.ews.tenant_id=<value-from-Azure>
  6. Configure the Client Secret value from the Azure application:
    • When using Application Permissions, set the following property to it:
      rsremote.receive.ews.client_secret=<value-from-Azure>
    • When using Delegated Permissions, leave the property blank:
      rsremote.receive.ews.client_secret=
  7. Configure the scope to the following value:
    rsremote.receive.ews.scope=https://outlook.office365.com/EWS.AccessAsUser.All
  8. Apply the changes:
    <actions-pro-home>/bin/config.sh
  9. Restart RSRemote:
    <actions-pro-home>/bin/run.sh rsremote
note

See ::Blueprint RSRemote Configuration for the full set of EWS Gateway properties that you can customize in blueprint.properties.

Adding Mailboxes to be Monitored​

After you set up Azure and blueprint.properties, you need to specify the mailbox to monitor.

  • If you chose to use Delegated Permissions, you need to specify the mailbox address and a password to access it.
  • If you chose to use Application Permissions, then you only need to specify the mailbox address. A password is not required as the Azure application (using the full_access_as_app permission) has access over all the tenant's mailboxes. To learn how to lock down the Azure application to specific mailboxes, see Limiting Exchange Access to Specific Mailboxes.

Take these steps to specify a mailbox to monitor:

  1. Log in to Action Pro.
  2. From the main menu, select Remote Administration > Gateway Filter Administration.
  3. From Gateway Type, select EWS.
  4. Go to the EWS Addresses tab.
  5. Click Create New.
  6. In EWS Address, enter the mailbox's email address.
  7. In EWS Password, do the following:
    • If using Delegated Permissions, enter the password of the delegated account.
    • If using Application Permissions, leave the field empty.
  8. Check Shared Inbox if the entered EWS Address corresponds to a shared Exchange mailbox. In this case:
    • In EWS Address, ensure that you have entered the shared inbox's address.
    • In the Shared Inbox Username field that appears, enter the username of the user who will be accessing the shared inbox in the name@domain.tld format.
    • In EWS Password, ensure that you have entered the password for the user specified in Shared Inbox Username.
  9. Click Save.
  10. Back on the EWS Addresses tab, select the entry that you just created and click Deploy to deploy the new EWS Address to the gateway.

Repeat the procedure for every mailbox that you want to monitor.

Limiting Exchange Access to Specific Mailboxes​

There are scenarios where your organization might want to limit an Azure application to only specific mailboxes and not all Exchange Online mailboxes in the organization. You can identify the set of mailboxes to permit access to by putting them in a mail-enabled security group. You can then limit third-party application access to only that set of mailboxes by creating an application access policy for access to that group. For details, see the official Microsoft documentation.

Troubleshooting​

Review the RSRemote log when experiencing set up problems with the EWS Gateway. To locate it, log in to the RSRemote node and open <actions-pro-home>/rsremote/log/rsremote.log.

Incorrect client_id, client_secret, tenant_id will usually show up as AuthenticationException or 401 Unauthorized error messages.