In this article, we will walk you through setting up the app registration and send email using Microsoft Graph API. Also, show you on how to limit which mailboxes this app registration can interact with, as application permissions have access to every mailbox by default.
Since the old age, applications that need to send emails through Exchange have always used a service account or a send connector to authenticate to the mail server and send emails. Within a Microsoft 365 environment, service accounts are a burden to manage as they cannot be protected with multifactor authentication and often use legacy authentication (which you really want to disable).
In order to mitigate this issue, Microsoft has provided the capabilities to use Microsoft Graph, the API that you use to connect to Microsoft 365, is secured with OAuth 2.0. In order to connect your app to Microsoft 365, you will need to create an app in Azure Active Directory (Azure AD) and grant this app permissions to access specific resources on behalf of the person using your app. The authentication is entirely based on the tenant ID, client ID and client secret of an application.
Important
- You only need application permissions to send emails from the Azure Active Directory app.
- Mail.Read will allow the application to read that mailbox’s emails. Mail.Send will allow the application to send emails from that mailbox.
- A mailbox should be added as members to the mail enabled security group to send emails.
- The EWS protocol should not be blocked on the mailbox as that would effectively block Graph API.
- To check the EWS status on the mailbox, Get-CASMailbox “Mailbox email address here” | fl EwsEnabled
- The mailbox active directory account can be disabled, and it does not need to be assigned an Exchange Online license to work with the application.
- IMAP and POP will not be used by an application working on top of the Graph API so it can be disabled if you do not have any other application dependencies on this mailbox through POP or IMAP.
- Client secret key on the Azure Active Directory app is valid for 2 years. It should be renewed before it expires.
Add new application registration in Azure Active Directory
- The first step in the process is setting up the app registration. Go to the Azure portal at https://portal.azure.com
- From the menu, select ‘Azure Active Directory‘
- From the Azure Active Directory menu, select ‘App registrations.’
- From the top menu, select the ‘New registration‘ button.
- Provide a meaningful name. This name is not visible to any end-user so it is recommended to use a name by which you can use to easily identify the application in the future.
- For the type of supported account types, select ‘Accounts in this organizational directory only (Single tenant)‘.
- After the app is created, you will be reverted to an overview page where you can find application/client ID and the tenant ID. Copy them to your clipboard, as you will need them later.
- The next step is to provide the correct permissions to the application. Navigate to the ‘API permissions’ tab and select ‘Add a permission’.
- The bulk of the services within Microsoft APIs permissions, use the ‘Microsoft Graph’. In our case, this is the API you are using to send email.
- Next up, choose ‘Application permissions’ and find the permission ‘Mail.Read’ and ‘Mail.Send’.
- In order to assign these permissions, you need to provide admin consent. To do so, click the ‘Grant admin consent’ button. A pop-up window will appear to authenticate the administrator.
- With the correct permissions setup, the last step is to generate a client secret.
- From ‘App registrations’ in Azure Active Directory, select your application. Navigate to ‘Certificates & secrets’ and select ‘New client secret’.
- A new pop-up window will appear to provide a description for your secret and select life time.
- The life time depicts how long the secret will be valid. The application using this app registration should be updated with a valid secret before it expires, as this will prevent unwanted downtime.
- Rotating your client secrets regularly protects your applications from leaked credentials.
- It is recommended to provide a meaningful description to the secret to easily identify it later.
- After you add the secret, it will be shown in the portal. Be sure to copy it as this is only visible once.
Limiting application permissions to specific Exchange Online mailboxes
There are scenarios where administrators may want to limit an app to only specific mailboxes and not all Exchange Online mailboxes in the organization. Administrators can identify the set of mailboxes to permit access by putting them in a mail-enabled security group. Administrators can then limit third-party app access to only that set of mailboxes by creating an application access policy for access to that group.
- In order to limit the scope of Exchange application permissions, you need to create an application access policy.
- With an application policy you can restrict the permissions of an application to a certain group or deny access to a specific group. Creating and managing application access policies is only possible through PowerShell.
- To create a new application policy, connect to Exchange Online PowerShell and create the application access policy.
- This is done with the New-ApplicationAccessPolicy. Replace <AppId> with the Application ID of your newly created app and the parameter ‘PolicyScopeGroupId’ requires a mail enabled security group which should include all the users that the application needs to have access to.
New-ApplicationAccessPolicy -AppId “Application ID here” -PolicyScopeGroupId “Mail enabled security group here” -AccessRight RestrictAccess -Description “Restricted access”
- After the policy is created, you can use the Test-ApplicationAccessPolicy to verify that the application cannot access any mailbox outside of the group.
- Use the shared mailbox email address and the mail enabled security group to verify the policy status. The access check result of both should be granted.
Test-ApplicationAccessPolicy -Identity “Mailbox email address here” -AppId “Application ID here”
Test-ApplicationAccessPolicy -Identity “Mail enabled security group here” -AppId “Application ID here”
- The AccessCheckResult depicts the fact whether the application is allowed to interact with a specific mailbox. Allow 24 hours for the changes to reflect in cloud.
Supported permissions and additional resources
Administrators can use ApplicationAccessPolicy cmdlets to control mailbox access of an app that has been granted any of the following Microsoft Graph application permissions or Exchange Web Services permissions.
Microsoft Graph application permissions:
- 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 more information about configuring application access policy, see the PowerShell cmdlet reference for New-ApplicationAccessPolicy.
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 members 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 Azure Active Directory > App registrations > All applications > Search the app name > API Permissions > Modify the permissions. |
| I no longer wish to send emails using the Azure Active Directory app. | Remove the shared mailbox as members of the mail enabled security group which will deny the access to send emails. |
| Will I be able to view the emails that I sent from the Azure 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 outlook web app (OWA). |
| Will end users be aware of client secret key expiration? | Monitor the renewals and let me know about the expiration and create a new client secret in Azure 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 to view the assigned Azure app permissions? | Go to Azure Active Directory > App registrations > All applications > Search the app name > Select API permissions. |
| I cannot find the Azure app based on the above options. | Go to Azure 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 Azure app is already registered then just add the shared mailbox as members to the mail enabled security group and execute the test command to verify. |
| How do I know if the Azure AD app is already created or newly registered? | Connect to Exchange Online PowerShell and execute the command which displays list of Azure apps created in the tenant. If the newly created app 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 Azure 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 |
While interacting with Exchange Online through the Microsoft Graph API is rather easy, it’s really important to understand the scope of the permissions you are assigning. Application permissions are extremely powerful and should be handled with care. By using application access policies within Exchange Online, we can mitigate the attack surface an application has access to.
That’s how you can send email using Microsoft Graph API.
Which finding from today’s report did you find most interesting? Or maybe you have a question about something that I covered.
Either way, I’d like to hear from you. So go ahead and leave a comment below.
