Changing authentication method for Connect to Mail

Question:
How can I change the authentication method for Connect to Mail?
 
Solution:
Connect to Mail was designed to connect to your Exchange mailbox via an Exchange impersonator account and the use of "Exchange Web Services". This impersonator account has been authenticated by the basic authentication method in older DocuWare versions. Starting in the second half of 2022, this authentication method will be deprecated for Office 365 and Exchange Online accounts. This being said, DocuWare relies on “Oauth2” as an authentication method. Please refer to the following information for setting up your OAuth connection for Exchange Online:
(Note: Currently, DocuWare does not support Exchange On-Premises with activated OAuth authentication. Please use Basic Authentication in such cases.)

Actions required in order to use the new authentication (Cloud Organizations):
Before connecting DocuWare Cloud with an Exchange Online / Office 365 account, you may need to revise the settings for “Admin consent requests” in your organization's Azure Active Directory (AAD). This setting allows your organization's users to request admin approval for apps. Connect To Mail requires permissions to access the organization's Exchange Web Services APIs, which can only be granted by an organization administrator.

When setting up the official DocuWare Cloud app for the first time, a user will see a screen Approval required screen. Here, you can request an approval for the app.
Note: All subsequent users will not have to request approval. They can use the DocuWare Cloud app right away.



From the User settings of the Azure Enterprise application, if your admin consent request settings are like shown below, users can request approval for Azure AD Apps, no changes are required.

Admin consent request (Preview)
Users can request admin consent to apps they are unable to consent to = Yes
Select users to review admin consent request = Select user(s) accordingly
Selected users will receive email notifications for request = Yes
Selected users will receive request expiration reminders = Yes


Incoming requests are then placed under “Admin consent requests (Preview),” an administrator can review and consent to the required permissions for the DocuWare Cloud app.
For more on the admin consent workflow, please see Configure the admin consent workflow




Every user can now connect directly with their Office 365 mailboxes right out of the DocuWare General Email plugin. No further consent requests are required.


If you want to connect to Office 365 with your self-registered Azure AD app, follow the steps below like for on-premises customers

On-premises Customers:
Please follow the instructions on Microsoft’s Office Dev Center for properly setting up an OAuth app registration in your company's Azure Active Directory. [https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth#register-your-application]


When do I have to register my own app in the Azure Active Directory?
Primarily, this is for the On-Premises customers of DocuWare, who would like to connect to their Office 365 / Exchange Online mail accounts.
On the other hand, it's also required for Office 365 / Exchange Online mail accounts that are hosted on Azure's National cloud [https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud]
Please follow the  following instructions

Register OAuth app in your organization's Azure Active Directory

1. Switch to your organization's app registration and click on "New registration".
2. Name the app registration 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". It's required to check "Access tokens" and "ID tokens". Now save your changes.
   
4. Switch to the "Certificates & secrets" menu and create a new client secret. Please store this client 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 API's and click on "Delegated permissions"
   • Ensure or Add the following permissions to the Microsoft Graph, then store your changes: 
     • offline_access
     • openid
     • EWS.AccessAsUser.Al
     • User.Read
       
6. Finally, click "Grant admin consent for YOUR COMPANY NAME" from the overview of configured permissions. This step is optional. If you don't grant access now, an organization administrator must do it afterwards; 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
   

1. Open the DocuWare Configurations [https://your-DocuWare/DocuWare/Settings]
2. Open the Mail Service plugin and select to create a new Exchange mail service
3. Make sure the Authentication type is set to "Use OAuth2 Authentication"
4. Fill all the 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 (eg. "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
We recommend leaving the existing impersonation mail service unchanged, so that already connected mail accounts work properly furthermore until Microsoft denies the basic authentication completely.
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.

Note: Once Microsoft denies the log-in via basic authentication on Office365 and 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.

For more on App registration and OAuth, please see: How to authenticate an ews application by using OAuth.

KBA is applicable to both Cloud and On-premise Organizations