Setting up Exchange Web Services (EWS)

27/08/2024
7 minutes to read

For email servers that are configured and used for on-premises OCR, the Continia OCR service supports Exchange Web Services (EWS), which makes it possible to authenticate with Exchange Online using OAuth 2.0.

To set up EWS, you must complete the following guides in the order given. Note that you should complete either Creating and adding a certificate or Creating and adding a client secret – you don't have to complete both.

Creating an app registration in Azure Active Directory.

In order to authenticate with Exchange Online, you must register the Continia OCR service as an application in Azure Active Directory (Azure AD). This registration establishes a trust relationship between the Continia OCR service and the Microsoft identity platform.

Before you can register the application, the following prerequisites must be met:

You must have an Azure account with an active subscription. This can be created for free here.
An Azure AD tenant must be set up. For more information, see Quickstart: Set up a tenant (Microsoft article).

To register the application:

Sign in to the Microsoft Azure portal with administrator privileges.
In the search box at the top, search for and select App registrations.
On the App registrations page, select New registration.
On the Register an application page, under Name, enter a name – for example, Continia Document Capture Service (EWS).
Under Supported account types, select Accounts in this organizational directory only (the default option).
Select Register to complete the initial app registration.
You're returned to the App registrations page, where the app registration's Overview pane is displayed. In the left menu, under Manage, select API permissions > Add a permission.
On the Request API permissions page, under APIs my organization uses, search for and select the Office 365 Exchange Online API and then Application permissions.
Select full_access_as_app > Add permissions.
You're returned to the API permissions page. In the list of API permissions, under Exchange, select full_access_as_app and then Grant admin consent for <domainame>.

To finish the app registration, the Document Capture OCR service must authenticate against the registration. For this to happen, you must add credentials in the form of either a client secret (the recommended option) or a certificate. The credentials are used to prove the application's identity when requesting a token, that is, when authenticating with app registration. Both options are described below.

Creating and adding a certificate

To use a certificate (also known as a public key) in the app registration process described above:

If you don't have an available certificate, you can create and sign your own following Generate and export certificates for point-to-site using PowerShell (Microsoft article).
In the Microsoft Azure portal, go to the left menu. Under Manage, select Certificates & secrets.
On the Certificates & secrets page, under Certificates, select Upload certificate.
Select the certificate you want to use. Only the following file types are accepted: .cer, .pem, .crt.
Select Add.
Copy the thumbprint that's displayed below the Upload certificate button. You'll need to enter it in Microsoft Dynamics NAV/Business Central later.

Important

The certificate you use must be installed on the server that's running the Continia Document Capture service.

Creating and adding a client secret

To use a client secret (also known as an application password) in the app registration process described above, follow these steps:

In the Microsoft Azure portal, go to the left menu. Under Manage, select Certificates & secrets.
On the Certificates & secrets page, under Client secrets, select New client secret.
In the dialog that opens, enter a free-text description for your client secret – for example, Continia Document Capture Service (EWS).
Under Expires, select a duration. Never is recommended.
Select Add.
The client secret is added, and you're returned to the Certificates & secrets page. Copy the secret's value and keep it in a safe place, as it is not displayed again once you've navigated away from the page.

Setting up categories in Document Capture

When you've added a certificate or a client secret as described above, the app registration is complete. However, before leaving Azure, navigate back to the Overview pane using the left menu, and then copy the values displayed in the following two fields:

Application (client) ID
Directory (tenant) ID

You need both of these values – along with your previously copied certificate thumbprint or client secret value (depending on your choice of credentials) – when you configure categories for document import.

When you've recorded all required values, you're ready to set up categories for document import in Document Capture. To do this, open NAV/Business Central and then follow Creating and Configuring Email Addresses for Document Import.

Security recommendations

As app registration provides access to all mailboxes in the domain, we recommend that you only associate the registration with the necessary subset of email addresses that function as mail-in accounts for documents to be processed in Document Capture. This can be done by following Limiting application permissions to specific Exchange Online mailboxes (Microsoft article).

Table of Contents