Setting up Exchange Web Services (EWS)

  • 15/02/2021
  • 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:

To register the application, follow these steps:

  1. Sign in to the Microsoft Azure portal with administrator privileges.
  2. In the search box at the top, search for and select App registrations.
  3. On the App registrations page, select New registration.
  4. On the Register an application page, under Name, enter a name – for example, Continia Document Capture Service (EWS).
  5. Under Supported account types, select Accounts in this organizational directory only (the default option).
  6. Select Register to complete the initial app registration.
  7. 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.
  8. 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.
  9. Select full_access_as_app > Add permissions.
  10. 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. In order 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, i.e. when authenticating with app registration. Both options are described in more detail below.

Creating and adding a certificate

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

  1. If you don't have an available certificate, you can create and sign your own following this guide.
  2. In the Microsoft Azure portal, go to the left menu. Under Manage, select Certificates & secrets.
  3. On the Certificates & secrets page, under Certificates, select Upload certificate.
  4. Select the certificate you want to use. Only the following file types are accepted: .cer, .pem, .crt.
  5. Select Add.
  6. 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:

  1. In the Microsoft Azure portal, go to the left menu. Under Manage, select Certificates & secrets.
  2. On the Certificates & secrets page, under Client secrets, select New client secret.
  3. In the dialog that opens, enter a free-text description for your client secret – for example, Continia Document Capture Service (EWS).
  4. Under Expires, select a duration. Never is recommended.
  5. Select Add.
  6. 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 will never be 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'll 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 this guide.

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 archived by following this Microsoft guide.

See also

Exchange Online
Microsoft Azure portal
Configuring email addresses using EWS