Configuring OAuth authentication for Incoming Mail agent

You can configure OAuth 2.0 authentication for the Incoming Mail agent used by the TRIRIGA® application to connect to the configured mailbox for retrieving email messages with the offline forms. You must register an application in Microsoft Azure for OAuth and then configure TRIRIGA application for using the OAuth 2.0 authentication for Incoming Mail agent.

Note: Effective April 2020, Office 365 was renamed to Microsoft 365. Effective July-October 2023, Microsoft Azure AD was renamed to Microsoft Entra ID.

Contents

I. Registering OAuth authentication in Azure

You can use the OAuth 2.0 authentication service provided by Azure Active Directory (Azure AD) to enable TRIRIGA application to connect with IMAP, or POP protocols to access Exchange Online in Office 365. For more information, see Authenticate an IMAP, POP or SMTP connection using OAuth.

Procedure
  1. Launch the Microsoft Azure app registration screen from the following URL:
  2. Under Manage, select App registrations > New registration to begin the app registration process:
    • Name: Specify the name to identify the registration in the Microsoft Azure portal. For example, TririgaIncomingMailAgent.
    • Account Type: Select the single tenant account type.
    • Click Register. When registration finishes, the Azure portal displays the app registration's Overview pane. Make a note of the Application ID.
  3. Create a client secret by completeing the following steps:
    1. Click Certificates & secrets.
    2. Click New client secret.
    3. Provide a description and enter a value for the duration of when the client secret expires.
    4. Click Add.
    5. Copy the client secret value from the Value column. This value is later provided in the OAuth Application Secret field of the Microsoft OAuth profile record in TRIRIGA.
      Note: The client secret can only be viewed immediately after creation so ensure to make note of the value before leaving the page.
  4. Click Overview and then click the Endpoints tab. Copy the OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2).
  5. Configure API permissions by completing the following steps:
    1. Click API permissions.
    2. Click Add a permission.
    3. Select the APIs my organization uses tab and search for Office 365 Exchange Online.
    4. Click Application permissions.
    5. Select the following permissions:
      • POP.AccessAsApp
      • IMAP.AccessAsApp
    6. Click Add permissions.
    7. Click Grant admin consent for "application name" for providing consent.
      Note: You need admin access to view the option to grant admin consent.
    8. Click Yes.
  6. Register the Service principal in exchange via Exchange Online PowerShell by running the following PowerShell commands:
    1. Install the ExchangeOnlineManagement and connect to your tenant ID:
      
Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement 
Connect-ExchangeOnline -Organization <tenantId>
    2. Register an Azure AD application's service principal in Exchange:
      New-ServicePrincipal -AppId <APPLICATION_ID> -ServiceId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]

      Use the Client ID as Application Id, Object ID as the Service ID for the application, and the Tenant ID as the ORGANIZATION_ID. You can find these details in Overview tab of the Azure portal by navigating to Azure Active Directory > Enterprise applications and select the application that you have registered. For more information, see New-ServicePrincipal command

    3. Add Mailbox permissions to the application to give access to your mailbox:
      Add-MailboxPermission -Identity "<EXCHANGE_EMAIL_ID>" -User <OBJECT_ID> -AccessRights FullAccess

II. Configuring OAuth profile in TRIRIGA

After you register an OAuth application with Microsoft Azure, you must enter the OAuth provider (Microsoft Azure) in TRIRIGA. To enter the OAuth provider (and OAuth application), you must create a Microsoft OAuth profile record in TRIRIGA.

Procedure
  1. Log in to the TRIRIGA main portal.
  2. Navigate to Tools > System Setup > Integration > OAuth Settings.
  3. Select Add to add a new Microsoft OAuth profile record.
  4. In the OAuth Setup section, specify the following OAuth settings.
    • Name: This name may be displayed to end users, and used in API calls to identify the target record.
    • OAuth Provider: Name of the OAuth provider. For example, "Azure" for Microsoft Azure Active Directory. Name is not case-sensitive.
    • Access type: Set the access type as Application.
    • Description: Description that describes this profile, so an application may display it to end users.
    • OAuth Application Key: Enter the value of the Application (Client) ID field from the above OAuth application registration in Microsoft Azure.
    • OAuth Application Secret: Enter the value of the client secret Value column from the above OAuth application registration in Microsoft Azure.
    • OAuth Authorize URL: Enter the tenant-specific URL value of the OAuth 2.0 authorization endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by TRIRIGA Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/authorize.
      Note: To obtain the URL value, click Overview on the Azure App registrations page, and then click the Endpoints tab. Copy the value of the OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2) fields.
    • OAuth Token URL: Enter the tenant-specific URL value of the OAuth 2.0 token endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by TRIRIGA Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/token
    • OAuth Scope: API permissions that are granted to an OAuth application. For Microsoft Azure, enter: https://outlook.office365.com/.default
      Note: Users might need to approve these permissions when they login.
  5. Save your new Microsoft OAuth profile record.

III. Configure the IncomingMailConfig record

Configure the IncomingMailConfig record to use OAuth authentication to connect with IMAP and POP protocols and access email data for Office 365 users.

Procedure
  1. Navigate to Tools > System Setup > IncomingMailConfig > Add.
  2. Host: Specify the host as: outlook.office365.com
  3. INBOX: Specify the folder name as: INBOX.
  4. Action: Specify the action as CREATE.
  5. Username: Enter your Outlook Mailbox address.
  6. Password: Enter the Outlook password of the mailbox used by the Incoming Mail agent for offline forms for a particular topic.
  7. MailServerType: Enter the mail server type as imaps with port 993.
    Important: For POP3 protocol, specify the mail server type as POP3S and port as 995.
  8. OAuthProfile: Select the OAuthProfile created in II. Configuring OAuth profile in TRIRIGA section.
  9. Save the record.

IV. Next

Verify that the Incoming Mail agent is running. Log in to the Admin Console, navigate to the Agents panel, and ensure that the Incoming Mail agent is running.