Question:
How do I use Modern Authentication or OAuth with Connect to Mail and a Google accounts?
Solution:
To use Connect to Mail with Google Accounts via OAuth, you need a Google OAuth 2.0 Client ID for each folder you want to read with Connect to Mail; this Client ID also contains the respective Client Secret. We will guide you through the necessary steps with these KBA:
1. First, please go to https://console.cloud.google.com/apis
2. Create a project there for OAuth in connection with DocuWare.
3.As soon as the project is created, click on "Enable APIs and Services", select the Gmail API and enable it.
⇓
⇓
4. Switch to the “OAuth consent screen” and create an OAuth consent screen of the External user type and click on Create.
5. In the next configuration screen, you can enter the app information. In our case, you can leave most of the information blank here, as nobody will be using this app apart from you.
Important: At the end of the app information page, Google asks for the e-mail address of the developer contact. This does not refer to DocuWare as the developer of Connect to Mail, but to the creator of this app, i.e. you. So please enter your e-mail address here, also because the recipient of this address will be informed if there are problems with the project you have created and this Google OAuth app. Click on Save and Continue.
6. On the second page, “Scopes,” click “Add or remote scopes” and select “openid” and the “Gmail API” with the following permissions: Read, compose, send and permanently delete all your email from Gmail.
This is the result when you click Update:
7. In the Test Users tab, please add all the email addresses that you want to query with this OAuth app. Click on Save and Continue.
Back in the overview, Google gives you the option to publish the OAuth Consent screen app. We do not recommend this step, as Google then wants to review the app. Since this is only a connection to a mailbox that is to be established to retrieve e-mails, and no API for other activities within the mailbox is used, we consider this step to be too time-consuming. We recommend using the app in “Testing” status.
8. Now go to “Credentials” and click on Create Credentials. Select OAuth Client ID from the list.
9. Application type for the OAuth Client ID is “Web Application”. Now select a meaningful name (we recommend a combination of the e-mail address and the folder to be connected, e.g. Invoices-South-West-Inbox) and add the Redirect URI.
Important: The Redirect URI is, as with Microsoft OAuth, your DocuWare Cloud URL + the addition "/DocuWare/Settings?link=MailCapture".
Like this: https://your-dw-cloud-name.docuware.cloud/DocuWare/Settings?link=MailCapture
10. Finally, note the Client ID, the Client Secret and the Redirect URI for the configuration within DocuWare. The Redirect URI must be written identically in Google and DocuWare, otherwise a mismatch error will occur. We recommend downloading the JSON file. You can store this in the DocuWare configuration and all settings from Google are then automatically transferred to the DocuWare configuration.
11. Go to the DocuWare configuration page and select “Mail services”, click on “New Mail service” and select IMAP. Name the new mail service as the OAuth Client ID was named in Step 9. above, so that you will always know which mail service belongs to which Google Client ID.
12. In the new window, click on “More options” and select “Use IMAP OAuth Authentication". Make sure that Google and not Other is selected there.
13. You can now upload the JSON file from Google and the configuration is complete. You can also upload the data manually, but we do not recommend this as it usually leads to more errors.
If you do want to configure the service manually, you will need these values in addition to the values noted in step 10:
Application (client) ID | noted in step 10 |
Client Secret Key | noted in step 10 |
OAuth 2.0 authorization endpoint | |
OAuth 2.0 token endpoint | |
Redirect URI | https://your-dw-cloud-name.docuware.cloud/DocuWare/Settings?link=MailCapture |
Scope | |
Host | imap.gmail.com |
Port | 993 |
14. Now connect your Google Mailbox with Connect to Mail. To do this, open “General Email” on the DocuWare configuration page. Select or create a new storage configuration and then click on “Connect to email account”.
15. In the new window, you must now log in to the Google account once. It is possible that Google will display a security message like this:
This message appears because of the entries made in Step 5. Ignore this message and click on Continue.
16. In the next window you have to give DocuWare the rights to access the mailbox. Click on Continue.
If you can now see your Google Labels in the DocuWare Connect to Mail Configuration, the configuration is complete.
Important notice:
Unfortunately, Google does not allow you to use a set of Client ID + Client Secret to log in to your mailbox multiple times to monitor different folders. To do this, you have to switch to your DocuWare project on the Google API page and create new OAuth 2.0 Client ID Credentials under Credentials. To avoid confusion, we recommend, as mentioned in Step 9, that you name these IDs after the folders you want to connect in DocuWare.
Then create a new mail service in DocuWare, preferably also with the folder name, and upload the new JSON file there.
More information about OAuth:
https://knowledgecenter.docuware.com/docs/mail-services?highlight=oauth
https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow
https://developers.google.com/workspace/guides/configure-oauth-consent
