Configure your email channel for OAuth with Microsoft

This document shows you how to configure a CCAI Platform email channel to support Microsoft OAuth.

Prerequisites

  1. An Azure account with an active subscription. The account needs to have Microsoft Entra management access, so it must be configured as one of the following roles:

    • Application administrator
    • Application developer
    • Cloud application administrator

  2. A Microsoft Entra tenant. See the Microsoft quickstart guide for instructions about how to create a tenant.

Make sure the email account allows IMAP & SMTP

CCAI Platform uses IMAP and SMTP to send and receive email from Microsoft. Because a Microsoft account can be connected to different programs, it is important to ensure that IMAP or SMTP is not blocked by any other secondary programs. The following steps walk you through some common places to check in Microsoft.

  1. Go to Users > Active users in the left navigation panel.

  2. Select a user to verify.

  3. Click Mail. If you see "This user doesn't have an Exchange Online license", then you need to give the user a proper license to use Exchange. Without a proper license CCAI Platform won't be able to send or receive emails for this user account.

  4. After a proper license is added, select Manage email apps under the Mail tab. Ensure that IMAP and Authenticated SMTP are checked.

  5. Click Save.

  6. Go to Mailboxes on the left navigation panel.

  7. Select the user account you want to check.

  8. Under the General tab, select Manage email apps settings. Ensure that the IMAP toggle is enabled.

Register an application

  1. Sign in to the Microsoft Entra admin center. If you have multiple tenants, use the Directories + Subscriptions filter to switch to the correct tenant.

  2. Go to Identity > Applications > App registrations > New registration.

  3. Enter an identifiable display Name. Multiple app registrations can share the same name. The client ID is what the program uses to identify the app. However, because users of the program can see the name you've created, it might expedite registration to giving it a unique name.

  4. Specify the account type that can use the application, or sign-in audience. Several account types are supported:

    1. Accounts in this organizational directory only: Select this option if you're building an application for use only by users (or guests) in a single tenant. This is sometimes referred to as a line of business (LOB) application.

    2. Accounts in any organizational directory: Select this option if you want users in any tenant to be able to use this application. This option is preferable for multi-tenant configurations.

    3. Accounts in any organizational directory and personal Microsoft accounts: Select this option if you want users in any tenant to be able to use this application, as well as users who have personal Microsoft accounts.

    4. Personal Microsoft accounts: Select this option if you only want to create an application for users who have personal Microsoft accounts. Includes Microsoft, Skype, Xbox, Live, and Hotmail accounts.

  5. For Redirect URI, select Web and enter https://{tenant}.ccaiplatform.com/v1/email_accounts/oauth_callback. Replace {tenant}` with your CCAI Platform tenant name.

  6. Click Register to complete the initial app registration.

  7. After registration is complete, you will see the Overview screen. Note the following information, which you will need when you complete the process in CCAI Platform:

    • Application (client) ID
    • Directory (tenant) ID

Enable the application

  1. Sign in to the Microsoft Entra admin center.

  2. Go to Identity > Applications > Enterprise Applications and select the app.

  3. Go to Properties.

  4. Toggle Visible to users? to Yes.

Add application credentials

Create a client secret for use on the CCAI Platform platform.

  1. Sign in to the Microsoft Entra admin center.

  2. Go to Identity > Applications > App registrations and select the app.

  3. Go to Certificates & secrets > Client secrets > New client secret. This will open a panel for you to name the secret.

  4. Add a description for the client secret.

  5. Select an expiration date for the secret, or specify a custom lifetime. Client secret lifetime is limited to two years (24 months) or less, however Microsoft recommends setting an expiration value of less than 12 months.

  6. Click Add. Make a note of the secret's value. You will need it to complete the process in CCAI Platform.

Add API permissions

The Graph API enables access tokens to work with IMAP, required for the CCAI Platform email channel's operation.

  1. Sign in to the Microsoft Entra admin center.

  2. Go to Identity > Applications > App registrations and select the app.

  3. Select API permissions > Add a permission.

  4. Select Microsoft Graph.

  5. Select Delegated permissions. Use the Select permissions search bar to perform the following searches and check the boxes next to proper results:

    • IMAP: Check IMAP.AccessAsUser.All
    • offline: Check offline_access
    • openid: Check openid
    • smtp: SMTP.Send

  6. Click Add permissions.

Add credentials to CCAI Platform

After the Microsoft setup is complete, use the information from the setup process to complete the connection between the two programs in CCAI Platform. Go to Settings > Email Account Management > Email SO and enter the following information:

Access Type: leave empty.

Authorization URL: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize. {tenant_id} is the Directory (tenant) ID from the Microsoft app.

Token URL: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token. {tenant_id} is the Directory (tenant) ID from the Microsoft app.

Client ID: The Application (client) ID from the Microsoft app.

Client Secret: The Client Secret value from the Microsoft app.

Scope: Enter the following values. They don't need to be comma-separated but they must all be present.

  • openid offline_access
  • https://outlook.office.com/IMAP.AccessAsUser.All
  • https://outlook.office.com/SMTP.Send

State: leave empty.

Access Type: leave empty.

Grant Type: Authorization Code

Uncheck "Include the Grant Type as part of the Authorization URL and Token URL."

Check "Include the Redirect URL as part of the Authorization URL and Token URL."

Click Save.