Enabling OAuth2 authorization in your Microsoft 365 account
PreviousEnabling OAuth2 Authorization in your Google AccountNextTroubleshooting guides for Microsoft OAuth2 Connections
Last updated
Last updated
On this page |
This article explains how to enable Microsoft 365 OAuth2 in your Microsoft Azure tenant to authenticate Email This Issue. This allows you to send FROM and receive TO your Microsoft 365 address using this application.
This guide applies to create and configure client credentials for both incoming and outgoing connections requiring the following OAuth2 authentication:
IMAP with OAuth2 authentication to read an Office365 mailbox
SMTP with OAuth2 authentication to send mails from Office365 address
Microsoft Graph API (uses OAuth2 by default) to read an Office365 mailbox
Microsoft Graph API (uses OAuth2 by default) to send mails from Office365 address
The only difference between these use cases is in their permission scopes they require to operate, i.e. all the steps detailed in the Application registration chapter are basically identical.
Before you begin with the app registration, check if you have the following:
A Microsoft365 account
An active Exchange Online license (aka “subscription”). Otherwise, you will get obscure error messages during the authorization process.
For example, if you have a Microsoft 365 Business Standard package, you should see something like this:
Visit the following link in your Microsoft Azure account (within your Azure Active Directory): https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
Click on + New registration
Register your application as illustrated:
Make sure to add the following content to the fields:
Name: An easily identifiable name.
Account type: Select the account type whether it should be available for accounts outside your organization or not.
Single tenant: choose this if the app is accessible for your organizational directory
Multitenant: choose this if you want to allow any organizations to use this app
Redirect URI: In the Redirect URI section, do the following:
Leave the Web as selected.
Copy and paste the Callback URL from the OAuth2 Client Credentials dialog as the URI value. As this URL is specific to your Jira instance, it is important to copy the URL from the Email This Issue app into this page as a URI of another Jira instance cannot be reused.
Important: As of now the OAuth2 for SMTP/IMAP is not supported for personal Microsoft accounts.
API Permissions (scopes) need to be granted for the application.
1. Click on the Register button to create your application
2. On the overview page of your newly created app select the API permissions / Security -> Permission menu:
3. To achieve this list of permission for your app do the following:
3.1. Do not remove the User.Read permission added as a default by the portal, as this is required to automatically obtain the username (more specifically, the userPrincipalName) associated with the account (identified by the email address you'll provide during the mail connection setup in the Email This Issue app).
3.2. To add any further permissions (scopes), click on the Add a permission button and select the Microsoft Graph group:
3.3. Select Delegated permissions then find and select the permissions. Depending on your actual use case (i.e. the used messaging/communication protocol), the following permissions shall be added:
General permissions (required both for incoming and outgoing connections)
General permissions are needed to acquire a refresh token and then manage access tokens (i.e. these are required in each and every use case). Besides offline_access and openid, the User.Read permission is also necessary. If not added by default (-> see point 3.1.), please manually add it now.
IMAP permissions (required for inbound traffic)
Permissions to use the IMAP protocol. In the filtering field provide the search term imap:
SMTP permissions (required for outbound traffic)
Permissions to use the SMTP protocol. You can find the permission for SMTP by entering smtp in the search field:
Graph API permissions to fetch messages
Permissions to use Graph API for incoming connections. These permissions can be found by entering mail. in the search field:
Graph API permissions to send messages
Permissions to use Graph API for outgoing connections. These permissions can be found by entering mail. in the search field:
General notes: The selections are retained between filtering. As soon as all the permissions have been selected, they can be added together by clicking on the Add permissions button at the bottom. This enables mixing and mingling any permission scopes within an app registration and exposing them via a client secret.
This also means that if using separate mailboxes (email addresses) is needed for different tasks, it is necessary to configure and grant the permissions for that functionality only. For example, it is possible to differentiate between incoming and outgoing connections, i.e. an app registration (and a respective client credential) can be created to configure a Mail Handler, while another registration can be made to use for message sending only (i.e. in order to configure a mailbox to be used by an incoming connection, permissions related to the SMTP protocol are unnecessary). In other words, the concept of mail providers allows for granular use and definition of permission scopes and the respective client credentials representing them.
In the Microsoft365 world, within a tenant, several app registrations can exist (with diverging configurations) for the very same account (mail address), while different accounts (mail addresses) might be used within a tenant to implement different tasks with individual app registrations for each, as well. There is also the possibility of creating a multi-tenant app registration if there is a demand for accessing a mailbox from different tenants (i.e. organizations/companies/departments/etc.) or from external addresses. Access and permission schemes can be organized according to your needs.
Generate a client secret to be used in client credentials.
1. Select the Certificates & secrets menu.
2. Click on the New client secret button to create a new client secret.
3. Add a description.
4. Select the expiration date that fits your needs
5. Click Add.
Important: Don’t forget to copy the client secret and provide it to the configuration part along with the Client ID from the Overview page of the app.
The authorization and token endpoints need to be added from the Microsoft app to the Client Credentials in Email This Issue.
Note: Without doing this you need to pay attention to finding and applying these endpoint URIs.
In the case of Microsoft 365 Oauth2, the authorization and token endpoints are different for multi- and single-tenant configurations.
For a single-tenant configuration, endpoints are unique for each tenant. As a consequence, you must provide them on the OAuth2 Client Credentials dialog.
For both the multi and single tenant configuration you find this information on the Overview page of the registered application selecting the Endpoint menu on the top as it is shown on the following screenshots. Copy and paste both of them.
You can easily copy and paste both of them.
In case you want to revoke the permission from the registered application to authenticate on behalf you just visit https://myapps.microsoft.com/ and delete the registered application from the list as shpwn in the following image:
The released access token still will be valid within its validity period. Only by refreshing the access token will it fail for this specific account. The application registration is untouched and other accounts can continue to use it.
