Obtaining connection values for Microsoft Exchange

About this task

This topic provides instructions for obtaining the connection values for the Microsoft Exchange connector.

To generate these values and connect to Microsoft Exchange, you need to register an application with the required permissions in Microsoft Azure, which will enable App Connect to integrate with Microsoft Exchange by using APIs and protocols.

Note: These instructions assume that you are registering an application in Microsoft Azure for the first time.

Procedure

  1. To register an application with Microsoft Azure, for use with App Connect:
    1. Log in to the Microsoft Azure portal, and then locate and click App registrations.
    2. If you have access to more than one tenant, switch to the tenant where you want to register the app by using the Directories + subscriptions filter in the banner and then click the Close icon (X) to return to the previous page.
    3. In the App registrations page, click New registration.
    4. In the Register an application page, specify a unique name for your app, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) as the account type, and accept the default values for the remaining fields.
      Figure 1. Microsoft Azure registering an application window
      The image is described in the preceding text.
    5. Click Register. The Overview page for the application is displayed.
      The overview page for the registered application is described in the surrounding text.
    6. Make a note of the Application (client) ID value because you need to specify it as a connection value when creating the account in App Connect.
  2. To generate a client secret for your registered application:
    1. Next to Client credentials on the Overview page, click Add a certificate or secret. This displays the Certificates & secrets page.
    2. Click New client secret
    3. In the Add a client secret panel, specify a description for the secret (for example, App Connect secret) and then select an expiry period.
    4. Click Add. The generated client secret is displayed on the Certificates & secrets page.
      The image shows the generated client secret for the registered app.
    5. Copy and store the client secret value because you need to specify it as a connection value when creating the account in App Connect.
      Note: The client secret value won't be shown again in full after you leave this page.
  3. Configure the permissions that App Connect needs.
    1. In the left pane, click API permissions and then click Add a permission > Microsoft Graph > Delegated permissions to add each of the following permissions in turn. You can search for and select a permission, and then click Add permissions.
      Permissions Description
      Calendars.ReadWrite Have full access to user calendars
      Contacts.ReadWrite Have full access to user contacts
      Mail.ReadWrite Read and write access to user mail
      Mail.Send Send mail as a user
      offline_access Maintain access to data that you have given it access to
      User.Read Sign in and read the user profile
      Note: Group.ReadWrite.All requires admin consent.
    2. If the status of any permission is shown as Not granted for myDomain, click Grant admin consent for myDomain, where myDomain is your domain name. Then click Yes to confirm. (This updates the status of all permissions to Granted for myDomain.)
      The image shows the required permissions for the registered app.
  4. If you want to connect by using BASIC OAUTH authorization, use an application to submit a POST request to generate an access token and a refresh token that will be used to interact with Microsoft Exchange on your behalf. Before you can request an access token, you must authorize your application.

    To authorize the application, complete the following steps:

    1. Open a browser window, and then go to the authorization endpoint by using a URL in the following format:
      Request URL:
      GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=xxxxxxxxxxxxxxx&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2myapps%2F&response_mode=query&scope=offline_access%20user.read%20mail.read&state=12345  HTTP/1.1
      Request parameters:
      Key Value
      client_id Set this to the Application (client) ID value that was generated for your registered app.
      response_type Set this to code to indicate that the app is using the OAuth 2.0 authorization code flow.
      redirect_uri Set this to the redirect URI registered for your application. This value must exactly match one of the registered redirect URIs and must be URL encoded. For native and mobile apps, use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient.
      scope A list of Microsoft Graph permissions, separated by spaces, that the user must consent to. For example, Calendars.ReadWrite Contacts.ReadWrite Mail.ReadWrite Mail.send offline_access User.Read
      response_mode Set this to specify how the authorization response is returned to the application. Valid values are query or form_post.
      state Set this to a unique value to maintain request state and help protect against cross‑site request forgery (CSRF) attacks.
    2. Enter your Microsoft account credentials, and then click Sign in.
    3. Review the permissions in the Permissions requested pop-up window and click Accept.
      The browser is redirected to the configured redirect URI. For example:
      HTTP/1.1 200 OK

https://localhost/myapp/?code=M0abs92efe-b6fd-df08-87dc-2c6500sa7f84d&state=12345&session_state=fe154s0c3-a69a-469a-9fa3-8a2470936421#
    4. Copy and save the value of the code query parameter in the redirected URL.
  5. To generate an access token and a refresh token, submit a POST request to the token endpoint by specifying the following parameters:
    • Token endpoint URL: 
      https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
    • Content-Type: application/x-www-form-urlencoded
    • Request parameters:
      Key Value
      client_id Set this to the Application (client) ID value that was generated for your registered app.
      scope A space-separated list of scopes. For example, Calendars.ReadWrite Contacts.ReadWrite Mail.ReadWrite Mail.send offline_access User.Read
      grant_type Set this to authorization_code
      client_secret Set this to the client secret value that was generated under Certificates & secrets for your registered app.
      code Set this to the code that you acquired in step 4.
      redirect_uri Set this to the same redirect URI used in step 4.

    • Example using Postman (Postman Version 7.29.1 was used in these instructions, so there might be a slight variation in the fields that you see if your version is different)

      1. Start a new POST request and specify the token endpoint URL.
      2. Click the Body tab and select x-www-form-urlencoded. This option automatically adds the Content-Type: application/x-www-form-urlencoded setting in the request header.
      3. Specify the request parameters.
      4. Click Send.
        An access token and refresh token are returned in the response. Make a note of these values because you need to specify them as connection values when creating the account.
        Note: The generated access token is valid for 1hour, and the refresh token will expire after 90 days of inactivity. So, it is expected that you need to generate new tokens only if the refresh token has been revoked or has not been used in 90 days.