In this guide, we’ll take you step-by-step through setting up your app registration and showcasing how to send email using Microsoft Graph API. Plus, we’ll highlight how to control which mailboxes your app registration can interact with, considering that application permissions usually come with access to every mailbox by default.
In the good old days, applications needing to send emails through Exchange relied on service accounts or send connectors for authentication to the mail server. However, managing service accounts in a Microsoft 365 environment can be a bit of a hassle—they can’t benefit from multifactor authentication and often stick to legacy authentication (which you’d ideally want to disable).
To make life easier, Microsoft offers the option of using Microsoft Graph, the API that connects you to Microsoft 365 and is secured with OAuth 2.0. To get started, create an app in Microsoft Entra Active Directory (Entra AD), and grant it the necessary permissions to access specific resources on behalf of the user. Authentication revolves around the tenant ID, client ID, and client secret of your application. Happy emailing!
Send Email Using Microsoft Graph API: Important
- When setting up your Entra app for sending emails, remember you only need application permissions. Specifically, Mail.Read lets your app read emails from the mailbox, while Mail.Send grants it the ability to send emails from that mailbox.
- To enable email sending, make sure to add the mailbox as a member of the mail-enabled security group.
- Ensure that the EWS protocol isn’t blocked on the mailbox, as that could inadvertently block the Graph API.
- For a quick check on the EWS status, use the command: Get-CASMailbox “Mailbox email address here” | fl EwsEnabled
- Here’s a pro tip: The mailbox’s active directory account can be disabled, and it doesn’t require an Exchange Online license to collaborate seamlessly with the application.
- As a side note, if you’re not using IMAP or POP for any other application dependencies, feel free to disable them—they won’t be needed for an app working with the Graph API.
- And lastly, don’t forget to renew the client secret key before it expires to keep everything running smoothly. Happy configuring!
Add new application registrations in Entra
Let’s walk through the first crucial step: setting up your app registration on the Entra portal.
- Navigate to the Entra portal and, in the left pane under Identity, choose ‘Applications‘ and then ‘App registrations.’
- Click on the ‘New registration‘ button from the top menu.
- Give your app a meaningful name; remember, it’s not visible to end-users, so make it easy to identify in the future.
- For supported account types, select ‘Accounts in this organizational directory only (single tenant).’
- After creation, you’ll be directed to an overview page. Copy the application/client ID and tenant ID; you’ll need them later.
- Move to the ‘API permissions‘ tab, click ‘Add a permission.’
- Since we’re dealing with Microsoft Graph, find ‘Microsoft Graph.’
- Choose ‘Application permissions’ and locate and select ‘Mail.Read‘ and ‘Mail.Send.”
- Admin consent is needed, so hit ‘Grant admin consent.’ Authenticate the administrator in the pop-up window.
- The final step is to whip up a client secret. Easy peasy!
- Back in ‘App registrations,’ select your application, go to ‘Certificates & secrets,’ and click ‘New client secret.’
- Get ready for a new pop-up adventure! This window is here to help you describe your secret and set its lifetime. The lifetime is like the countdown to a secret party—it shows how long your secret will be valid. Remember, update your application with a fresh secret before the countdown hits zero to avoid any unplanned downtime.
- And here’s a pro tip: regularly changing your client secrets is like giving your applications a superhero costume change—keeps them safe from leaked credentials. Don’t forget to give your secret a meaningful description, so you can easily spot it in the crowd later on!
- Once you’ve added the secret, it’s time for its grand reveal on the portal stage. Don’t blink or you might miss it! Make sure to grab a copy because this show is a one-time event—you won’t get an encore.
Limiting application permissions to Exchange Online mailboxes
Picture this: administrators playing the role of mail puppet masters, wanting to give specific apps the VIP treatment by limiting them to certain mailboxes. To make this happen, they gather those chosen mailboxes into a mail-enabled security group—the exclusive guest list. And to ensure the third-party apps follow the rules, administrators create an application access policy that grants access only to the members of this elite group. It’s like having a velvet rope for your mailboxes, ensuring only the right apps get past the bouncer.
- To put a leash on Exchange application permissions, you’ll want to whip up an application access policy.
- Think of it like setting the rules for a well-behaved app—what it can and can’t do. But here’s the catch: this power move is exclusive to PowerShell.
- So, buckle up, connect to Exchange Online PowerShell, and let’s craft that application access policy magic. Use the New-ApplicationAccessPolicy command, replacing <AppId> with your app’s Application ID. Oh, and don’t forget to toss in the ‘PolicyScopeGroupId,’ which is basically a mail-enabled security group with all the users the app should have access to. It’s like giving your app its own set of golden keys.
New-ApplicationAccessPolicy -AppId “Application ID here” -PolicyScopeGroupId “Mail enabled security group here” -AccessRight RestrictAccess -Description “Restricted access”
- Once your policy masterpiece is crafted, it’s time to run the ultimate check-up with Test-ApplicationAccessPolicy.
- Think of it as the app’s wellness exam. Plug in the email address of the shared mailbox and the mail-enabled security group, and watch the magic happen. If all goes well, both should get the green light—AccessCheckResult showing that your app has the VIP pass to interact with those mailboxes.
Test-ApplicationAccessPolicy “Mailbox email address here” -AppId “Application ID here”
Test-ApplicationAccessPolicy “Mail enabled security group here” -AppId “Application ID here”
- Just a heads up: changes take a bit to sync with the cloud, so be patient and give it a cozy 24 hours. It’s like waiting for the paint to dry on your masterpiece—it’s worth it in the end!
Supported permissions and additional resources
Admins, listen up! If you’ve got an app with some serious Microsoft Graph application permissions or Exchange Web Services permissions, the ApplicationAccessPolicy cmdlets are your go-to control panel.
It’s like having the keys to the kingdom for mailbox access. So whether your app has its eyes set on Microsoft Graph application permissions or Exchange Web Services permissions, these cmdlets are your trusty sidekick to keep things in check. Power to the admins!
- Mail.Read
- Mail.ReadBasic
- Mail.ReadBasic.All
- Mail.ReadWrite
- Mail.Send
- MailboxSettings.Read
- MailboxSettings.ReadWrite
- Calendars.Read
- Calendars.ReadWrite
- Contacts.Read
- Contacts.ReadWrite
Exchange Web Services permission scope: full_access_as_app.
For all the nitty-gritty details on configuring application access policies, consider the PowerShell cmdlet reference for New-ApplicationAccessPolicy. It’s like having the playbook to master the art of controlling access for your app. Go ahead, unleash the power!
Common issues and troubleshooting
| Issues | Troubleshooting |
| When I check the policy status using the mail enabled security group, the status shows granted but when I check it using the shared mailbox, it gets denied. | Add the shared mailbox as a member to the mail enabled security group and allow 5–10 minutes for replication. |
| I am getting ErrorAccessDenied when sending emails. | Ensure that the app has permission to access the mailbox resource. |
| How do I change the application access permissions? | Go to Entra Active Directory > App registrations > All applications > Search the app name > API Permissions > Modify the permissions. |
| I no longer wish to send emails using the Entra Active Directory app. | Remove the shared mailbox as a member of the mail enabled security group, which will deny access to send emails. |
| Will I be able to view the emails that I sent from the Entra Active Directory app? | After the message is sent, it will be saved to the sent items folder of the shared mailbox, which can be viewed on Outlook or the Outlook web app (OWA). |
| Will end users be aware of client secret key expiration? | This is manual work. Users have to monitor the renewals and involve administrators to create a new client secret in Entra Active Directory. |
| I am getting the token contains no permissions, or permissions cannot be understood error. | Ensure the application permissions are provided with admin consent required ‘Yes’. If delegated permissions provided, then this error would occur. |
| How do I view the assigned Entra app permissions? | Go to Entra Active Directory > App registrations > All applications > Search the app name > Select API permissions. |
| I cannot find the Entra app based on the above options. | Go to Entra Active Directory > Enterprise applications > Search the app name or the application ID > Select permissions. |
| Do I have to create an application access policy each time? | No, if the Entra app is already registered, then just add the shared mailbox as a member to the mail enabled security group and execute the test command to verify. |
| How do I know if the Entra AD app is already created or newly registered? | Connect to Exchange Online PowerShell and execute the command, which displays a list of Entra apps created in the tenant. If the newly created app is not displayed, then create the New-ApplicationAccessPolicy command to create the policy. Get-ApplicationAccessPolicy | fl AppId |
| How do I check the secret key is valid or expired? | Go to Entra Active Directory > App registrations > All applications > Search the app name > The ‘Certificates & secrets’ attribute shows the status. Current – Secret key is valid. Expired – Secret key is expired. Expiring soon – Secret key will expiry soon. |
Navigating Exchange Online through the Microsoft Graph API is quite a breeze, but let’s not underestimate the power of application permissions—it’s a game-changer! Handle them with care, as they wield immense power. To play it safe, dive into application access policies within Exchange Online. They work wonders in narrowing down an application’s access and help keep potential security risks in check.
And there you have it—a secure way to send email using Microsoft Graph API! Easy peasy, right?
I’m all ears! What stood out to you the most in today’s report? Any findings that made you raise an eyebrow or perhaps a question that’s been brewing in your mind? I’m here to chat, so feel free to drop a comment below!
