Step-by-Step configuration of an Email account using OAuth 2.0 in ServiceNow

As a ServiceNow Admin or Developer, you can connect your ServiceNow environment to a Business Google Mail account as inbound so you can receive emails and process them as cases, incidents and other task types.

The configuration is not straightforward requires activities in ServiceNow and Google Console. The following guide outlines each configuration step required to integrate a Google Workspace (Gmail) account with ServiceNow for incoming email using OAuth 2.0, including the rationale and dependencies for each step.

Step 1: Install Required Plugin

As per default, you can create a new Email Account for an IMAP mailbox only using username and password. To enable the OAuth 1.0 and OAuth 2.0 options, you need to install a ServiceNow plugin.

OAuth (Open Authentication) is a secure way to connect ServiceNow to third-party email providers like Gmail without storing usernames and passwords. Instead, it uses access and refresh tokens to authorise sending and receiving emails via IMAP and SMTP. These tokens are saved in the system, and ServiceNow automatically refreshes them when needed to keep the connection active.

Action:

Navigate to System Definition > Plugins and activate: Email: OAUTH support for IMAP, Microsoft Graph (Receiving), and SMTP(com.glide.email.oauth).

This plugin enables OAuth 2.0 support specifically for ServiceNow’s email (IMAP/SMTP) integrations. It must be installed before setting up email accounts that use OAuth.

---

Step 2: Create OAuth 2.0 Credentials in Google Cloud

Google requires OAuth credentials to authorize third-party applications like ServiceNow to access Gmail accounts. This is required configuration before configuring OAuth Providers in ServiceNow.

The Google Cloud Console is a web-based interface that lets you manage your Google Cloud projects and resources. You can create a new project or select an existing one, and then work with resources within the context of that project. In our case, ServiceNow Email Account acts a Web Application that reads Google data.

Actions:

• Go to Google Cloud Console
• Create a project or select an existing one
• Navigate to APIs & Services > Credentials
• Click Create Credentials > OAuth client ID
  
• Choose Web Application and set the Authorized redirect URI to:
  • https://<your-instance>.service-now.com/oauth_redirect.do
  • Save the Client ID and Client Secret

When you configure OAuth 2.0 in Google Cloud, you must set up an OAuth Consent Screen. This screen defines how your app requests access to user data and who is allowed to use it. You will find different publishing status under Audience.

Testing Mode is the default state when you first set up the consent screen. You must manually add test users (by email address) who are allowed to authorize your app. Tokens (especially refresh tokens) can behave differently or be limited in duration. Means, in Testing Mode you probably will not receive refresh tokens and will need to manually refresh tokens (Authorize) in the newly created Email Account. That’s fine for testing but once your integration works and you’re going live, you should publish the consent screen to avoid manual user management and ensure long-term stability.

Note: In the Test mode, if the Gmail account you’re using in ServiceNow is not added as a test user, the authorization will fail with a 403: access_denied error.

---

Step 3: Enable Gmail API

You need to grant ServiceNow permissions to read email via Gmail. This is done in your Google account.  Must be done before ServiceNow can retrieve tokens to access Gmail.

The Gmail API is a RESTful API that allows you to access Gmail mailboxes and send emails. For most web applications, it is the preferred method for authorized access to a user’s Gmail data. Typical use cases including reading and extracting emails for indexing or backups, automated sending of messages, migrating email accounts, organizing emails, e.g., by filtering and sorting, and managing consistent email signatures across an organisation.

Actions:

• Go to Google Cloud Console
• Go to APIs & Services > Library
• Enable the Gmail API for your project
  

---

Step 4: Configure OAuth Provider in ServiceNow

Next, define how ServiceNow communicates with Google’s OAuth service. OAuth is a secure authorization method that allows users to grant external applications access to their data without sharing their login credentials. Instead of repeatedly entering usernames and passwords, OAuth uses tokens to authorize requests, making the process both safer and more efficient.

When integrating Gmail with ServiceNow for email processing, OAuth lets ServiceNow access Gmail accounts securely using tokens instead of storing sensitive credentials. This improves security, supports compliance, and ensures stable, automated communication between ServiceNow and Gmail.

Actions:

• Go to System OAuth > Application Registry
• Create a new record using Connect to a third-party OAuth Provider
• Fill in:
  
  • Name: Gmail OAuth
  • Client ID / Secret: From Google Cloud Console
  • Token URL: https://oauth2.googleapis.com/token
  • Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
    
  • Redirect URL: https://<your-instance>.service-now.com/oauth_redirect.do
  • Default Grant Type: Authorization Code
    
    

---

Step 5: Create OAuth Entity Profile

As next, wen need to tie a specific scope and grant type to the OAuth provider for email authentication.

In an OAuth setup, profiles and scopes define how access is granted and what level of access is allowed.

An OAuth profile combines a grant type with one or more scopes. The scope defines what the application can do with the user’s data—for example, read or write access. Each third-party provider (like Google) can have its own profile, using scopes specific to that provider. When you create a third-party OAuth provider in ServiceNow, the system automatically creates a default profile for it. Only one default profile is allowed per provider, and these profiles are also used when making REST API calls that require OAuth 2.0 authentication.

We must define an OAuth profile that includes the correct grant type and Gmail-specific scopes to securely connect ServiceNow to Gmail using OAuth. This ensures that ServiceNow has the right permissions to access and process emails.

Actions:

• Go to System OAuth > Application Registry
• Create a new OAuth Entity Profile
• Fill in:
  
  • OAuth Provider: Gmail OAuth
  • Grant Type: Authorization Code
  • Scope: https://mail.google.com/

---

Step 6: Extend OAuthUtil Script Include (for Refresh Token Parameters)

Google only returns a Refresh Token if these parameters are included, and ServiceNow UI doesn’t allow them by default. You can include them by writing your own OAuth API Script. Make sure OAuth Provider already exists.

The OAuthUtil Script Include is used to adjust request parameters and handle the token response at runtime. If an external OAuth provider returns a response in a format other than application/json, you can create a custom version of this script to properly parse that response. To do this, extend or copy the original OAuthUtil Script Include, then reference your custom version in the OAuth API Script field of the Application Registry for your third-party OAuth provider.

Note: The name of your custom Script Include must begin with “OAuth” for ServiceNow to recognize it.

Actions:

• Go to System Definition > Script Includes
• Create a new Script Include:
  • Name: CustomOAuthUtil
  • Accessible from: All Application Scopes
  • Script:
    

var CustomOAuthUtil = Class.create();

CustomOAuthUtil.prototype = Object.extendsObject(OAuthUtil, {
   interceptRequestParameters: function(requestParamMap) {
      requestParamMap.put('access_type', 'offline');
      requestParamMap.put('prompt', 'consent');
      this.preprocessAccessToken(requestParamMap);
   },
   type: 'CustomOAuthUtil'
});

• Assign this script to the OAuth API Script field on your OAuth Provider record.
  

---

Step 7: Configure IMAP Email Account in ServiceNow

And now we start configuring the email Account that will import Emails from you business google mail. Here you define how ServiceNow connects to Gmail IMAP and authenticates via OAuth.

Actions:

• Go to System Mailboxes > Administration > Email Accounts
• Create a new record:
  
  • Name: Gmail Business Incoming
  • Incoming Mail Server: imap.gmail.com
  • Port: 993
  • Security Protocol: SSL
  • Use OAuth: ✅
  • OAuth Entity Profile: Gmail OAuth Profile
  • User: Full Gmail business email address (e.g. user@yourdomain.com), same as you use to authenticate at your google business account.
    

---

Step 8: Authorize OAuth and Test the Connection

Finally, let’s ensuree ServiceNow can securely authenticate and connect to Gmail using the full OAuth flow. All previous steps must be completed. OAuth credentials, scopes, and profile must be valid. Let’s test the connection.

Actions:

• Revoke any previous OAuth access via Google Permissions
• Delete previous tokens in ServiceNow at System OAuth > Manage Tokens
• In OAuth Entity Profile, click Get OAuth Token
• In Email Account, click Authorize Email Account Access and then Test Connection
  

---

⚠️ Known Issues and Solutions

I faced some issues and pitfalls during the configuration. Please note, there might be other problems on your way. Let me know so I can extend the list.

• Redirect URI Mismatch (Error 400):
  
  • Ensure ServiceNow and Google have an exactly matching redirect URI.
    
• “OAuth Access or Refresh tokens are not available” warning:
  
  • Typically caused by missing refresh token. Fix by using the custom Script Include and revoking prior Google OAuth access.
    
• “Invalid SASL Argument” during IMAP Connection:
  
  • Caused by incorrect port or missing “User” field. Use port 993, SSL, and specify full Gmail address.
    

---

📌 Useful References

• Google OAuth 2.0 Docs
  
• Google Account Permissions
  
• ServiceNow KB Article (KB0792354)
  

---

✅ Final Check (for stability):

• Go to System OAuth > Manage Tokens
  • Confirm both Access and Refresh Tokens exist
    
• Monitor System Logs > Emails to verify ongoing successful message retrieval beyond the 1-hour token window
  
• If only Access Token is present, reauthorize after revoking permissions in Google to retrieve Refresh Token
  

---

This process ensures a secure and stable connection between ServiceNow and Gmail using OAuth 2.0 for enterprise-level, password-less IMAP authentication. I hope this guide will help your ServiceNow administration and maintenance. If you have any problems or comments to the approach, please let me know so I can share it with the community.

Kostya Bazanov, Managing Director, Mar 31, 2025

Eager to take the next step? Contact us today!

Privacy policy (GDPR)

* Required fields

Submit