Microsoft 365 IMAP Client Credentials with 360Works Email

This Microsoft documentation covers much of what will be covered here, if you want more context for any of this guide, review this page or email us at support@360works.com.

This documentation directs users on how to leverage the client credentials grant flow with 360Works Email. This involves:

• Creating and configuring a new App in the Azure portal.
• Using the Exchange Admin Center to configure your mailbox to work with IMAP.
• Using PowerShell to further configure your app, including creating security groups, assigning mailbox permissions, and setting application access policies.
• Implementing 360Works Email FM plugin functions into your FM scripts

Why use a client credentials auth setup?

Most modern email authentication centers around user-based authentication using the OAuth 2.0 Authorization Code Flow. In this setup, a user is prompted to log into the relevant service in a web browser. After successful authentication and consent, an access token (and usually a refresh token) is generated and stored for later use.

In a Client Credentials grant flow, no user is involved at all. Instead, the application authenticates as itself using its Application (client) ID and Client Secret. The resulting access token represents the application’s identity rather than a human user. This model is ideal for background services, scheduled jobs, integrations, and other “headless” systems that need to access a specific mailbox without interactive sign-in.

Assumptions before starting

• You have administrative access to Microsoft Entra ID (Azure AD) and the Exchange Online tenant.
• You have a dedicated admin/setup account (preferably not the mailbox user account) for performing high-privilege operations.
• You have access to a system where you can run PowerShell (Windows, macOS, or Linux) and install the Exchange Online Management module.
• The target mailbox already exists and is licensed for Exchange Online (or something that includes Exchange Online)
• IMAP is supported in your tenant (some policies or tenants may disable IMAP by default).
• You have familiarity with basic PowerShell cmdlets, including New-DistributionGroup, Add-DistributionGroupMember, New-ApplicationAccessPolicy, and Add-MailboxPermission.
  • This guide provides commands, but troubleshooting may require some knowledge of this.
• You have access to the 360Works Email plugin and the relevant FileMaker scripts for connecting with the OAuth token.

Guide

1. Create a new App Registration in the Azure Portal

• Microsoft Entra ID → App registrations → New registration
• Select single tenant
• No redirect URI required
• Record these values before proceeding:
  • Application (client) ID (should be visible immediately after creation)
  • Directory (tenant) ID (should be visible immediately after creation)
  • Enterprise Application Object ID (Azure Console → Enterprise Applications → Manage → All Applications → Look for the Object ID)
    • This is not the same Object ID that's visible in the app overview

2. Create a Client Secret

• Go to your Registered Apps, and click "All Applications"
• Click your app → Manage → Certificates & secrets → New client secret
• Record the secret VALUE immediately (not the secret ID) in a secure location

3. Add Required API Permissions

• Go to your Registered Apps, and click "All Applications"
• Click your app → Manage → API permissions → Add a permission → APIs my organization uses → Office 365 Exchange Online → Application Permissions
• Add the following Application permission:
  • IMAP.AccessAsApp
• Click Grant admin consent

4. Enable IMAP on the Target Mailbox

• Exchange Admin Center → Recipients → Mailboxes
• Select mailbox → General tab → Email apps & mobile devices → Manage email apps settings
• Toggle IMAP ON

5. (If not already done) Install PowerShell Utilities and Connect to Your Tenant

• Perform this using a dedicated admin/setup account rather than the mailbox account you will be granting access to
• Install Exchange Online Management Module:
  • Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser
• Connect to Exchange Online:
  • Connect-ExchangeOnline -UserPrincipalName "Admin'sEmailAddress"
• You can now run cmdlets such as New-DistributionGroup, Add-DistributionGroupMember, New-ApplicationAccessPolicy, and Add-MailboxPermission

6. Ensure the Admin Account Has Sufficient Privileges

The setup steps in this guide require an admin account with the Global Administrator role (or a combination of less permissive roles to allow the following actions). If you receive permissions errors in the following steps, your user will need its permissions to be expanded.

Warning:

Do not grant any more permissions to the application itself; this is only required for the admin account performing the setup.

7. Create a Mail-Enabled Security Group (For Access Policy Scoping)

• New-DistributionGroup -Name "IMAP-App-Access" -Type Security

8. Add the Target Mailbox to the Security Group

• Add-DistributionGroupMember -Identity "IMAP-App-Access" -Member <TARGETMAILBOX@YOURDOMAIN.com>

9. Create the Application Access Policy (Restricts Mailbox Scope)

New-ApplicationAccessPolicy `
  -AppId <YOUR-APP-CLIENT-ID> `
  -PolicyScopeGroupId "IMAP-App-Access" `
  -AccessRight RestrictAccess `
  -Description "Restrict IMAP app access to approved mailboxes"

10. Create the Service Principal for the App

• New-ServicePrincipal -AppId <YOUR-APP-CLIENT-ID> -ObjectId <YOUR-APPLICATION'S-ENTERPRISE-APPLICATION-OBJECT-ID>

11. Retrieve the Service Principal Object ID

• Get-ServicePrincipal | Where-Object { $_.AppId -eq "<YOUR-APP-CLIENT-ID>" } | Select Id, AppId, DisplayName
• Use the Id value from this output for the next step

12. Grant Mailbox Access to the Service Principal

Add-MailboxPermission `
  -Identity "<TARGETMAILBOX@YOURDOMAIN.com>" `
  -User "<SERVICE-PRINCIPAL-ID-FROM-STEP-11>" `
  -AccessRights FullAccess

13. Implement Client Credentials flow in your FileMaker script

Tip:

There's an example of a simple FileMaker integration in the "Office365 IMAP - Fetch Client Credentials Token And Connect" script in the "360Works Email Plugin Examples.fmp12" file that's provided with every download of 360Works Email; review that to see basic usage of the functions that 360Works Email exposes to work with this style of auth. There's also an Office 365 UI in that same file (Click "Demo Examples">"Office 365") to allow you to test basic connectivity/function with client credentials.

• Store the clientId, clientSecret, and tenantId somewhere secure in your FM database (or somewhere where they can be securely accessed by the database's scripts)
• Use the EmailOffice365AuthorizeClientCredentials ( clientId ; clientSecret ; tenantId ) calculation function to fetch the token store and store it in a variable or a field.
• Pass the token store that was just fetched to the EmailOffice365ConnectIMAP function to establish a connection.
• Use IMAP-compatible (generally, non-sending) 360Works Email functions as desired.
• Check the output of 360Works Email functions; if they output "ERROR", it means that something went wrong, and you can fetch an error from the plugin. Use the EmailLastError function to fetch the text of the error, and when your script encounters an error that the token has expired or that the connection was reset, run a script that completes the above two steps again before retrying. By default, these access tokens last one hour minimum, so depending on your use case you may never expect them to expire before the next time you authenticate.