This article focuses on setting up an OAuth Provider for use with a Microsoft Office 365 account. Once configured, you will be able to retrieve access and refresh tokens from the Microsoft Azure OAuth server by using the OAuth 2 Authorization-Code grant type. I first list what must be done in Azure before touching anything in ServiceNow.
See Microsoft’s official guide: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-...
1 – Install the plugin
Go to All › Plugins in the instance and install OAUTH support for IMAP, Microsoft Graph (Receiving) and SMTP.
The next steps are performed in Microsoft Azure, so you will need the team responsible for Azure.
2 – Register an application in Azure Active Directory and set the ServiceNow OAuth redirect URL
3 – Create a client secret for the application to prove its identity when requesting a token
4 – Add OAuth scopes in the Azure application for SMTP/IMAP and offline_access (to obtain the refresh token, per Microsoft’s documentation). Azure also recommends keeping the User.Read scope for proper operation; don’t remove it. The final API permissions are shown below.
From this point on, the steps are done in ServiceNow.
5 – Configure OAuth in ServiceNow for Microsoft
Open Email Accounts as shown below
Fill in the following fields:
Even so, you still won’t be able to submit the record because there is no OAuth Profile yet; we’ll configure it now.
6 – Open Application Registry in a new tab
Click New
Select Connect to a third-party OAuth Provider
-
Configure Microsoft OAuth endpoints
-
Authorization URL:
https://login.microsoftonline.com/<Azure-tenant-ID>/oauth2/v2.0/authorize -
Token URL:
https://login.microsoftonline.com/<Azure-tenant-ID>/oauth2/v2.0/token -
Redirect URL:
{Instance_URL}/oauth_redirect.do
-
OAuth Entity Scopes
| Name | OAuth Scope |
|---|---|
| IMAP.AccessAsUser.All | https://outlook.office.com/IMAP.AccessAsUser.All |
| SMTP.Send | https://outlook.office.com/SMTP.Send |
| offline_access | offline_access |
-
Add all the scopes created in step 2 to OAuth Entity Profile Scopes.
Now go back to Auth Profile, click the magnifier
and then New.
Fill in the fields as below, choose the same OAuth Provider name you used earlier, then submit the record. Don’t forget to replicate the scopes in this record as well.
7 – After saving the OAuth Entity Profile, the button appears
PAY CLOSE ATTENTION TO THIS STEP.
This is the number-one reason for failure in most cases.
You must use a private/incognito window and a local login (side_door.do, if necessary) to ensure your personal account is not detected by Microsoft SSO. Enter the mailbox account’s username/credentials, not your own. If you attempt to authorise while already signed in to Azure, no pop-up window appears and it may look like the authorisation succeeded; however, the instance receives an access token for your credentials instead of the mailbox account. Test Connection will then fail because the instance tries to access the mailbox with your account and is denied.
8 – Once the tokens are received and Test Connection succeeds, e-mail send/receive should work. Yet sometimes nothing happens and no obvious error helps diagnosis.
TL;DR: Use the provided Background Script to validate the received Access Token. It has been observed that the problem is most often the wrong Microsoft account authorising mailbox access.
For example, if a user is signed in via Microsoft SSO or already has an active Microsoft session (Outlook, Office, etc.), that session is silently picked up when Authorize Email Account Access is invoked. The user’s own account then authorises access instead of the intended IMAP/SMTP mailbox, and the tokens belong to the wrong identity.
Example: the email account servicedesk@vbcpn.onmicrosoft.com is configured as an IMAP mailbox.
he logged-in user AdeleV@vbcpn.onmicrosoft.com is an SSO user. When Adele tries to authorize access for the IMAP account by clicking “Authorize Email Account Access,” Microsoft uses Adele's active session, preventing emails from being retrieved from servicedesk@vbcpn.onmicrosoft.com, because the received tokens belong to AdeleV@vbcpn.onmicrosoft.com.
Therefore, strictly follow the step: use a private/incognito window and a local login (side_door.do, if necessary) to ensure your personal account is not detected by Microsoft SSO. Provide the email account’s credentials, not your own.
If you attempt authorization while already signed in to Azure, no popup appears and it may seem to succeed, but the instance receives a token for your own credentials. Ideally, you should get the Microsoft login prompt where you enter the mailbox’s email address.
Summary
This guide walks through installing the email-OAuth plugin, registering an Azure AD app with the required SMTP/IMAP scopes, creating the OAuth Provider and Profile in ServiceNow, and authorizing the mailbox in an incognito session. When done, ServiceNow fetches and auto-renews tokens, eliminating password expiry and Basic Auth issues for Office 365 email.
For this article, references were used from the ServiceNow knowledge articles (Support) with the following numbers: KB0816072, KB2071947
