ServiceNow Connector — Authentication Guide

Last updated: 2026-03-25

Relates to: sv0-connectors#16, sv0-connectors#9

---

Why this matters

The ServiceNow connector was originally configured with HTTP Basic Authentication (username + password). This is not acceptable for enterprise or production deployments:

• Passwords are long-lived secrets — a compromised credential provides indefinite access
• Large organisations (Inetum and others) prohibit service accounts with stored passwords
• Basic Auth does not meet modern security standards for API integrations
• It cannot be scoped to specific API access — it grants the user's full permissions

The default authentication method for all new deployments is now OAuth 2.0 Client Credentials. Basic Auth is retained only as a fallback for older ServiceNow versions (pre-Washington DC) or isolated development instances.

---

Supported Authentication Methods

Method	SERVICENOW_AUTH_METHOD value	Production use?	Minimum ServiceNow version
OAuth 2.0 Client Credentials	oauth2_client_credentials	Yes — recommended	Washington DC (2024)
API Key	api_key	Limited — see tradeoffs below	Any
HTTP Basic Auth	basic	Dev/eval only	Any

---

Option 1: OAuth 2.0 Client Credentials (Production)

How it works

1. An Inbound Integration is created in ServiceNow using the OAuth 2.0 — Client Credentials grant (one-time setup by a ServiceNow admin)
2. The connector authenticates by POSTing grant_type=client_credentials to /oauth_token.do
3. ServiceNow returns a short-lived Bearer token (~30 minutes)
4. The connector caches and auto-refreshes the token (refreshes 60 seconds before expiry)
5. All API requests use Authorization: Bearer <token> — no password is ever transmitted after setup

Step 1 — ServiceNow admin: create the Inbound Integration

1. Log in to your ServiceNow instance as an administrator

2. Navigate to System OAuth → Application Registry

3. Click New → select "Create an OAuth API endpoint for external clients"

   This creates an Inbound Integration — it allows an external system (SecurityV0) to authenticate into ServiceNow using OAuth.

4. Fill in the form:

   • Name: SecurityV0 Connector (or similar)
   • Grant type: select Client Credentials — "Used for machine-to-machine access to the application without the user's context." This is the correct grant for automated connectors with no interactive user.
   • Client ID: auto-generated, or set a recognisable value
   • Client Secret: auto-generated — copy this securely
   • Accessible from: All application scopes
   • Active: checked

5. Under OAuth Entity Scopes, verify or add the scope that covers REST API access.

   The scope must match what the connector will request. The default ServiceNow scope (useraccount) is sufficient for most read-only Table API access. If your instance enforces custom scopes, ensure the scope grants read access to:

   • sys_script — Script Includes
   • sysauto_script — Scheduled Scripts
   • sys_rest_message — REST Messages
   • sys_rest_message_fn — REST Message Functions

   The OAuth token the connector receives must carry this scope. If the token scope does not cover these tables, API calls will return 403 errors even with a valid token.

6. Save and note the Client ID and Client Secret

Minimum version note: Inbound OAuth 2.0 Client Credentials was introduced in the Washington DC (2024) release. If your instance is on an earlier release, upgrade or use Basic Auth as a temporary measure only.

Step 2 — Set environment variables

SERVICENOW_INSTANCE=your-instance      # without .service-now.com
SERVICENOW_AUTH_METHOD=oauth2_client_credentials
SERVICENOW_CLIENT_ID=<from step 1>
SERVICENOW_CLIENT_SECRET=<from step 1>

# Leave these unset (or commented out) for OAuth deployments:
# SERVICENOW_USERNAME=
# SERVICENOW_PASSWORD=

Step 3 — Verify the connection

Start the connector and check the logs for:

INFO - ServiceNow auth: OAuth 2.0 Client Credentials
INFO - ServiceNow OAuth2 token acquired

If you see ServiceNow OAuth2 token acquired on startup, the token exchange succeeded and all subsequent API calls will use Bearer auth.

If the token exchange fails, check:

• The instance URL is correct (SERVICENOW_INSTANCE should be just the subdomain, e.g. acmecorp)
• The Application Registry entry is active and accessible
• The grant type is set to Client Credentials (not Authorization Code)
• The client secret was copied without trailing whitespace
• The OAuth token scope matches what the connector requests
• The ServiceNow instance is on Washington DC or later

---

Option 2: API Key

How it works

ServiceNow supports API keys as a lightweight alternative for authenticating REST API calls. An API key is a long-lived static token tied to a specific user or integration.

Step 1 — ServiceNow admin: create an API key

1. Log in to your ServiceNow instance as an administrator

2. Navigate to System Web Services → API Keys (or search for API Keys in the application navigator)

   Note: The API Keys module requires the com.glide.api_key plugin to be active. If you do not see this module, check with your ServiceNow admin or use OAuth instead.

3. Click New and fill in:

   • Name: SecurityV0 Connector
   • Assigned to: a dedicated integration service account (not a personal user)
   • Active: checked

4. Save and copy the generated API key value — it is shown only once.

Step 2 — Set environment variables

SERVICENOW_INSTANCE=your-instance
SERVICENOW_AUTH_METHOD=api_key
SERVICENOW_API_KEY=<from step 1>

---

API Key vs OAuth Tradeoffs

Both methods authenticate the connector to ServiceNow, but they differ significantly in what they can access.

Property	API Key	OAuth 2.0 Client Credentials
Setup complexity	Low	Medium
Credential lifetime	Long-lived (static)	Short-lived (~30 min token, auto-refreshed)
Credential exposure per request	Yes — key sent on every call	No — key exchanged once for a short-lived token
Compromise window	Indefinite until revoked	~30 minutes
Audit trail	Limited	Yes — token issuance logged in ServiceNow OAuth log
Meets "no stored password" enterprise policies	Partially	Yes
Access to Table API (/api/now/table/)	No — blocked	Yes
Access to execution metadata (sys_script, sysauto_script, sys_rest_message)	Severely limited	Full read access

Why the Table API matters

The ServiceNow Table API (/api/now/table/) is the primary mechanism SecurityV0 uses to read automation metadata — script records, scheduled jobs, REST message configurations, and execution logs. API keys cannot access the Table API. ServiceNow restricts Table API access to sessions authenticated via OAuth or Basic Auth.

This means an API key deployment will produce significantly fewer findings:

• Scheduled scripts (sysauto_script) — inaccessible via API key
• Script Includes (sys_script) — inaccessible via API key
• REST Message definitions (sys_rest_message) — inaccessible via API key
• Execution logs and audit records — inaccessible via API key

An API key connector sees only a fraction of the automation surface. It is acceptable for quick connectivity testing or environments where OAuth cannot yet be configured, but should not be used in production where completeness of findings matters.

Use OAuth 2.0 Client Credentials for all production deployments.

---

Option 3: Basic Authentication (Dev/Eval Only)

Basic Auth is supported as a fallback for development instances or older ServiceNow versions. Do not use in any environment accessible to customers or containing real data.

SERVICENOW_INSTANCE=dev12345
SERVICENOW_AUTH_METHOD=basic           # explicitly set, or leave unset (default)
SERVICENOW_USERNAME=integration_user
SERVICENOW_PASSWORD=your-password

---

Migrating an Existing Deployment

If you are running a deployment that currently uses Basic Auth and want to migrate to OAuth:

1. Ask the ServiceNow admin to create the Inbound Integration with Client Credentials grant (Step 1 above)
2. Obtain the new CLIENT_ID and CLIENT_SECRET
3. Update your environment / secrets manager:
   • Set SERVICENOW_AUTH_METHOD=oauth2_client_credentials
   • Add SERVICENOW_CLIENT_ID and SERVICENOW_CLIENT_SECRET
   • Remove (or comment out) SERVICENOW_USERNAME and SERVICENOW_PASSWORD
4. Restart the connector and confirm ServiceNow OAuth2 token acquired appears in the logs
5. After confirming OAuth works, delete the integration service account from ServiceNow

No code changes are required — the switch is entirely configuration-driven.

---

Roadmap: Further Hardening

The OAuth 2.0 Client Credentials flow is the immediate priority (addresses the Inetum requirement). Further hardening options are planned:

Option	Issue	Priority	When to use
Mutual TLS (mTLS)	sv0-connectors#12	P3	Customers that prohibit any shared secret
OAuth 2.0 with JWT Bearer	Planned	P3	Eliminates long-lived client secret
Pluggable auth interface	sv0-connectors#11	P2	Clean architecture for all auth methods

See the connector authentication integration plan for the full phased roadmap.

---

Security Properties Summary

Property	Basic Auth	API Key	OAuth 2.0 Client Credentials
Long-lived credential exposed per request	Yes	Yes	No (Bearer token is short-lived)
Credential compromise window	Indefinite	Indefinite	~30 minutes
Table API access	Yes	No	Yes
Full automation metadata coverage	Yes	No — severely limited	Yes
Can be scoped to specific access	No	No	Partially (OAuth scopes)
Audit trail of token issuance	No	No	Yes (ServiceNow OAuth log)
Meets enterprise "no stored password" policies	No	No	Yes