Changing authentication method for Connect to Mail
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 version. Starting second half of 2021 this authentication method will be deprecated for Office 365 and Exchange Online accounts. That is why DocuWare relies on “Oauth2” as an authentication method.
What customers have to do in order to use the new authentication
Before connecting DocuWare Cloud with an Exchange Online / Office 365 account you may need to revise the settings for “Admin consent requests” in your organizations Azure Active Directory (AAD). This setting is to allow your organizations users the request of an admin approval for apps. Connect To Mail requires permissions to access the organizations Exchange Web Services APIs, which can only be granted by an organization admin.
When setting up the official DocuWare Cloud app for the first time, a user will see a screen like below. At this step, he can request an approval for the app.
All subsequent users will not have to request approval. They can use the DocuWare Cloud app right away.
If your settings are like shown below, users can request an approval for Azure AD Apps, no changes are required.
Incoming requests are then placed under “Admin consent requests (Preview)” and an admin can review and consent the required permissions for the DocuWare Cloud app.
Read more about the admin consent workflow here: [https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-admin-consent-workflow]
Right out of the DocuWare General Email plugin every user can now connect directly with their Office 365 mailboxes. 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
Please follow the instructions on Microsoft’s Office Dev Center for properly setting up an OAuth app registration in your companies 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 at 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 organizations Azure Active Directory
- Switch to your organizations app registration and click on the plus icon [https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
- Give it a friendly display name and provide a Redirect URI like "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 an user has successfully authenticated
- 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.
- 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.
- 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"
- Add the following permissions below and store your changes:
- Now your configured permissions should look like this:
- Finally click on "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 afterwards, otherwise the user won't be able grant permission for Connect to Mail.
- 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
Create a new Exchange mail service connection in DocuWare
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.
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.
- Open the DocuWare Configurations [https://your-DocuWare/DocuWare/Settings]
- Open the Mail Service plugin and select to create a new Exchange mail service
- Make sure the Authentication type is set to "Use OAuth2 Authentication"
- Fill all details that you've noted down while creating the new Azure Active Directory app registration.
- Don't forget to enter the exact same Redirect URI from the registration (eg. "https://my-company.com/DocuWare/Settings?link=MailCapture")
- It’s may required to change the Exchange Web Services URL.
- Store and save your configuration
- 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 to leave 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.
Once Microsoft denies 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.
Further reading [https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth#register-your-application]