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 to use the new authentication
DocuWare Cloud delivers already 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.
If you want to connect to Office 365 with your self created app, follow the steps below like for on-premises customers
Please follow the instructions on Microsofts 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 OnPremises 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
Allow access of Connect to Mail to Exchange Web Services APIs
Before heading over to DocuWare we must classify Exchange Web Services APIs as low impact.
This step is required regardless of using the official DocuWare Cloud OAuth app, or if you're using your self registred Azure App.
- From the Azure Active Directory open the blade "Enterprise applications"
- Now move to "Consent and permissions" [https://portal.azure.com/?l=en.en-us#blade/Microsoft_AAD_IAM/ConsentPoliciesMenuBlade/UserSettings]
- In the submenu "User consent settings (Preview)" select "Allow user consent for apps from verified publishers, for selected permissions (Recommended)"
- Click now on permissions classifed as low impact and the Exchange Web Services APIs. It should look like this:
- Don't forget to save your changes. Now you're users able to grant access to this app. Proceed with the next steps
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 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]