Microsoft IMAP and SMTP with OAuth2

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

Step 3 - Account (tenant) type selection

Register your application as illustrated:

Registering an application

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.

  • Copy and paste the Redirect URL from the OAuth2 Client Credentials dialog as the URI value. As this URL is specific to your Jira instance, it is essential to copy the URL from the Email This Issue app into this page as a URI of another Jira instance cannot be reused.

    

    Redirect URI

Important: As of now the OAuth2 for SMTP/IMAP is not supported for personal Microsoft accounts.

Step 4 - Define API permissions

API Permissions (scopes) need to be granted for the application.

1. On the overview page of your newly created app select the API permissions / Security -> Permission menu. Click on the Add a permission button and select the Microsoft Graph group:

Navigating to the API permission manager

1. 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:

2.1. 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).

• offline_access

• openid

• User.Read (If not added by default, please manually add it now.)

General permissions

2.2. IMAP permissions (required for inbound traffic)

• IMAP.AccessAsUser.All Permission to use the IMAP protocol. In the filtering field provide the search term imap:

IMAP-specific permissions

2.3. SMTP permissions (required for outbound traffic)

• SMTP.Send Permissions to use the SMTP protocol. You can find the permission for SMTP by entering smtp in the search field:

SMTP-specific permissions

Here is the complete list of required permissions

The complete list of permissions required for both incoming and outgoing connections

Step 5 - Generating a client secret

Generate a client secret to be used in client credentials.

1. Select the Certificates & secrets menu.

Azure Active Directory: Certificates & secrets

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

Adding a new client secret

3. Add a description.

4. Select the expiration date that fits your needs

5. Click Add.

6. Copy the Client Secret Value as you need to enter it into the Email This Issue app and it will not be visible in the Azure UI later.

Step 6 - Copying data into Email This Issue

In Email This Issue go to OAuth2 credentials and click to create new credentials.

1. Name: a custom name for this entry.

2. OAuht2 Service Provider: Microsoft 0365

3. Grant type: Auth code

4. Client ID: the Application (client) ID - you can find it on the Overview screen

   

   The location of Client ID (aka Application ID) to copy from
5. Client Secret: this needs to be the Client Secret Value

   

   Location of the Client Secet Value to copy from
6. Auth Endpoint URL: you can find this information on the Overview page of the registered application, selecting the Endpoint menu at the top. Ensure that you copy the V2 endpoint.

   

   Location of the Auth Endpoint URL to copy from
7. Token Endpoint URL: you can find this information on the Overview page of the registered application, selecting the Endpoint menu at the top. Ensure that you copy the V2 endpoint.

   

   Location of the Token Endpoint URL to copy from

Removing consent

In case you want to revoke the permission from the registered application to authenticate on your behalf, just visit https://myapps.microsoft.com/ and delete the registered application from the list, as shown in the following image:

Withdrawing personal consent (granted for an app previously)

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.