IMAP Configuration for Email Based Workflow Approvals¶

Overview¶

This document describes the steps required to configure an enterprise application to authenticate to Microsoft 365 mailboxes using IMAP.

The application uses a Microsoft Entra ID (Azure AD) App Registration and OAuth 2.0 client credentials authentication to obtain an access token. The token is then used to authenticate to Exchange Online IMAP services.

Purpose¶

The IMAP integration enables the application to process approval decisions submitted by email.

When request email notifications are enabled, approvers receive email messages requesting approval or rejection of a request. The application monitors a designated Microsoft 365 mailbox folder for replies to these notification emails. When a reply is received, the application interprets the email content and records the corresponding approval decision or rejection comment.

Email-based approvals participate in the standard request approval workflow. Approval or rejection decisions submitted by email are processed in the same manner as decisions made through the application's user interface. Depending on the configured approval workflow, a request may require additional approvals from other approvers, or a single approval or rejection may complete the approval process.

This integration allows organizations to support approval workflows directly from email while maintaining a consistent approval process across both email and the application interface.

Prerequisites¶

The following prerequisites must be completed before configuring the application:

A Microsoft 365 tenant with Exchange Online mailboxes.
Administrative access to create and configure an application registration.
An application identity configured with either:
- A client secret, or
- A certificate credential.

Step 1: Creating the App Registration in Azure¶

Sign in to the Azure Portal.
Navigate to Applications > App registrations
Create a new application registration.
Record the following values:
- Application (client) ID
- Directory (tenant) ID

These values are required by the application during OAuth authentication.

Step 2: Configure Application Authentication¶

Next, From the Manage > Certificates & secrets page of your application, choose either Certificate (for Entra ID Assertion) or Client secret (for Entra ID oAuth) authentication:

Certificate: Upload your public key, enter a Description, and click Add. This public key and the corresponding private key and private key password will be required to complete the 12Port integration. When generating the Private Key use a strong, complex private key password (for example, 20+ characters with a mix of uppercase letters, lowercase letters, numbers, and special characters) to ensure the integration authenticates successfully.
Client secret: Click on New client secret, enter a Description and select an Expires option. Click Add to continue. After the secret is created, copy the value of the secret by selecting and copying the full string from the Value column. Securely save this Value string to a save location and please note that this value is only visible from this screen. Once you close this page, the value cannot be viewed again.

Step 3: Configure App Registration API Permissions¶

Add the required application permission:

API Permissions
    > Add a permission
    > Microsoft APIs
    > Microsoft Graph
    > Application permissions
    > Mail.ReadWrite

After adding the permission:

Grant administrator consent for the tenant.
Verify that the permission status shows as granted.

Step 4: Creating a new IMAP Configuration in 12Port¶

Log in to the 12Port tenant where you wish to support this IMAP configuration with an Administrator or Configuration Manager account.
Navigate to Integration > IMAP and click the Add button.
Populate each of the parameters using the in-application help for details or use the following section as guidance.
- Name: Enter a unique, but recognizable name for this IMAP connection.
- Server: Enter the IMAP host server. If you are using Azure/Office365, enter outlook.office365.com.
- Port: Enter your IMAP port. If you are using Azure/Office365, enter 993.
- Folder: This parameter defines the mailbox folder to read emails from. Typically, this is Inbox, but if you have a Outlook rule that automatically moves the 12Port request emails to a sub-folder like approvals, then enter this sub-folder's name in this parameter.
- Start TLS: Enable TLS if your IMAP server supports this protocol. If you are using Azure/Office365, enable this TLS option.
- Timeout: Enter a timeout value defined in milliseconds. We recommend using the default value unless you encounter timeout issues, in which case you can increase as needed.
- Authentication: Select between Basic Authentication, Entra ID oAuth, or Entra ID Assertion, the later two are available for an Azure/Office365 IMAP connection.
  1. Basic Authentication:
    - Account: Enter the username of the mailbox that will be used for receiving, reading, and submitting request emails.
    - Password: Enter the password of the account used to send emails.
  2. Entra ID oAuth: Please see the next section Creating an Azure App Registration for IMAP for additional configuration steps.
    - Account: Enter the username of the mailbox that will be used for receiving, reading, and submitting request emails.
    - Password: Enter the password of the account used to send emails.
    - Tenant ID: Enter the Azure Tenant ID from where your IMAP App Registration was created.
    - Client ID: Enter the Azure Client ID of your IMAP App Registration.
    - Client Secret: Enter the Value string from the Certificates & Secrets page that was created for this IMAP App Registration.
  3. Entra ID Assertion: Please see the next section Creating an Azure App Registration for IMAP for additional configuration steps.
    - Account: Enter the username of the mailbox that will be used for receiving, reading, and submitting request emails.
    - Tenant ID: Enter the Azure Tenant ID from where your IMAP App Registration was created.
    - Client ID: Enter the Azure Client ID of your IMAP App Registration.
    - Certificate: Enter your Public Key Certificate that was uploaded to the Azure App. The certificate must be entered as text content (PEM format), not the file itself.
    - Private Key: Enter your Private Key Certificate that corresponds to the Public Key Certificate. The certificate must be entered as text content (PEM format), not the file itself.
    - Private Key Password: Enter your Private Key Password. When generating the Private Key use a strong, complex private key password (for example, 20+ characters with a mix of uppercase letters, lowercase letters, numbers, and special characters) to ensure the integration authenticates successfully.
- Host Name Verification: An indicator to enforce host name verification when connecting to a IMAP server over a secure protocol.
- Enabled: Enable this option to enable this IMAP connection.

Click the Save button to complete the IMAP configuration.

After the integration has been configured and enabled, the application periodically checks the configured mailbox for new email messages. When a reply to a request notification is received, the application identifies the associated request and approver, interprets the approval decision or rejection comment contained in the email, and updates the request within the application's approval workflow.

Mailbox Considerations¶

The Mail.ReadWrite permission enables application-based authentication to Exchange Online. Organizations should review and restrict application mailbox access according to their security requirements.

To limit application access to specific mailboxes rather than allowing broad mailbox access, consult your Microsoft Exchange Online administrator for guidance on configuring appropriate Exchange Online application access controls and authorization policies.

Using Email Approvals¶

To more information about how to use Email based approvals, please see Approving or Rejecting Approvals via Email.