Exchange

Establishing a Connection

Available Schemas

There are two services available for connecting to Exchange. These are EWS (Exchange Web Services) and the Microsoft Graph. Exchange Web Services is available for both Exchange OnPremise and Online, but is no longer receiving updates. Microsoft recommends switching to using the Microsoft Graph for Exchange Online users. Both are available with our tool.

To switch between the two, use the Schema connection property to set either EWS or MSGraph. If you wish to use EWS with Exchange Online, set Schema to EWS and the Platform to Exchange_Online.

Connecting to Exchange using Exchange OnPremise

When using an OnPremise edition of Exchange, OnPremise Set User, Password, and AuthScheme; by default, the provider performs Basic authentication, but Windows (NTLM), Kerberos, and delegated authentication are also supported.

Authenticating with Kerberos

Authenticating with Kerberos

To authenticate to Exchange using Kerberos, set the following properties:

• AuthScheme: Set this to NEGOTIATE

• KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.

• KerberosSPN: Set this to the service and host of the Exchange Kerberos Principal. This will be the value prior to the '@' symbol (for instance, ) of the (for instance, ).

Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.

1. Ensure that you have an environment variable created called KRB5CCNAME.

2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.

3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.

4. Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to Exchange.

As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to Exchange.

Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with Exchange.

Cross-Realm Authentication

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).

In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.

In addition to the authentication values, set the Server property to the address of the Exchange server you are connecting to and set Platform to the Exchange version. Finally, set Schema to EWS.

Connecting to Exchange using Exchange Online

When connecting to Exchange Online, authentication will be done via OAuth. If you are connecting to Exchange Online platform through EWS, set the AuthScheme property to OAuth. Otherwise if you will be using Microsoft Graph to connect to Exchange Online, resources will be pulled from a different service so the Schema should be set to MSGraph. When Schema is set to MSGraph, the Platform value will be ignored.

Follow the steps below to obtain the OAuth values for your app, the OAuthClientId and OAuthClientSecret.

1. Log in to https://portal.azure.com.

2. In the left-hand navigation pane, select Azure Active Directory then App Registrations and click the Add button.

3. Enter an app name and set the radio button for "Any Azure AD Directory - Multi Tenant". Then set the redirect url to something such as http://localhost:33333, the provider's default. Or, set a different port of your choice and set CallbackURL to the exact reply URL you defined.

4. After creating the app, go to the Certificates & Secrets section, create a Client Secret for the app and select a duration.

5. After you save the key, a value for the key is displayed once. Set OAuthClientSecret to the key value. Set OAuthClientId to the Application Id.

6. Select API Permissions and then click Add. If you plan for your app to connect without a user context, select the Application Permissions (OAuthGrantType = CLIENT). Otherwise, when selecting permissions, use the Delegated permissions.

7. If you are connecting to Exchange through EWS schema, select Exchange API and add EWS.AccessAsUser.All permission. If you are connecting to Exchange through MSGraph schema, select Microsoft Graph API and add the following permissions: Calendars.ReadWrite.Shared, Contacts.ReadWrite, Group.Read.All, Group.ReadWrite.All, User.ReadWrite.All, and Mail.ReadWrite.Shared.

8. Save your changes.

9. If you have selected to use permissions that require admin consent (such as the Application Permissions), you may grant them from the current tenant on the API Permissions page. Otherwise, follow the Admin consent steps below

10. Admin consent refers to when the Admin for an Azure Active Directory tenant grants permissions to an application which requires an admin to consent to the use case.

    When creating a new OAuth app in the Azure Portal, you must specify which permissions the app will require. Some permissions may be marked stating "Admin Consent Required". For example, all Groups permissions require Admin Consent. If your app requires admin consent, there are a couple of ways this can be done.

    The easiest way to grant admin consent is to just have an admin log into portal.azure.com and navigate to the app you have created in App Registrations. Under API Permissions, there will be a button for Grant Consent. You can consent here for your app to have permissions on the tenant it was created under.