Skip to main content
By default, users setting up document import from an email service using an Input activity in a Process skill only have access to basic IMAP server authentication. To enable Google and Microsoft email services authentication via the OAuth 2.0 protocol, you need to:
  1. Register applications on the Google Cloud Platform and/or the Azure portal.
  2. Generate account credentials for these applications (Client ID and Client secret).
  3. Pass the generated credentials to Consul.
These steps can be done both before and after installing Vantage.

​
Registering the Application in Google

Creating an application requires a Google account.

​
Creating a Project on the Google Cloud Platform

  1. Navigate to the Google Cloud Platform New Project page.
  2. Specify a name for your project and click Create.
Google Cloud Platform New Project page showing project name field
  1. Wait for a notification saying that your project has been created.
Google Cloud Platform notification showing project creation confirmation

​
Setting Up the Application

  1. Navigate to the Google Cloud Console and select the appropriate project.
Google Cloud Console project selector dropdown
  1. In the menu on the left side of the screen, select APIs & Services > OAuth consent screen.
Google Cloud Console menu showing APIs & Services with OAuth consent screen option
  1. Select the External user type and click Create.
  2. Specify a name for your application. In the User support email drop-down list field, select your Gmail address.
OAuth consent screen App information form with app name and user support email fields
  1. Specify the developer’s email in the Developer contact information section at the bottom of the page and click Save and continue.
Developer contact information section with email field
  1. Click Add or remove scopes. This will open the Update selected scopes dialog on the right.
  2. Copy and paste the following text into the Manually add scopes field in the bottom part of the dialog and click Add to table:
openid https://www.googleapis.com/auth2/userinfo.email https://www.googleapis.com/auth2/userinfo.profile https://mail.google.com/
You can also select scopes manually. The following scopes need to be selected:
  • openid
  • https://mail.google.com/
  • ../auth2/userinfo.email
  • ../auth2/userinfo.profile
  1. Click Update. This will close the Update selected scopes dialog and display the selected scopes.
Update selected scopes dialog showing the required OAuth scopes
  1. Click Save and continue at the bottom of the screen.
  2. Click Save and continue to skip the Test users page settings and navigate to the Summary page.
On the Summary page, you’ll see information about the application, email addresses, and permissions that have been set up.

​
Creating Account Credentials

  1. Select Credentials in the menu on the left side of the screen.
  2. Click + Create credentials and select OAuth client ID.
Create credentials dropdown menu showing OAuth client ID option
  1. Select the Web application type.
Create OAuth client ID form with Application type dropdown showing Web application
  1. In the Authorized redirect URIs section, select + Add URI.
Authorized redirect URIs section with Add URI button
  1. In the field that will appear, specify the redirect URI:
https://<Vantage host name>/connectors-tokens-callback.html
Redirect URI field with Vantage callback URL and CREATE button
  1. Click Create.
The pop-up dialog box that will appear will contain the Client ID and Client secret values. OAuth client created dialog showing Client ID and Client secret values This data is required for setting up the tokenmanagement service in Vantage. You can save it immediately or copy it later by navigating to APIs & Services > Credentials and selecting the OAuth 2.0 client identifier you created.

​
Publishing and Verification

The publishing status of the application is displayed in the APIs & Services > OAuth consent screen section. OAuth consent screen showing Publishing status as Testing with Publish App button Applications with the Testing status are only available to users that have been added to the testers list. Only publishing an application makes it available to any user with a Google account. Click Publish app. The https://mail.google.com/ scope allows the application to access confidential user data, which is why a message saying that the application needs to be verified will be displayed. To verify the application, you will need to provide:
  • An official link to the application’s Privacy policy
  • A YouTube video demonstrating the stated purpose of obtaining Google user data using the application
  • A text addressed to Google that contains a description of why you require access to confidential user data
  • A full list of all your domains verified in the Google Search Console
Click Confirm. The status of your application will change to In Production. The Prepare for verification button will also appear, letting you provide all required verification data. OAuth consent screen showing In Production status with verification warning and Prepare for Verification button
Before your application is verified, only 100 users will be able to use it. The user counter is located in the bottom part of the OAuth consent screen section and cannot be reset during the project’s lifetime.
OAuth user cap showing 0 users out of 100 user cap

​
Registering the Application in Microsoft Azure

To create an application, an Azure Active Directory tenant with application registration and editing permissions is required. You can switch to the correct directory on the Portal settings | Directories + subscriptions page.

​
Registering the Application

  1. Navigate to the App registrations page.
  2. Click New registration.
  3. Specify a name for your application and select the supported account types.
Azure Register an application form showing Name field and Supported account types options
If the Multitenant type is selected for the application, it will be available for users in any Azure AD tenant. Such applications need to be verified, which is only available for Microsoft Partner Network participants. If you are not a participant, select Single tenant, which will only make your app available to users in your own Azure AD tenant.
  1. In the Redirect URI section, select the Web platform and specify the redirect URI:
https://<Vantage host name>/connectors-tokens-callback.html
Azure Redirect URI section with Web platform selected
  1. Click Register.

​
Setting Up Application Permissions

  1. Navigate to the API permissions tab.
Azure portal sidebar showing API permissions menu option highlighted
  1. Click Add permission.
  2. In the dialog that will open, select the Microsoft Graph section.
Request API permissions dialog showing Microsoft Graph option highlighted
  1. Select Delegated permissions.
Microsoft Graph permissions dialog showing Delegated permissions option selected
  1. Add the following permissions:
    • email
    • IMAP.AccessAsUser.All
    • offline_access
    • openid
    • profile
  2. Click Add permissions. This will close the dialog and display the selected permissions.

​
Creating Client Secrets

  1. Navigate to the Authentication tab.
Azure portal sidebar showing Authentication menu option highlighted
  1. In the Implicit grant and hybrid flows section, mark ID tokens (used for implicit and hybrid flows).
Implicit grant and hybrid flows section with ID tokens checkbox
  1. Click Save at the top of the screen.
  2. Navigate to the Certificates & secrets tab and click New client secret.
Certificates & secrets tab showing New client secret button
  1. In the dialog box that will open, specify a name for the client secret and an expiration date.
The maximum expiration date is 24 months.
  1. Click Add. This will close the dialog and display information about your new client secret.
It is important that you copy and save the Value, since you will not be able to access it again once you close the page. This value is required when configuring the tokenmanagement service in Vantage.
Client secrets list showing the secret Value column highlighted You will also need a client identifier, which can be copied from the Application (client) ID field in the Overview tab. The copy icon will appear once you hover the mouse cursor over the value of the identifier. Azure application Overview showing Application (client) ID field highlighted

​
Verifying the Application

To make the application available to users from any Azure AD tenant, verification is required. Verification is not required if accounts from a single Azure AD tenant are used. Only Microsoft Partner Network participants can undergo verification.
  1. Navigate to the Branding & properties tab.
Azure portal sidebar showing Branding & properties menu option highlighted
  1. Verify that the domain is specified in the Publisher domain field. If required, configure your domain by clicking Configure a domain.
Azure Branding & properties page showing Publisher domain field with Update domain option
The warning icon displayed next to the domain name means that an application with the specified domain cannot be verified. Click Update domain to specify a different valid domain related to the Azure Active Directory tenant. Alternatively, verify a new domain.
  1. In the Publisher verification section, specify your MPN ID and click Verify and save.
If you do not have the required permissions to add an MPN ID, verify that all publisher verification requirements are satisfied.
Once your verification is successful, the appropriate icon will be displayed next to the Publisher display name field.

​
Passing Credentials to Consul

If Vantage is already installed, you need to use Consul to manually enter account credentials generated for Microsoft and/or Google email service authentication. Features specific to the OAuth 2.0 protocol are listed in the TokenManagement service.
Before setting up, verify that the kubectl command line tool is installed and that you are connected to the Kubernetes cluster.
  1. Get access to the Consul web interface by running the following command:
kubectl port-forward -n abbyy-infrastructure service/consul-ui 8500:80
Then navigate to http://localhost:8500/ui/dc1/kv/secret/.
  1. In the Key/Value tab that will open, select the appropriate Vantage deployment scope. Then, select the vantage project.
Consul vantage project showing list of services with tokenmanagement highlighted
  1. Select the tokenmanagement service.
Consul tokenmanagement service showing oAuthClientConfiguration section
  1. Navigate to the oAuthClientConfiguration section.
Consul oAuthClientConfiguration showing google and microsoft options
  1. Select the service for which you want to specify user data (google or microsoft).
Consul oAuthClientConfiguration section showing google service with clientId and clientSecret keys
  1. Select the clientId key.
  2. Copy and paste the Client ID value you saved earlier to the entry field and click Save.
Consul clientId value editor with Save button
  1. Repeat steps 6 and 7 for the clientSecret key.
If required, repeat steps 5 through 8 for a different email service.
  1. Restart the tokenmanagement service by running the following command:
kubectl -n abbyy-vantage rollout restart $(kubectl -n abbyy-vantage get deployments -l app.kubernetes.io/component=tokenmanagement -o name)

​
Updating Client Secret

The Client secret value is used for server-side client identification and constitutes confidential information. For security purposes, this data should periodically be updated. Some services like Azure Active Directory limit the validity period for such data. Once a new Client secret has been created, the value of the corresponding Consul key should also be updated.
Once the Client secret is updated, users will need to set up connections to their email service in the Input activity of the Document skill from scratch. Otherwise, Vantage will not be able to connect to the mailbox and import emails from it.

​
Updating the Client Secret in Google

  1. Navigate to the Google Cloud Console and select the appropriate project.
  2. In the menu on the left, select APIs & Services > Credentials.
  3. In the OAuth 2.0 Client IDs section, select the identifier used to authenticate when connecting to the IMAP server.
  4. Click Reset secret.
Google Cloud OAuth client details showing Reset Secret button
  1. Click Reset in the pop-up dialog box. This will update the Client secret value and recall its previous value.
  2. Download the JSON file containing the credentials. Alternatively, copy the Client secret value from the right side of the screen.
Google Cloud OAuth client details showing Download JSON button and Client secret field

​
Updating the Client Secret in Microsoft Azure

  1. Navigate to the App registrations page and select the application used for authentication using the IMAP server.
Azure App registrations page showing Owned applications list with Example App
  1. Navigate to the Certificates & secrets tab and click New client secret.
  2. In the dialog box that will open, specify a name for the client secret and its expiration date.
  3. Click Add. This will close the dialog and display information about the new client secret. It is important that you copy and save the Value, since you will not be able to access it again once you close the page.
  4. If the current client secret has not expired yet, you can delete it in order to only be able to use the new client secret to identify the client.

​
Updating the Client Secret in Consul

Follow the steps listed in Passing Credentials to Consul, omitting steps 6 and 7 (copying the clientId value).