How to Set Up Microsoft 365 As A Message Source Connection
Introduction
This document explains how to connect your Microsoft 365 email system to Y Meadows, so that Y Meadows can act on incoming email messages.
The connection communicates with the email system using Microsoft Graph API. The connection may also be used for steps that interact with other Microsoft products that also use Microsoft Graph API.
Microsoft 365 was formerly known as Office 365. The typical email client used is Microsoft Outlook. So, this is often referred to as the Outlook, MS365, or O365 connection.
This connection will not work for email that is not accessible via Microsoft Graph API. For example, certain Microsoft Exchange based systems cannot connect using this method.
Connection Options
There are 2 ways Y Meadows can connect to Microsoft 365:
Delegated Permissions
Application Permissions
Delegated Permissions has Y Meadows act as a single user. We only have access to what that user has access to. Essentially that user has delegated control to us. This has security benefits - we can only see some mailboxes and not others.
Setting this up requires that someone is able to log into Y Meadows and then authenticate (log in) to O365 using the delegated user’s credentials. This may be an issue if you use a special “Y Meadows” user and the SSO setup that makes it hard to login as a service account user (or any other user that would not normally log in to a UI).
If you want to add a mailbox, you have to change that user’s access to allow the new mailbox.
Application Permissions has Y Meadows act as an app. The app has permissions, for example it can be limited to only read emails and not create emails. But, it cannot be limited on an account by account, i.e. mailbox by mailbox level. If it can read emails, it can read everyone’s emails. Y Meadows will only ever look at the mailbox that is configured. However, the credentials would enable us to read any account’s emails. And changing which inbox(es) are read by Y Meadows is achieved in the Y Meadows admin UI.
This does not require someone to log into O365 during Y Meadows setup. It also makes it easy to switch mailboxes.
Delegated Permissions Setup
Step 1 - Create an App Registration
In the Azure Portal (Microsoft Azure ):
Select "App registrations" (https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade). This is part of Entra, formerly Azure Active Directory (AD)
Press the "+ New Registration" button.
Fill out the form:
Name (can be anything...). "YMeadows"
Account type - Accounts in this organizational directory only
Press "Register" at the bottom
Navigate to the newly created App Registration...
Copy/Note the "Application (client) ID" and the "Directory (tenant) ID". You will need this data in a later step.
Step 2 - Create secret
On the left, navigate to "Certificates & secrets" under the “Manage” menu.
Click the "+ New client secret" button. Use the longest expiration period that your security policies allow.
Note the expiration deadline and set a calendar alert some time in advance. When the credential expires a new one will need to be generated!
Choose a Description that makes sense for your use (EG: Y Meadows automation)
Click the Add button at the bottom of the screen
Copy/Note the generated client secret. You will need it in a later step.
Step 3 - Add redirect URL
On the left, navigate to "Authentication" under “Manage”
Hit the "+ Add a platform" button.
Select "Web"
Enter “https://oauth-redirect.ymeadows.com/“ as “Redirect URIs“
Check “Access tokens (used for implicit flows)“ checkbox
Click “Configure“
Step 4 - Get the Mailbox ID / User ID
(Note, this is called a “user id” in the Y Meadows user interface)
In order to trigger automations based on new incoming email we need to know what mailbox to watch. This could be specified as both an email address or as an ID. For shared mailboxes, the information for the mailbox should be used so that the inbox of the user who authenticates is not reviewed.
In Azure Portal:
select "Users" if YM will watch an individual’s mailbox and “Group” if it is a shared mailbox
select the User/Group for the mailbox that is going to be watched
get the "Object ID" for this user or Mailbox (This will be used as the User ID when filing in the connection in YM)
Note: for a shared Mailbox you will need the Object ID of the shared mailbox.
Generally, you only need the email address. But, there are circumstances where ID is required. Please provide the ID to Y Meadows if troubleshooting is required.
Step 5 - Setup in Y Meadows
Go to Components > Connections.
Click “+ Connection”.
Enter “Microsoft” in the search bar and press Enter.
Click “Microsoft 365 OAuth 2.0”.
Check the box that says OAuth Settings. More fields will appear.
For Client ID enter the ID you got as "Application (client) ID" from Step 1.
For Client Secret enter the ID you got in Step 2.
For tenant, use the “Directory (tenant) ID” that you got from Step 1.
For user, use the value from Step 4. See note below.
Check Process all messages if you want Y Meadows to start a trip on every email, not just the first one in a thread.
Leave all of the other fields (Authorize Endpoint, Token Endpoint, and Scopes) blank.
Click Save. You will be redirected to a Microsoft page.
You will need to login to Microsoft 365 if you have not done so already. Be sure that the user signing in is the user whose account Y Meadows will be accessing.
Consent for Y Meadows to access the data using the screens shown by Microsoft.
You will be taken back to Y Meadows. It should show the word “Connected” on the screen in green.
How to change the mailbox you are monitoring
Turn off any and all Junction paths that are subscribed to this connection
Wait for 5-6 min so all of the Microsoft 365 subscriptions are removed
Change user ID in the connection.
Go to Junction Source step and re-select directory to watch (even if the directory name is the same the ID is different, so you have to choose it again).
Turn on Junction paths
Wait for 5-6 min so that new Microsoft 365 subscriptions are created.
How to change the permissions the app has
If you need to modify the permissions that the Y Meadows app has then:
Go to the connection
Edit the Scopes field (see below).
Click the check mark.
Click reconnect.
These are the default scopes:
offline_access files.read files.readwrite mail.read mail.readbasic mail.readwrite mail.read.shared mail.readbasic.shared mail.readwrite.shared mail.send mail.send.shared user.read
To make changes, please modify the list above. It is a space separated list of permissions. That is what goes in the Scopes field.
Application Permissions Setup
Step 1 - Create an App Registration
In the Azure Portal (Microsoft Azure ):
Select "App registrations" (https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade). This is part of Entra, formerly Azure Active Directory (AD)
Press the "+ New Registration" button.
Fill out the form:
Name (can be anything...). "YMeadows"
Account type - Accounts in this organizational directory only
Press "Register" at the bottom
Navigate to the newly created App Registration...
Copy/Note the "Application (client) ID" and the "Directory (tenant) ID". You will need this data for a later step.
Step 2 - Create secret
On the left, navigate to "Certificates & secrets" under the “Manage” menu.
Click the "+ New client secret" button. Use the longest expiration period that your security policies allow.
Choose a Description that makes sense for your use
Click the Add button at the bottom of the screen
Copy/Note the generated client secret. You will need it in a later step.
Step 3 - Add API Permissions
On the left, navigate to "API permissions" under “Manage”
Hit the "+ Add a permission" button
Select "Microsoft Graph"
Select "Application permissions"
Type "Mail" in the search box
Select:
ChannelMessage.Edit
ChannelMessage.Read.All
ChannelMessage.ReadWrite
ChannelMessage.Send
Chat.ReadWrite.All
Files.Read.All
Files.ReadWrite.All
Mail.Read
Mail.ReadBasic.All
Mail.ReadWrite
Mail.Send
Sites.Read.All
Sites.ReadWrite.All
User.Read
User.Read.All
Press "Add permissions" at the bottom
Select the "checkmark" for "Grant admin consent for ..."
In the popup click “Yes” to approve the permissions that you just gave the application.
Step 4 - Get the Mailbox ID / User ID
(Note, this is called a “user id” in the Y Meadows connection form)
In order to trigger automations based on new incoming email we need to know what mailbox to watch. This could be specified as both an email address or as an ID. For shared mailboxes, the information for the mailbox should be used so that the inbox of the user who authenticates is not reviewed.
In Azure Portal:
select "Users" if YM will watch an individual’s mailbox and “Group” if it is a shared mailbox
select the User/Group for the mailbox that is going to be watched
get the "Object ID" for this user or Mailbox (This will be used as the User ID when filing in the connection in YM)
Note: for a shared Mailbox you will need the Object ID of the shared mailbox.
Generally, you only need the email address. But, there are circumstances where ID is required. Please provide the ID to Y Meadows if troubleshooting is required.
Step 5 - Setup in Y Meadows
Go to Y Meadows.
Go to Components > Connections.
Click “+ Connection”.
Enter “Microsoft” in the search bar and press Enter.
Click “Microsoft 365”.
Do not use the connection type that has “OAuth” in its name.
For tenant and application id, use the values from Step 1.
For scope, use https://graph.microsoft.com/.default
For secret, use the value from Step 2.
For user, use the value from Step 4.
Check Process all messages if you want Y Meadows to start a trip on every email, not just the first one in a thread.
Click “Save”.
Changing permissions to an existing app
Sometimes you need to change the permissions granted to Y Meadows.
Last updated
Was this helpful?