Introduction
This article will walk through how to connect FME to Microsoft Exchange Online using OAuth 2.0, also known by Microsoft as "Modern Authentication", for sending and receiving email. Microsoft blocked basic authentication for the IMAP and SMTP protocols in January, 2023. For more information, please see Microsoft's blog post Basic Authentication Deprecation in Exchange Online.
For sending email, FME supports the SMTP email protocol via the Emailer transformer, the Automation External Email Action, and the legacy Notification Service Email Subscriber.
For monitoring incoming emails, FME Flow supports the IMAP email protocol in the Automation IMAP Email Trigger and the legacy Notification Service Email Publisher.
Prerequisites
- FME 2022.2+
- Access to your Microsoft Azure Portal and permissions to create an app registration
- For sending email only: SMTP AUTH for the organization and SMTP AUTH for the specific mailboxes should be enabled via Exchange Admin Center and via the Microsoft 365 Admin Center, respectively. The SMTP AUTH protocol is used for SMTP client email submissions.
Step-by-Step Instructions
Part 1: Emailer Transformer in FME Form (SMTP)
1. Create an Azure app registration
Create an Azure app registration as per Microsoft's documentation.
The app registration Overview will contain information you need to configure the web service later in FME. The screenshots in this article use a multitenant app registration as an example.
2. Configure the Azure app registration for FME Form
After creating the app registration, add a platform for 'Mobile and desktop applications'
When adding the platform, use Microsoft's default redirect URI for desktop applications: https://login.microsoftonline.com/common/oauth2/nativeclient. This must match the web service in FME Form, which will be created in the next step. If you registered a single tenant app, then the redirect URI will be https://login.microsoftonline.com/<TenantID>/oauth2/nativeclient
In API Permissions, add the following Microsoft Graph Delegated Permissions (Please see Microsoft's documentation for assistance):
- offline_access
- User.Read
- Mail.Send
3. Create the web service in FME Form
The Emailer transformer comes with a Microsoft Mail (safe.emailer) web service template. If you haven't already installed the Emailer package from the FME Hub, you can do so by adding the Emailer to the FME Workbench canvas or by downloading it from the FME Hub.
Create a new web service from the template by going to Tools > FME Options > Web Connections > Manage Services… (FME Workbench > Preferences > Web Connections > Manage Services... in MacOS). On the Manage Web Services windows, click [+] > Create From > Microsoft Mail (safe.emailer)
In the new web service, enter:
- Web Service Name: It's recommended to include the name of your Azure app registration for reference.
- Client ID: the Client ID from your Azure app registration (Found on the Overview of your app registration).
- Optional: check this off. Ensure nothing is entered into the client secret. The client secret is only for FME Flow. Using a client secret in FME Form will return errors from Microsoft Azure.
- Redirect URI: leave as https://login.microsoftonline.com/common/oauth2/nativeclient to match the Azure app registration.
- For Single Tenant Azure app registrations: replace the word "common" with your Tenant ID found on the app registration Overview in the Redirect URI, Parameters URL, Retrieve Token Parameters URL, and Refresh Token Parameters URL.
- Refresh Token Parameters URL: confirm the URL doesn't contain the hardcoded parameter and value "&redirect_uri=http://localhost/". Alternatively, you can add http://localhost to your app registration's desktop redirect URI list.
Click Test to test the web service connection and then Apply.
4. Create the web connection in FME Form
Return to the Web Connections window (Tools > FME Options > Web Connections > Manage Services… (FME Workbench > Preferences > Web Connections > Manage Services... in MacOS). Click the plus ("+") to add a web connection. Choose the web service you created and give the connection a name. Click OK. When prompted, enter your Microsoft credentials to authorize the connection.
5. Use the web connection in the Emailer
Your new Microsoft Mail web connection is ready to use in the Emailer transformer. The rest of the configuration should be the same as basic authentication.
If you encounter errors, please see Part 4: Troubleshooting
Part 2: Emailer Transformer in FME Flow (SMTP)
To use the Emailer Transformer with Microsoft as the email service on FME Flow, follow the steps below.
1. Complete the steps in Part 1: Emailer Transformer in FME Form (SMTP)
2. Add the FME Flow redirect URI to the Azure app registration
In your Microsoft Azure app registration, add a second platform for Web (Authentication > Add a platform) and enter the Redirect URI in the following format:
HTTPS://<Your FME Flow URL>/fmeoauth
3. Create a client secret
A client secret is required to use the emailer on FME Flow. In the app registration, click Certificates & Secrets > + New client secret. Important: you can only see the client secret value immediately after creation. It will then be hidden. Make sure to store the client secret value in a secure place, like a secrets vault, immediately after creation. Client secrets expire. Set a reminder before the expiry date so that you can generate a new client secret and update the web service in FME Flow. Workspaces using this web service will stop working after the expiry.
See Microsoft's documentation for more information about client secrets.
4. Publish to FME Flow
Publish a workspace using the Emailer and Microsoft Mail web connection to FME Flow. Alternatively, upload the web connection from FME Form by going to Tools > FME Options > Web Connections > (right-click) Upload.
5. Edit the web service in FME Flow
In FME Flow, go to Connections & Parameters > Web Connections > Manage Web Services. Click on the web service name that you created in Part 1. Make sure that the Client Id matches the Azure app registration created in Part 1. Add the Client Secret and Redirect URI that were added to the Azure app registration earlier in this part. Click Save.
6. Authorize the web connection
Go to Connections & Parameters > Web Connections and click on the web connection name. Click Authorize. Enter your Microsoft credentials. Once authorized, the web connection will have a green check mark.
7. Test the web connection
Run a workspace with an Emailer transformer that uses the Microsoft Mail web connection.
If you encounter errors, please see Part 4: Troubleshooting
Part 3: FME Flow Automations
Email sent to a Microsoft Exchange Online inbox can trigger an Automation (IMAP). Email can also be sent from an Automation Email external action using Microsoft Exchange Online (SMTP). Before proceeding, please note:
- The Microsoft account must have multifactor authentication (MFA) disabled. If this is an issue, please use the Emailer transformer instead.
- Unlike the emailer, the trigger and action do not use a web service, but they still require that a Microsoft Azure app registration be created.
- A client secret is not required.
1. Create an Azure app registration
See Part 1: Emailer Transformer in FME Form (SMTP) or Microsoft's documentation for reference, if needed. You can use the same App Registration if you have already created one for the Emailer transformer.
2. Add permissions to the app registration
In API Permissions, add the following Microsoft Graph Delegated Permissions (Please see Microsoft's documentation for assistance):
- IMAP.AccessAsUser.All
- SMTP.Send
Grant admin consent after adding the permissions. This enables FME Flow to perform operations on behalf of the logged-in user.
3. Allow public client flows
In Authentication, allow the app registration to function as a public client by allowing public client flows.
4. Configure the Automation
When using the “Email - IMAP” (received) trigger or “Email” (send) external action, you'll see an additional field for Client ID. This is the Client ID from your Azure app registration created in step 1. The rest of the configuration should be the same as basic authentication with an email address and password. As mentioned earlier, you do not need to provide a client secret.
Note: this step is the same if using the legacy Notification Service SMTP Email Subscriber for sending email or the IMAP Email Publisher for receiving email.
Part 4: Troubleshooting
Inspect the Microsoft Entra Sign-In logs for login attempts made by FME to the Azure Entra tenant. In addition, please see the troubleshooting guides below:
Comments
0 comments
Please sign in to leave a comment.