Views:

Question:
How can I best switch over my Connect to Mail configurations to using OAuth2 authentication?

Answer:

Please refer to the following guide on how to enable OAuth2 authentication for Connect to Mail:

Background Information
Microsoft has stated Basic Authentication is officially announced to be deprecated effective October 1, 2022. After this date, it will no longer be possible to configure Basic Authentication for Exchange Online systems. 

With the upcoming deprecation, it'll become necessary to implement OAuth2 authentication to ensure that your Connect to Mail jobs remain functional. Making the changes can vary depending on your situation with which DocuWare system you are using. Please consider the following scenarios with respect to how to begin using OAuth2.

For additional information regarding the deprecation of basic authentication, please see: Deprecation of basic authentication/exchange-online

***Note: Even when Basic Authentication is disabled, SMTP Auth will still be available.***


For Cloud Customers without creating a self-created app in Azure
There is no need to create a Mail Service configuration since we already deliver everything for connecting to your Office 365 mail account with OAuth2. Go to your “General Email” plugin and connect directly with your Office 365 account by selecting the “Exchange Online” option.


For Cloud Customers using a self-created app in Azure
If you want to connect to Office 365 with your self-created app, follow the steps below:

Register the OAuth app in your organization's Azure Active Directory

  1. Switch to your organization's app registration and click on the New registration plus icon [https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
  2. Give it a display name and provide a Redirect URI such as "https://my-company.com/DocuWare/Settings?link=MailCapture" 
    Note: The Redirect URI is case-sensitive and must be accessible from the internet. This redirect url will be called by Microsoft after a user has successfully authenticated

  3. Open the "Authentication" menu from the left and scroll down to the header "Implicit grant". Please ensure both "Access tokens" and "ID tokens" are checked, then save your changes.
    Image
  4. Switch to the "Certificates & secrets" menu and create a new client secret. Please store this client's secret safely. We will need it later while registering the app in DocuWare Mail Services.
  5. Next, on the app registration menu, select "API permissions" and add a new permission.
    • Select here "Microsoft Graph" from the Microsoft APIs and click on "Delegated permissions"
    • Add the following permissions below and store your changes: 
      • offline_access
      • openid
      • EWS.AccessAsUser.All
      • User.Read
        Image
  6. Finally, click "Grant admin consent for YOUR COMPANY NAME" from the overview of configured permissions. This is step is optional. If you don't grant access now, an organization administrator must do it afterward. Otherwise, the user won't be able to grant permission for Connect to Mail.
     
  7. Congratulations! You now have successfully configured your personal OAuth2 app. Switch to the overview and copy the values of "Application (client) ID," "OAuth 2.0 authorization endpoint (v2)," and "OAuth 2.0 token endpoint (v2)" (from the Endpoints menu). We will need them for registering in the mail services plugin
    Image


Allow access to Connect to Mail to Exchange Web Services APIs
Before heading to DocuWare, we must classify the Exchange Web Services APIs as low impact.

Note: This step is required regardless of whether you're using the official DocuWare Cloud OAuth app or your self-registered Azure App.
  1. From the Azure Active Directory, open the blade "Enterprise applications"
  2. Next, move to "Consent and permissions" [https://portal.azure.com/?l=en.en-us#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings]
  3. In the submenu "User consent settings (Preview)," select "Allow user consent for apps from verified publishers, for selected permissions (Recommended)"
    Image
  4. Click-on permissions are classified as low impact and the Exchange Web Services APIs. It should be displayed as the following:

    Permissions
    EWS.AccessAsUse.All
    Offline_access
    profile
    openid
    email
    User.Read


  5. Remember to save your changes, and users will now be able to grant access to this app. Please proceed to the following section.

Create a new Exchange mail service connection in DocuWare (Cloud)
Now that we've everything in place, it's time to introduce this to Connect to Mail so that Connect to Mail authenticates via OAuth2 on Exchange.

Note: Creating a connection to Exchange mail service in Connect to Mail is only required if you want to connect Office 365 / Exchange Online from DocuWare On-Premises or your Office 365 is working from Microsoft National Cloud.
  1. Open the DocuWare Configurations [https://your-DocuWare/DocuWare/Settings]
  2. Open the Mail Service plugin and select create a new Exchange mail service
  3. Make sure the Authentication type is set to "Use OAuth2 Authentication"
  4. Fill in all details that you've noted down while creating the new Azure Active Directory app registration.
  5. Don't forget to enter the exact same Redirect URI from the registration (e.g. "https://my-company.com/DocuWare/Settings?link=MailCapture")
  6. It may be required to change the Exchange Web Services URL.
  7. Store and save your configuration
  8. Now, you're able to use this new Exchange mail service connection in the General Email plugin.


For On-premise customers using a self-created app in Azure
Register your application as a public client with Azure Active Directory. You can register an application in the Azure Active Directory admin center or using Microsoft Graph. The following are instructions provided by Microsoft from the link below:
How to authenticate an ews application by using oauth/register-your-application
  1. Open a browser and navigate to the Azure Active Directory admin center, and log in using a personal account (aka: Microsoft Account) or Work or School Account.
  2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.
  3. Select New registration. On the Register an application page set the values as follows.
    • Set Name to a friendly name for your app.
    • Set Supported account types to the choice that makes sense for your scenario.
    • For Redirect URI, change the dropdown to Web and set the value to "https://my-company.com/DocuWare/Settings?link=MailCapture".
  4.   Choose Register. On the next page, copy the value of the Application (client) ID; you will need it later.
Once the application has been created, you’ll need the following information for setting up the Mail Service in DocuWare
  • Application (client) ID
  • Client secret
  • OAuth 2.0 authorization endpoint
  • OAuth 2.0 token endpoint
  • Redirect URI
     
Create a new Exchange mail service connection in DocuWare (On-Premise)
Now that we've everything in place, it's time to introduce this to Connect to Mail, so that Connect to Mail authenticates via OAuth2 on Exchange.

Note: Creating a connection to Exchange mail service in Connect to Mail is only required if you want to connect Office 365 / Exchange Online from DocuWare On-Premises or your Office 365 is working from Microsoft National Cloud.
  1. Open the DocuWare Configurations [https://your-DocuWare/DocuWare/Settings]
  2. Open the Mail Service plugin and select create a new Exchange mail service
  3. Make sure the Authentication type is set to "Use OAuth2 Authentication"
  4. Fill in all details that you've noted down while creating the new Azure Active Directory app registration.
  5. Don't forget to enter the exact same Redirect URI from the registration (e.g., "https://my-company.com/DocuWare/Settings?link=MailCapture")
  6. It may be required to change the Exchange Web Services URL.
  7. Store and save your configuration
  8. Now, you're able to use this new Exchange mail service connection in the General Email plugin.
     
Upgrading existing mail connections to new OAuth2 authentication
Prior to Basic Authentication being disabled, we recommend leaving the existing impersonation mail service unchanged so that already connected mail accounts work properly until Microsoft denies the basic authentication completely on October 1st, 2022.
Everyone with an existing mail connection in the General Email plugin needs to re-login with the new "Login with Microsoft" option. Users with an existing mail connection must either select the official DocuWare "Exchange Online" mail service (only available to DocuWare Cloud) or the newly created Exchange mail service based on the OAuth authentication. For additional information and recommendations regarding OAuth2 authentication in Connect to Mail, please see KBA-36552  · DocuWare Support Portal.


Note: Once Microsoft depreciates the login via basic authentication on Office365 & Exchange Online, mail connections using the old mechanism won't be able to use Connect to Mail anymore. They will be disabled automatically by DocuWare.

KBA is applicable for both Cloud and On-premise Organizations.
Comments (1)