# Enabling OAuth2 authorization in your Microsoft 365 account

| **On this page**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <ul><li><a href="#introduction-checking-your-account-details-and-subscription">Introduction, checking your account details and subscription</a></li><li><p><a href="#registering-an-application">Registering an application</a></p><ul><li><a href="#step-1-finding-azure-active-directory-to-manage-your-account">Step 1 - Find Azure Active Directory to Manage You Account</a></li><li><a href="#step-2-initiating-an-app-registration">Step 2 - Initiating an app registration</a></li><li><a href="#enablingoauth2authorizationinyourmicrosofto365account-step3-account-tenant-typeselection">Step 3 - Account (tenant) type selection</a></li><li><a href="#enablingoauth2authorizationinyourmicrosofto365account-step4-defineapipermissions">Step 4 - Define API permissions</a></li><li><a href="#enablingoauth2authorizationinyourmicrosofto365account-step5-generateclientsecret">Step 5 - Generate client secret</a></li><li><a href="#enablingoauth2authorizationinyourmicrosofto365account-step6-copyendpointsuris">Step 6 - Copy endpoints URIs</a></li></ul></li><li><a href="#enablingoauth2authorizationinyourmicrosofto365account-removingtheconsent">Removing consent</a></li></ul> |

## Introduction, checking your account details and subscription

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 creating and configuring 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&#x20;
* An active[ Exchange Online license](https://portal.office.com/account/?ref=MeControl#subscriptions) (aka “subscription”). Otherwise, you will get obscure error messages during the authorization process.<br>

For example, if you have a Microsoft 365 Business Standard package, you should see something like this:

![Double-checking the Microsoft 365 subscription](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FIKNYOFL3FQlaUBFcGvPV%2Fimage.png?alt=media\&token=a1d38460-c842-477e-a12e-15fbda1a5321)

## Registering an application

### Step 1 - Finding Azure Active Directory to manage your account

Visit the following link in your Microsoft Azure account (within your Azure Active Directory):\
<https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps>

### Step 2 - Initiating an app registration

Click on **+ New registration**

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F5a8u4C3GnGCDo91jGVLK%2Fimage.png?alt=media&#x26;token=2b665666-ef34-4af3-835d-e20a36b4e452" alt=""><figcaption><p>Initiating a new app registration on the Azure Portal</p></figcaption></figure>

### Step 3 - Account (tenant) type selection <a href="#enablingoauth2authorizationinyourmicrosofto365account-step3-account-tenant-typeselection" id="enablingoauth2authorizationinyourmicrosofto365account-step3-account-tenant-typeselection"></a>

Register your application as illustrated:

![Registering an application](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FJMpl2Ob8oK1XIFACHBQV%2Fimage.png?alt=media\&token=0de3555c-4796-44e1-93a6-e90e78d1d095)

Make sure to add the following content to the fields:

* **Name**: An easily identifiable name.
* **Account type**: Select the account type to indicate 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.&#x20;
  * Copy and paste the **Callback URL** from the [OAuth2 Client Credentials](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/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.

{% hint style="warning" %}
Important: As of now, the OAuth2 for SMTP/IMAP is not supported for personal Microsoft accounts.
{% endhint %}

### Step 4 - Define API permissions <a href="#enablingoauth2authorizationinyourmicrosofto365account-step4-defineapipermissions" id="enablingoauth2authorizationinyourmicrosofto365account-step4-defineapipermissions"></a>

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:

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FHxuIkujwj7XEk18w3Kli%2Fimage.png?alt=media&#x26;token=0d069b68-4519-49bf-95d0-cc2625648aa8" alt=""><figcaption><p>The complete list of permissions required for both incoming and outgoing connections</p></figcaption></figure>

3\. To achieve this list of permission for your app do the following:

&#x20;   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).

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FRWK6ca9uMEcd9HmEjZUD%2Fimage.png?alt=media&#x26;token=212dceb3-cd77-405e-a3b0-73fcb01d2b40" alt=""><figcaption><p>Encountering and keeping the User.Read permission associated with the app registration by default</p></figcaption></figure>

&#x20;   3.2. To add any further permissions (scopes), click on the **Add a permission** button and select the *Microsoft Graph* group:

![Navigating to the API permission manager](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fn1beH04o8YJ8PZjc19e6%2Fimage.png?alt=media\&token=db388bda-301a-4733-a4f1-2a12bf0ae1f4)

&#x20;    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 for both 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.

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FMnmpDGODDWzDKtxSKc4X%2Fimage.png?alt=media&#x26;token=6e874bd5-62fc-4a1d-973e-c031c75b67f7" alt=""><figcaption><p>General permissions</p></figcaption></figure>

* **IMAP permissions (required for inbound traffic)**

Permissions to use the IMAP protocol. In the filtering field provide the search term `imap`:

![IMAP-specific permissions](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FR07yKY11Fy6e0Yki0xNM%2Fimage.png?alt=media\&token=9d71fe46-7d56-4c24-bac4-70304c98b51a)

* **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:

![SMTP-specific permissions](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fpsct3cL2AnzjQqgXTLwl%2Fimage.png?alt=media\&token=90131111-6be6-494f-a82b-f3ef1f07755b)

* **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:

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FzbDEdPlZ2Yebpgyz1wR8%2F2024-10-22_10h48_44.png?alt=media&#x26;token=0a6c4c4c-e4b5-414f-a2a0-feadeb3faace" alt=""><figcaption><p>Graph specific permissions for receiving emails</p></figcaption></figure>

* **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:

<figure><img src="https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fp58lUNluychD5UnsNwfY%2F2024-10-22_10h51_20.png?alt=media&#x26;token=480dc54c-2d9f-4a45-a613-4a62404ac4aa" alt=""><figcaption><p>Graph specific permissions for sending emails</p></figcaption></figure>

**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.

### Step 5 - Generating a client secret <a href="#enablingoauth2authorizationinyourmicrosofto365account-step5-generateclientsecret" id="enablingoauth2authorizationinyourmicrosofto365account-step5-generateclientsecret"></a>

Generate a client secret to be used in [client credentials](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/oauth2-client-credentials).&#x20;

1\. Select the **Certificates & secrets** menu.

![Azure Active Directory: Certificates & secrets](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F6Q9tuAOuvcomz843zHxA%2Fimage.png?alt=media\&token=9ef5bc8e-2a33-41f6-adf1-d71a3d65879b)

2\. Click on the **New client secret** button to create a new client secret.

![Adding a new client secret](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2Fxw7bQxxLqPmRfuLSqEmP%2Fimage.png?alt=media\&token=0d2dd75e-b13d-4d07-9c9d-06c6141d6608)

3\. Add a description.

4\. Select the expiration date that fits your needs&#x20;

5\. Click **Add**.

![Info panel calling for copying the client secret](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F2ros5BqEZga5pAlROHHS%2Fimage.png?alt=media\&token=d78e3930-24d7-4b7d-ab31-35becf6c2588)

{% hint style="warning" %}
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.
{% endhint %}

![The location of Client ID (aka Application ID) to copy from](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FIoMLxDU8SSQwRSSYZOsV%2Fimage.png?alt=media\&token=0629a384-e0e5-4c29-9b49-01b67e33fcda)

### Step 6 - Copying endpoints URIs <a href="#enablingoauth2authorizationinyourmicrosofto365account-step6-copyendpointsuris" id="enablingoauth2authorizationinyourmicrosofto365account-step6-copyendpointsuris"></a>

The authorization and token endpoints need to be added from the Microsoft app to the [Client Credentials](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/oauth2-authorizations-in-email-this-issue/broken-reference) in Email This Issue.&#x20;

{% hint style="info" %}
Note: Without doing this, you need to pay attention to finding and applying these endpoint URIs.
{% endhint %}

In the case of Microsoft 365 Oauth2, the authorization and token endpoints are different for multi- and single-tenant configurations.&#x20;

For a single-tenant configuration, endpoints are unique for each tenant. As a consequence, you must provide them in the [OAuth2 Client Credentials](https://docs.meta-inf.hu/email-this-issue/email-this-issue-for-jira-server-data-center/documentation/administration/oauth2-client-credentials) dialog.

For both the multi- and single-tenant configurations, you find this information on the Overview page of the registered application, selecting the Endpoint menu at the top, as shown in the following screenshots. Copy and paste both of them.

![Copying endpoint URIs](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2F3Kf4fGjnpomICzKDYR4G%2Fimage.png?alt=media\&token=6a5c5c0f-5adb-4156-9394-23b50aa0855d)

You can easily copy and paste both of them.

## Removing consent <a href="#enablingoauth2authorizationinyourmicrosofto365account-removingtheconsent" id="enablingoauth2authorizationinyourmicrosofto365account-removingtheconsent"></a>

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:

![Withdrawing personal consent (granted for an app previously)](https://4173056255-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY44m7ZY1jU4Arh2tzwNn%2Fuploads%2FFy8NyKwEEvjwvPZK84X4%2Fimage.png?alt=media\&token=f59a64cb-b7ec-4e2f-8c10-23f8f7338c08)

The released access token will still 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.