Skip to Content

Microsoft Exchange Connection Guide

Overview

This guide describes the system requirements and instructions for connecting VinylTM to Microsoft Exchange as a Data Server. This connection makes use of the Client Credentials OAuth flow.

Client credentials refer to a flow in OAuth where there is no direct user authentication taking place. Instead, credentials are created for just the app itself. All tasks taken by the app are done without a default user context. This makes the authentication flow a bit different from the standard. All permissions related to the client Oauth flow require Administrator consent.

To connect your servers, you must have Vinyl 3.3+ installed.

System Requirements

  • Microsoft Exchange

  • Azure Portal

Client Web Browser

  • Chrome: 84+

  • Firefox: 73+

  • Safari: 13.0.1+

  • Edge: 84+

Limitations and Supported Features

  1. To use the Microsoft Exchange connector you must be running Vinyl Version 3.2.31151 released on 12/22/2022 3:15:01 PM (build 002ff986) or later.

  2. There may be limitations around the Microsoft Exchange primary key IDs with SQL Server database. The primary key is a long alphanumeric string and will cycle through a-z, 0-1, A-Z incrementally for new emails. The issue with this is that SQL Server is, by default, case insensitive so two emails with PKs "1234a" and "1234A" are the same to Vinyl. A workaround is to leverage the column changeKey, that in combination with id will always be unique.

Connection Instructions

Prerequisites to Configure in Azure Portal

Before configuring the Microsoft Exchange Data Server connection in Vinyl, you will need to first configure the following information from your Azure portal.

  • Create a custom OAuth App within the Azure Portal: https://cdn.cdata.com/help/CEH/ado/pg_oauthcustomappcreate.htm

  • On the app registration, select Access tokens (used for implicit flows) in the Authentication section.

    attachment

  • Navigate to Certificates & secrets and create a client secret value

    Note

    Be sure to copy the Client secret value and store it where you can access it* when configuring the Vinyl steps.

    attachment

  • Navigate to API permissions and select Microsoft Graph permissions. There are two distinct sets of permissions - Delegated and Application permissions. The permissions used during client credential authentication are under Application Permissions. Select the applicable permissions you require for your integration.

  • Configure the following API permissions, as well as grant admin consent to these permissions.

    attachment

Configure in Vinyl

Create an OAuth Security Provider

  1. Navigate to the Vinyl IDE

  2. Click the Security Providers button

  3. Click the + User Authentication button

  4. Assign the Name as something identifiable. For example: Microsoft Exchange Connector

  5. Set the Type to OAuth

  6. Set the Authentication Type to OAuth

  7. Set the OAuth Grant to Client Credentials

  8. Set the OAuth Client Authentication to Basic

  9. Set the OAuth Resource Authentication to Bearer

  10. Set the Token Owner to Client

  11. Click the + Endpoint button and create a record:

    • Type = Token Endpoint

    • URL = https://login.microsoftonline.com/{{ TenantID }}/oauth2/v2.0/token

    Note

    Replace the TenantID in the URL string provided accordingly

    attachment

  12. Click the + Credentials button and create a record using the Application (client) ID value created in Azure. This information is stored on the Azure application's Overview page:

    1. Set the Type to Client

    2. Provide the User Name. This is the Application (client) ID value found on the Azure application Overview page.

    3. Provide the Password. This is the Client Secret value created previously.

    4. Click the Save button

    attachment

  13. Click the + Property button and create a Scopes record:

    • Set the Parameter to Scopes

    • Set the Value to the default permissions value for Microsoft Graph

    attachment

  14. Check the Enabled field in Provider Settings to enable this as a security provider

Create the Microsoft Exchange Data Server

  1. Navigate to the Vinyl IDE

  2. Click the Data Servers button

  3. Click the + Server button

  4. Assign a Server Name. For example: Exchange Driver

  5. Set the Type to Microsoft Exchange

    attachment

  6. Click to expand the Security Settings

  7. Set the Security Provider to the Security Provider we created. For example: Microsoft Exchange Connector

  8. Click the Save button

  9. Click to expand the Server Settings

  10. Click the Advanced Settings button

  11. In the Advanced field, you need to specify a User from the Tenant to whom you wish to access Outlook resources. The format should be: UserID={{ UserEmail }}

    • If you have multiple Tenants configured, here you will need to specify which tenant as well. If not specified, your default Tenant will be used.

    attachment

In this section, we will link the Exchange Data Server source we created to our Vinyl app.

  1. From your Vinyl app, navigate to the App Workbench

  2. Click the Data Sources tile

  3. Click the + Source button

  4. Select Link to existing source

  5. Click Next

  6. Locate the Exchange Driver

  7. Check the Selected field

  8. Click the Link 1 Source button

  9. Click Done

  10. Click the Tables tile

  11. Select the Exchange Driver as the App Data Sources value

  12. Confirm you can now view all Tables associated with the Exchange Driver data source for the specified user

    attachment