ServiceNow OAUTH Setup

Steps for OAuth Setup for ServiceNow Office 365 Email Account

  • Register an application on Microsfot Azure AD 
  • Create Client Secret in Azure AD for the Registered Application
  • Configure Microsoft Graph OAuth Scopes and  Permissions on the Registered Application and Authorize them in Azure AD
  • Configure OAuth in ServiceNow for Microsoft Office 365 
  • Create ServiceNow OAuth Entity Scopes
  • Create the corresponding OAuth Entity scopes in the default ServiceNow OAuth Profile 
  • Verify that you can obtain access and refresh tokens using POST MAN
  • Create ServiceNow Office 365 Email Accounts for OAuth SMTP and OAuth IMAP and obtain access and refresh token from Azure AD
  • Troubleshooting OAuth Setup; AADSTS50011: The redirect URI “https://skoanow.comtechnologies.com/oauth_redirect.do” specified in the request does not match the redirect URIs configured for the application ‘4aXXXXXXXXXXXXXXX’
  • Troubleshooting OAuth Setup; Connection Failed. Email sender connection invalid.:Cannot connect to SMTP server: smtp.office365, as: skoanow@skoanowtechnologies.com, message: failed to connect. 
  • Troubleshooting OAuth Setup; Connection Failed. Email sender connection invalid: OAuth access token is not present or has expired. Email account=be9aXXXXXXXXXXXXXXX

Register An Application on Microsfot Azure AD

  • In Azure Active Directory, click on Manage>>select App Registration>>click on New Registration
  • Name: ServiceNow O365 Email; Support Account Types; Who can use this application or access this API? (Accounts in this organizational directory only); Redirect URI (optional) (select Web from the drop down and in the add the OAuth URI, https://skoanow.service-now.com/auth_redirect.do). If there is another alias URL such as https://skoanow.com/auth_redirect.do, then it needs to be added as an authorized URI.  
  • Click Register to register the application.
  • Once the application has been registered, the Application ID will be generated automatically.

Create Client Secret in Azure AD for the Registered Application

  • Within Azure Active Directory, click on Manage>>select App Registration>>>select the registered application (ServiceNow O365 Email). 
  • In the left pane, click on Certificates & Secrets, select the Client Secrets tab and then click New Client Secret>>>Description (SNOW Office 365 SMTP account)>>>select the Expiration Date (12 months) from the drop-down arrow >>>click Add. 
  • Note: Copy the generated Secret Value and save it in a document for use in ServiceNow; you will not be able to view the Secret value again once the Client Secret setup has been completed. 
  • The four values from Azure AD App Registration needed for connecting with ServiceNow are the Application/Client ID (not the Secret ID), Secret Value, OAuth 2.0 Token Endpoint (V2) URL. (https://login.microsoftonline.com/[Directory (Azure Tenant) ID]/oauth2/v2.0/token), and OAuth 2.0 Authorization Endpoint (V2) URL (https://login.microsoftonline.com/[Directory (Azure Tenant) ID]/oauth2/v2.0/authorize). 
  • To obtain the the Token URL for ServiceNow, navigate to Azure AD>>>App Registrations>>>select the registered application>>>Overview>>>click on Endpoint tab>>>copy the URL under OAuth 2.0 Token Endpoint (V2).
  • To obtain the the Authorization URL for ServiceNow, navigate to Azure AD>>>App Registrations>>>select the registered application>>>Overview>>>click on Endpoint tab>>>copy the URL under OAuth 2.0 Authorization Endpoint (V2).

Configure Microsoft Graph OAuth Scopes and Permissions on the Registered Application and Authorize Them

  • Configuring the OAuth scope and permissions will allow Microsoft Identity Platform to use OAuth 2.0 to help third-party app, such as ServiceNow, to access web-hosted resources, such as Microsoft Graph, on behalf of a user. The setup also allows for defined set of permissions for Microsoft Graph to be selected to divide the functionality of that resource into smaller chunks to ensure that the external application is given only the access it requires to operate correctly. For example Microsoft Graph has permissions such permission to read a user’s calendar, permission to write to a user’s calendar, and permission to send mail as a user.
  • Within the registered application, click on Manage >>>select API Permissions >>>click Add a Permission. From the list of APIs, select Microsoft Graph>>>click on Delegated Permissions; now you can navigate through the list and select for Open ID (offline_access), SMTP (select SMTP.Send) scope as well as IMAP.AccessAsUser.All scope. 
  • The Microsoft Graph scopes for ServiceNow OAuth setup in Azure AD App Registry include; 
  •  IMAP.AccessAsUser.All scope – API/Permissions Name (IMAP.AccessAsUser.All); Type (Delegated); Admin Consent Request (No); 
  • offline_access scope – API/Permissions Name (offline_access);  Type (Delegated); Admin Consent Request (No); 
  • SMTP.Send scope –  API/Permissions Name (SMTP.Send);  Type (Delegated); Admin Consent Request (No); 
  • User.Read default scope; API/Permissions Name (User.Read);  Type (Delegated); Admin Consent Request (No);  (This is automatically created by Azure AD).
  • Each delegated permission to each scope will need to be approved by the Azure Global Administrator for access to the application within the Azure tenant. Click on the Grant Admin Consent

Configure OAuth 2.0 in ServiceNow for Microsoft Office 365

  • While Azure AD is the source, this step allows you to create a client version of the API permission scopes, that were created in Azure AD, in ServiceNow. In your ServiceNow instance, make sure ServiceNow plugin for Email OAuth (com.glide.email.oauth) has been installed, if not, navigate to System Definition>>>Plugins>>>search for com.glide.email.oauth and click Install for Email-OAUTH Support for IMAP and SMTP. 
  • Once the plugin has been installed, search for System OAuth>>>click on Application Registry >>>click New>>>select Connect to a third party OAuth Provider (referring to Azure AD) and then fill the form.
  • Name (ServiceNow O365 Email OAuth); Client ID (Application ID of Azure AD registered application; ServiceNow O365 Email); Client Secret (Provide client secret value of Azure AD registered application); OAuth API Script (); Default Grant Type (Authorization code); Refresh Token Lifespan (8640000); Application (Global); Accessible from (All application scopes); Active (Yes); 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 /https://dev119391.service-now.com/oauth_redirect.do; Use Mutual Authentication (No/Unchecked); Send Credentials (In Request Body[Form URL Encoded])>>>click Save. 
  • Once you click Save, the OAuth Entity Profile for that application will be created automatically as ServiceNow O365 Email OAuth default_profile. 

Create ServiceNow OAuth Entity Scopes

  • Within the application that has been registered in ServiceNow (ServiceNow O365 Email OAuth), navigate to the bottom of the screen, click on the OAuth Entity Scopes tab and create the following scopes to match the API permission scopes created in the ServiceNow O365 Email OAuth in Azure AD;
  • Name (IMAP.AccessAsUser.All); OAuth Scope (https://outlook.office.com/IMAP.AccessAsUser.All)
  •  Name (SMTP.Send); OAuth Scope (https://outlook.office.com/SMTP.Send)
  • Name (offline_access); OAuth Scope (offline_access)
  • Click Save to save the changes that have been made. 

Create The Corresponding OAuth Entity Scopes in the Default ServiceNow OAuth Profile

  • Within the application that has been registered in ServiceNow (ServiceNow O365 Email OAuth), navigate to the bottom of the screen, click on the OAuth Entity Profile tab and click on the default OAuth profile to open it; ServiceNow O365 Email OAuth default_profile.
  • Create the following OAuth Entity scope names; IMAP.AccessAsUser.All, SMTP.Send, and offline_access. 
  • Note: The OAuth Entity scope URLs will not work, and so enter only the OAuth Entity scope names instead. 
  • Click Save to save the changes that have been made. 

Verify with POST MAN

  • Before creating the ServiceNow OAuth SMTP and OAuth IMAP accounts, very that you are able to obtain access and refresh tokens using POST MAN.
  •  

Create ServiceNow SMTP OAuth Azure / Office 365 Email Account

  • The ServiceNow mailbox system is setup such that it can receive email to the default ServiceNow Office 365 account, using the ServiceNow POP3, ServiceNow SMTP or ServiceNow Office 365 SMTP; which use Basic authentication. 
  • To switch to ServiceNow OAuth 2.0, disable the ServiceNow POP3, ServiceNow SMTP or ServiceNow Office 365 SMTP (using Basic authentication) and create ServiceNow SMTP  and IMAP Office 365 email accounts that use OAuth 2.0; SMTP will be for sending emails and IMAP will be used for receiving emails just like POP3 does.
  • To create ServiceNow SMTP OAuth Office 365 email account, navigate to System Mailbox >>> Administration >>>   Email Accounts>>>click New.  
  • Name (ServiceNow OAuth Office 365 SMTP); Type (SMTP); Authentication (OAuth 2.0); User Name (skoanow@gmail.com); OAuth Profile (ServiceNow O365 Email OAuth default_profile); Server (SMTP.Office365.com); Connection Security (SSL/TLS); Port (587).
  • Click Authorize Email Account Access to obtain the access and refresh tokens; another browser window will open asking you to authorize the account access on the third-party (Microsoft Office 365) email account. Now authorize the access to allow the account to use OAuth to send and receive emails in ServiceNow using the credentials of the email account.
  • Note: You should be logged into ServiceNow with System Administrator or Admin role otherwise the authorization will fail. 
  • Once the authorization is successful and the tokens are saved to the instance, the Authorize Email Account Access button no longer appears on the Email Account form.

Create ServiceNow IMAP OAuth Azure / Office 365 Email Account

  • To create ServiceNow IMAP OAuth Office 365 email account, navigate to System Mailbox >>> Administration >>>   Email Accounts>>>click New.  
  • Name (ServiceNow OAuth Office 365 IMAP); Type (IMAP); Authentication (OAuth 2.0); User Name (Email@skoanowtechnologies.com); OAuth Profile (ServiceNow O365 Email OAuth default_profile); Server (Outlook.Office365.com); Connection Security (SSL/TLS); Port (993).
  • Click Authorize Email Account Access to obtain the access and refresh tokens; another browser window opens asking you to authorize the account access on the third-party (Microsoft Office 365) email account. Now authorize the access to allow the account to use OAuth to send and receive emails. 
  • Once the authorization is successful and the tokens are saved to the instance, the Authorize Email Account Access button no longer appears on the Email Account form.
  • After a valid refresh token is available, the scheduled job named “Refresh email access token” will run every 3 minutes to check and get the new Access token.

Troubleshooting OAuth Setup; AADSTS50011: The redirect URI "https://skoanowtechnologies.com/oauth_redirect.do" specified in the request does not match the redirect URIs configured for the application '4aXXXXXXXXXXXXXXX'

  • This error message is displayed if an alias URI; https://skoanowtechnologies.com/oauth_redirect.do,  is used for the organization’s ServiceNow portal in addition to the default ServiceNow URI; https://skoanow.service-now.com/oauth_redirect.do. Both URIs need to be added to the Enterprise application that is created in Azure Active Directory. If only one of the URIs is added, then when you click on the Authorize Email Account Access button while logged into the URL portal which was not added, then the AADSTS50011 error message will be displayed.
  • To resolve this issue, log into Azure Active Directory as the Global administrator, click on Manage>>select App Registration>>search for the registered Enterprise application; ServiceNow O365 Email;  Redirect URI (optional) (select Web from the drop down and in the add the OAuth URI, https://skoanow.service-now.com/auth_redirect.do). 

Troubleshooting OAuth Setup; Connection Failed. Email sender connection invalid.:Cannot connect to SMTP server: smtp.office365, as: skoanow@skoanowtechnologies.com, message: failed to connect.

  • This error message is displayed if an alias URI; https://skoanowtechnologies.com/oauth_redirect.do,  is used for the organization’s ServiceNow portal in addition to the default ServiceNow URI; https://skoanow.service-now.com/oauth_redirect.do. Both URIs need to be added to the Enterprise application that is created in Azure Active Directory. If only one of the URIs is added, then when you click on the Authorize Email Account Access button while logged into the URL portal which was not added, then the AADSTS50011 error message will be displayed.
  • To resolve this issue, log into Azure Active Directory as the Global administrator, click on Manage>>select App Registration>>search for the registered Enterprise application; ServiceNow O365 Email;  Redirect URI (optional) (select Web from the drop down and in the add the OAuth URI, https://skoanow.service-now.com/auth_redirect.do).