Connect to ServiceNow

TL;DR

• Connect your ServiceNow instance to receive and manage incidents automatically
• Choose between Basic Authentication (username/password) or OAuth 2.0 Client Credentials (token-based, recommended for production)
• Once connected, your agent acknowledges, investigates, and updates ServiceNow incidents

Time: 15 minutes

Prerequisites

Before you begin, make sure you have:

• An Azure SRE Agent created and running
• A ServiceNow instance with admin access
• For OAuth 2.0 Client Credentials: An OAuth application registered in ServiceNow with a client ID and client secret
• For Basic Authentication: A ServiceNow user with incident management permissions
• Contributor on the SRE Agent resource to save connector settings
• For portal-managed OAuth API Connections: Owner or User Access Administrator at the resource group or subscription scope, in addition to Contributor, so the portal can grant the agent's runtime managed identity Logic App Contributor on the connection

Choose your authentication method

Method	Security	Best for	Setup time
OAuth 2.0 Client Credentials	Token-based, automatic refresh, no stored passwords	Production environments, security-conscious teams	~10 min
Basic Authentication	Username and password stored	Quick setup, dev/test environments	~5 min

Recommendation

OAuth 2.0 Client Credentials is recommended for production use. Tokens refresh automatically, and no user password is stored in your agent configuration.

---

Option A: Connect with OAuth 2.0 Client Credentials

Prepare ServiceNow for Client Credentials

With Client Credentials, the agent signs in as the OAuth Application User set on your OAuth application. Before connecting from the portal, create that user and an OAuth application in your ServiceNow instance:

1. In ServiceNow, go to User Administration → Users and create a dedicated service account. Don't use admin.
   • A recognizable username (e.g., sre-agent-integration)
   • Active: Checked
   • Web service access only: Checked
   • Internal Integration User: Checked, where your ServiceNow release provides this field
2. Assign roles to the service account based on what you want the agent to do. See ServiceNow permissions.
3. Set the system property glide.oauth.inbound.client.credential.grant_type.enabled to true. If it doesn't exist, create it in sys_properties.list with type true | false. Without this property, every token request fails with 401 server_error.
4. Navigate to System OAuth → Application Registry, select New, and choose Create an OAuth API endpoint for external clients
5. Fill in:
   • Name: A descriptive name (e.g., Azure SRE Agent)
   • Active: Checked
6. Click Submit, then reopen the application. If Default Grant type, OAuth Application User, or Scope Restriction isn't shown, add it with Configure → Form Design.
7. Set these fields, then save:
   • Default Grant type: Client Credentials
   • OAuth Application User: The service account from step 1
   • Scope Restriction: No restrictions. The agent calls unscoped Table APIs, so with Securely scoped, every call fails with 403 Access to unscoped api is not allowed. The service account's roles still control what the agent can access.
8. Note:
   • Client ID — displayed on the application page
   • Client Secret — click the lock icon to reveal; copy it immediately

warning

The Client Secret is shown only once in some ServiceNow versions. Copy it before navigating away.

Configure in the portal

1. Navigate to your agent in the Azure SRE Agent portal
2. In the left navigation, select Incidents → Connect an incident platform
3. In the wizard, select ServiceNow

Switching platforms

If another platform is already connected, a confirmation dialog appears. Confirm to disconnect the current platform before proceeding. Only one incident platform can be active at a time.

4. Set Authentication Type to OAuth 2.0 Client Credentials (Service Account)
5. Enter your ServiceNow details:
   • ServiceNow endpoint: Your instance URL (e.g., https://your-instance.service-now.com)
   • OAuth Client ID: From your ServiceNow OAuth application
   • OAuth Client Secret: From your ServiceNow OAuth application
   • Service Account Username (optional): The service account's username. The agent uses it only to set Assigned to when it acknowledges an incident. It doesn't change which user the agent signs in as.

6. Click Next, complete the optional Generate insights step, then click Save.

Verify your connection

After saving, the Incidents page shows a green "ServiceNow is connected." status indicator. Your agent can now receive and manage incidents from ServiceNow.

Checkpoint: Open the platform connection menu on the Incidents page to see Edit and Disconnect, confirming the connection is active.

What you unlocked

Your agent can now automatically receive, investigate, and update ServiceNow incidents. Set up response plans to control which incidents your agent handles.

---

Option B: Connect with Basic Authentication

Create a ServiceNow integration user

Create a dedicated user in ServiceNow for the agent:

1. In ServiceNow, go to User Administration → Users

2. Create a new user with:

   • A recognizable username (e.g., sre-agent-integration)
   • A strong password
   • Active: Checked
   • Web service access only: Checked, so the account can call the API but can't sign in to the ServiceNow UI
   • Internal Integration User: Checked, where your ServiceNow release provides this field
   • Password needs reset and Locked out: Cleared

   Web service access only and Internal Integration User are separate settings. Set both. If either field isn't shown on the user form, add it to the form layout.

3. Assign roles based on what you want the agent to do. See ServiceNow permissions.

tip

Use a dedicated integration user rather than an administrator account. ServiceNow records every change the agent makes under this user, which keeps the audit trail clear.

Reading incident attachments

To let the agent list and download files attached to an incident, the account the connection authenticates as also needs read access to the sys_attachment table, on top of its incident access. Without it, incident operations keep working but attachment reads fail or return nothing.

Configure in the portal

1. Navigate to your agent in the Azure SRE Agent portal
2. In the left navigation, select Incidents → Connect an incident platform
3. In the wizard, select ServiceNow
4. Leave Authentication Type as Basic Authentication (default)
5. Enter your ServiceNow details:
   • ServiceNow endpoint: Your instance URL (e.g., https://your-instance.service-now.com)
   • Username: The integration user's username
   • Password: The integration user's password
6. Click Next, complete the optional Generate insights step, then click Save.

Verify your connection

The portal validates connectivity automatically. You should see a green "ServiceNow is connected." status indicator on the Incidents page.

---

Set up response plans

Once ServiceNow is connected, create response plans to define how your agent handles incidents.

You can optionally enable Quickstart response plan during setup, which creates a default response plan for high-priority incidents automatically.

note

Your agent doesn't pick up any ServiceNow incidents until at least one response plan exists. If the Quickstart response plan option isn't shown during setup, create a response plan manually. Every response plan needs a handling agent, which you choose in Response subagent. It can be your main agent (listed as Meta Agent) or one of your subagents. The quickstart response plan uses the main agent.

When you enable Quickstart response plan, your agent creates a default plan based on the platform:

Platform	Default plan handles	Autonomy level
ServiceNow	Critical (Priority 1) incidents	Autonomous
Azure Monitor	Sev3 alerts	Autonomous
PagerDuty	P1 incidents	Autonomous

ServiceNow priority values:

Priority	ServiceNow value	Label
Critical	1	Critical
High	2	High
Moderate	3	Moderate
Low	4	Low
Planning	5	Planning

---

What your agent can do with ServiceNow

Once connected, your agent interacts with ServiceNow incidents throughout their lifecycle:

Capability	Description
Read incidents	Fetch incident details, related records, and customer-visible comments. When the agent looks up a specific incident, it sees every field the connection's account can read, including custom u_* fields. Journal fields aren't included. To keep a field from the agent, don't grant the account read access to it.
Post discussion entries	Add investigation findings and updates as work notes or customer-visible comments
Acknowledge incidents	Mark incidents as acknowledged when investigation begins
Change priority	Adjust incident priority based on investigation findings
Resolve incidents	Close incidents with resolution notes after successful mitigation

---

ServiceNow permissions

The agent calls the ServiceNow Table API as the ServiceNow user that the connection signs in as. ServiceNow access control lists (ACLs) on that user determine what the agent can do:

• Basic Authentication: The integration user whose username you enter.
• OAuth 2.0 Client Credentials: The OAuth Application User set on your OAuth application. The optional Service Account Username in the portal doesn't change this user.
• Portal-managed OAuth API Connections: The ServiceNow user who signs in when you authorize the connection.

Grant only the roles required for the scenarios you plan to use.

Permissions by scenario

Scenario	Required roles	Tables and fields	Behavior
Connect and validate	itil (or any role with read access to incident)	incident (read)	The connection check queries the incident table with a limit of one to confirm that the credentials work. An empty result still counts as connected.
Pick assignment groups	itil (or any role with read access to sys_user_group)	sys_user_group (read)	Optional. The portal lists active assignment groups in the Generate insights step and in response-plan assignment-group filters. If the user can't read them, the portal reports The assignment-group request failed with 403 Forbidden. The connection still works.
Filter response plans on custom fields	A role with read access to each custom field you filter on	Selected incident.u_* fields (read); sys_dictionary (read, optional)	The agent filters on the values ServiceNow returns for these fields. If ServiceNow hides a field's value from the user, the incident doesn't match and is skipped. The portal reads sys_dictionary to suggest custom fields. Without it, enter the u_* field name manually.
Read incidents only	itil and snc_read_only	incident, sys_journal_field (read)	The agent receives, investigates, and reads incidents that match your response plans, including their customer-visible comments. Without read access to sys_journal_field, the agent reads incidents without their comments. ServiceNow rejects all write operations with 403 Forbidden, and the incident record isn't modified.
Acknowledge incidents	itil	incident.state, incident.comments, incident.assigned_to (write)	Sets State to In Progress and adds a customer-visible comment that the incident was acknowledged. If the connection has a username (the Basic Authentication username, or the optional Service Account Username for OAuth 2.0 Client Credentials), also sets Assigned to to that user. Otherwise, including for portal-managed OAuth API Connections, Assigned to isn't changed.
Post discussion entries	itil	incident.work_notes, incident.comments, incident.state (write)	Adds one entry per call, either as an internal work note (the default) or as a customer-visible comment. The request resends the incident's current State value, unchanged. Entries aren't posted to resolved or closed incidents.
Update incident fields	itil	Target fields on incident (write)	Rejects requests that include state, incident_state, or a journal field (work_notes, comments, work_notes_list, comments_and_work_notes). Use acknowledge and resolve to change State, and post discussion entries for journal entries. Every other field is sent to ServiceNow as requested, including close_code, close_notes, and resolved_at. ServiceNow ACLs and business rules decide whether each change is applied. Custom fields protected by field-level ACLs may require additional roles.
Resolve incidents	itil	incident.state, incident.close_code, incident.close_notes, incident.resolved_at (write), plus any custom u_* columns the agent sends	Sets State to Resolved, records the resolution time, and adds the agent's resolution notes. The agent keeps the connection's default close code and sets no other columns unless your instructions name them or your instance requires them on resolve (such as a custom cause code); then it sets them in the same update. Only custom u_* columns can be set this way; built-in fields such as assignment group or priority can't be changed by a resolve. When a resolve fails because fields are mandatory, the agent reads the incident form metadata (/api/now/ui/meta/incident, readable with itil) to find each field's column and valid values. Over a portal-managed OAuth API Connection, the metadata has the columns but not the valid values. Extra columns are governed by rules and PreToolUse hooks on ResolveServiceNowIncident; rules and hooks on UpdateServiceNowIncident don't apply. Incidents that are already resolved or closed aren't changed. See Limit what a resolve can set and Limitations.
Create problems, problem tasks, change requests, or catalog tasks	Not supported	Not applicable	The agent works only with the incident table.

Read-only posture

The snc_read_only role blocks write access that other roles grant. To let the agent investigate without modifying ServiceNow, assign itil together with snc_read_only. To enable acknowledge, update, and resolve, remove snc_read_only and keep itil.

Stricter least privilege

On a standard instance, itil covers the scenarios in the table, but it also grants access beyond the incident table. Customized ACLs and custom fields can require additional access. For tighter control, create a custom role whose ACLs grant only the tables and fields listed for the scenarios you use. Response plans control which incidents the agent works on, but they don't limit what the credentials can access in ServiceNow.

Required read access

Every write operation first looks up the incident, so the operation fails before anything is written if the user can't read it. Depending on how ServiceNow denies the read, the agent reports either Could not find incident '<number>' in ServiceNow, even when the incident exists, or 403 Forbidden. Don't remove itil (or an equivalent read role) when removing snc_read_only.

Control which ServiceNow tools the agent can use

The agent gets its ServiceNow tools from the built-in ServiceNow skill, so they don't appear as rows on the Tools page. To restrict them, open the Advanced permissions tab on that page and add a rule by tool name. For example, set ResolveServiceNowIncident to Ask to require approval before each resolve, or to Deny to block it.

The tool names are GetServiceNowIncident, PostServiceNowDiscussionEntry, AcknowledgeServiceNowIncident, ResolveServiceNowIncident, and UpdateServiceNowIncident. In Autonomous mode, Ask acts as Allow. If a limit must hold without approval, use Deny or a hook.

Limit what a resolve can set

ACLs apply to a whole column, so they can't allow some values and block others. To do that, add a PreToolUse hook on ResolveServiceNowIncident with the hooks API. This hook lets a resolve set u_cause_code only to Software or Hardware. The script reads the additionalFieldsJson argument and exits with code 2, which blocks the call, when it sets u_cause_code to any other value.

PUT /api/v2/extendedAgent/hooks/restrict-servicenow-cause-codes

{
  "name": "restrict-servicenow-cause-codes",
  "type": "GlobalHook",
  "properties": {
    "eventType": "PreToolUse",
    "activationMode": "always",
    "description": "Allow only listed cause codes on resolve",
    "hook": {
      "type": "command",
      "matcher": "ResolveServiceNowIncident",
      "timeout": 30,
      "failMode": "block",
      "script": "#!/usr/bin/env python3\nimport json, sys\n\nALLOWED = {\"Software\", \"Hardware\"}\n\nargs = json.load(sys.stdin).get(\"tool_input\") or {}\nfields = json.loads(args.get(\"additionalFieldsJson\") or \"{}\")\ncause = fields.get(\"u_cause_code\")\nif cause is not None and cause not in ALLOWED:\n    print(\"Cause code must be Software or Hardware.\", file=sys.stderr)\n    sys.exit(2)"
    }
  }
}

When the hook blocks a resolve, the tool doesn't run and the incident isn't changed. The thread shows the hook as Blocked with the reason, and the agent reports it. An allowed resolve shows the hook as Allowed and goes through. For the full input and output contract, see Hook data contract.

Limitations

• Work notes aren't read. The agent reads customer-visible comments when it picks up an incident, but it doesn't read work notes. Use comments or the agent chat to give the agent additional instructions.
• The default close code is Resolved by caller. When the agent doesn't pick one, resolve uses Resolved by caller for every connection type. Portal-managed OAuth API Connections used Solved (Permanently) until this release. If your instance doesn't have Resolved by caller in its close_code choice list, as on older releases, ServiceNow rejects the resolve with "The following fields are mandatory: Resolution code". Over a direct connection the agent reads the valid values and retries, but an API Connection doesn't return them, so name the close code in your instructions. See Tell the agent your resolution rules.
• API Connections don't return valid choice values. Portal-managed OAuth connections go through the Azure ServiceNow connector, which exposes only its documented record actions. When a resolve fails because fields are mandatory, the connector gives the agent each field's column but not its choice list, and accounts with only the itil role can't read sys_choice either. The agent can still set the right column, but it has no list of valid values to choose from. If your instance requires choice fields on resolve, such as a resolution code or cause code, name the values in your agent's instructions. See Tell the agent your resolution rules.
• The update action doesn't block resolution fields. It rejects state, incident_state, and journal fields, so it can't resolve an incident, but it can change close_code and close_notes. Resolve writes close_code, close_notes, and resolved_at as the same user, so ACLs can't allow resolve while blocking the update action from changing those fields.
• Posted journal text isn't echoed back. ServiceNow returns empty work_notes and comments values in update responses, so the tool result doesn't show the posted entry. Check the incident's Activities stream in ServiceNow to confirm the entry.

More information

For details about the ServiceNow roles referenced in this section, see the ServiceNow documentation:

• Base system roles: describes platform roles such as itil and snc_read_only.
• Incident Management roles: lists the roles that grant access to Incident Management.

---

Change credentials

To update your ServiceNow connection:

1. Go to Incidents and open the platform connection menu
2. Select Edit
3. Update your endpoint, authentication type, or credentials
4. Click Next, complete the optional Generate insights step, then click Save

---

Disconnect ServiceNow

To disconnect your ServiceNow integration:

1. Go to Incidents and open the platform connection menu
2. Click Disconnect
3. Confirm the disconnection

warning

Disconnecting permanently removes the connection. Your agent stops receiving and managing ServiceNow incidents.

---

Troubleshooting

OAuth Client Credentials fails

• Confirm your OAuth application supports the Client Credentials grant and is Active in ServiceNow
• Double-check your Client ID and Client Secret
• Ensure your ServiceNow instance allows external OAuth connections
• If every token request fails with 401 server_error, set the system property glide.oauth.inbound.client.credential.grant_type.enabled to true
• If calls fail with 403 Access to unscoped api is not allowed, set Scope Restriction on the OAuth application to No restrictions
• Confirm that OAuth Application User is set to an active, non-admin service account

Connection shows "Not Connected" after setup

• OAuth Client Credentials: Verify the OAuth application supports the Client Credentials grant, then edit the connection from the platform connection menu
• Basic auth: Verify the endpoint URL, username, and password are correct
• Confirm the ServiceNow endpoint is reachable from Azure (no firewall blocking)

"Unable to connect to ServiceNow endpoint"

• Verify the endpoint URL format: https://your-instance.service-now.com (no trailing slash)
• Confirm your ServiceNow instance is accessible from the public internet
• Check that the integration user has sufficient permissions

401 Unauthorized when loading assignment groups

With Basic Authentication, the Generate insights step loads assignment groups with the credentials you entered. If ServiceNow rejects the integration user's sign-in, the portal reports ServiceNow rejected the assignment-group request with 401 Unauthorized. In ServiceNow, open the user record and confirm that:

• Active is checked
• Password needs reset and Locked out are cleared
• The password matches the one entered in the portal

403 Forbidden when the agent acknowledges, updates, resolves, or posts to an incident

The integration user has read access but not write access to the fields the operation changes. This is expected when the user has the snc_read_only role. To allow writes, remove snc_read_only and keep itil. If you use a custom role, confirm that its ACLs grant write access to every field listed for that scenario. See ServiceNow permissions.

"Could not find incident" error

If the agent reports Could not find incident '<number>' in ServiceNow for an incident that exists, the integration user can't read it. ServiceNow can also deny the read with 403 Forbidden, depending on the ACL. Confirm that the user has the itil role (or an equivalent role with read access to incident) and that no ACL hides the record from that user.

"Invalid OAuth credentials"

• Regenerate the Client Secret in ServiceNow and try again
• Verify the Client ID matches the one in your ServiceNow OAuth application
• Confirm the OAuth application is active and not expired

---

Related

• Incident platforms — How incident platforms work with your agent
• Automate Incident Response — Configure response plans and automation

---

What you learned

In this tutorial, you:

• Connected your ServiceNow instance to Azure SRE Agent using OAuth 2.0 or Basic Authentication
• Verified the connection is active and healthy
• Learned how to set up response plans for ServiceNow incidents
• Understood what your agent can do with ServiceNow (read, post, acknowledge, resolve incidents)