SOAP web service
-
- UpdatedAug 1, 2024
- 11 minutes to read
- Xanadu
- API implementation
Simple Object Access Protocol (SOAP) is an XML-based protocol for accessing web services over HTTP.
Web service provider
- Direct web services: Use a URL query to request a table's WSDL.
- SOAP web service import sets: Use import tables and transform maps to automate web service requests for tables.
- Scripted SOAP web services: Use custom JavaScript to execute SOAP web services requests.
WSDL
All tables and import sets dynamically generate Web Service Definition Language (WSDL) XML documents that describe its table schema and available operations.
All dynamically generated and served ServiceNow WSDLs accessible via HTTP are available for use under the terms defined in the Open Source Initiative OSI - Apache License, Version 2.0 license agreement.
Long-running SOAP request support
The Now Platform supports long-running SOAP requests by preventing socket timeouts due to inactivity of the network connection while the requests are in process.
This functionality improves the efficiency of the ODBC driver when requesting large numbers of records, doing aggregate queries, or using order by expressions that require sorting.
By default, the system provides timeout protection for web services clients provided by ServiceNow such as the ODBC driver and the MID Server. You can add timeout protection to your custom web services with system properties.
Timeout protection
Web services clients receive a 307-Temporary Redirect to keep long sessions alive and prevent a timeout due to socket inactivity. A 307-Temporary Redirect causes web services clients which support the status code to repeat their last request to the location specified in the HTTP location header. The value of the location header is the same URL that the web services client originally specified. The use of 307-Temporary Redirects is WS-I compliant.
- The value of glide.soapprocessor.allow_long_running_threads is true.
- The request includes a redirectSupported=true URL parameter.
- The request is session-aware (supports HTTP cookies).
- The number of redirects has not exceeded the value set by glide.soap.max_redirects.
SOAP web services security
An instance enforces web service security using a combination of basic authentication challenge/response over the HTTPS protocol and system-level access control lists (ACLs) using contextual security. Administrators can control what system resources web services users can access by granting them one of the SOAP roles.
SOAP roles
To use SOAP web services, you must have the appropriate role for the operation you want to perform. Also, you must have any other roles required to access the target tables.
Default web services role requirements
By default, a set of processor ACL rules require users to have the soap_query role to make WSDL, XSD, and XML schema requests.
If you want to change these role requirements, you can deactivate the ACL rules.

Basic authentication
To enforce basic authentication for the user associated with the instance for each WSDL or
SOAP message request, administrators can set the property
glide.basicauth.required
to true.
When enabled, each WSDL and SOAP request must contain an "Authorization" header as specified in the Basic Authentication protocol.
Because web services requests are non-interactive, the Authorization header is always required during a request.
Supplying basic authentication information with every request (whether or not it is required) has the added advantage that the user supplied in the basic authentication credentials can be associated web service invocation. For example, when creating an Incident record, the journal field lists the user ID contained in the basic authentication header instead of the default guest user.
SOAP security policies
- Enable or disable signing SOAP requests when consuming an external web service
- Specify the authentication requirements SOAP requests must meet when communicating over WS-Security.
To know more about SOAP access policy, see SOAP API access policies.

Certificates required for signed SOAP requests
To sign SOAP requests for WS-Security communications, the following certificates are required:
- X.509 certificate from the requester
- X.509 CA certificate of the certificate authority who signed the requester's certificate
SOAP default security policy
Administrators can specify the SOAP security policy an instance uses with the system
property glide.soap.default_security_policy
. The
glide.soap.default_security_policy
system property specifies the name of
the SOAP security policy the instance uses when enforcing Web Services-Security (WSS) for
inbound requests.
Field | Description |
---|---|
Type | String |
Default value | Default Security Policy |
Location | Add a system property to the System Properties [sys_properties] table |
WS-Security
- Verify that SOAP messages originate from a known sender
- Verify that SOAP messages have not been altered in transit
WS-Security is intended to work with basic authentication. When an instance receives a SOAP message, it reviews the basic authentication header to determine if the SOAP user has rights to the instance. It reviews the WS-Security header to determine the validity of the incoming message. Requests affected by attacks, such as a man-in-the-middle attack, have an invalid WS-Security header and are blocked.
WS-Security profiles
A WS-security profile determines how a web services message is authenticated when WS-security is enabled. The following mechanisms can be used to authenticate web services requests:
Authentication mechanism | Description |
---|---|
Certificate verification | Verifies the certificate associated with the request. Verifying the request's certificate requires uploading the requester's certificate and certificate authority. |
User credentials | Authenticates the web services request by verifying the user credentials associated with the request. This type of authentication can either verify that the request's credentials match an existing user's credentials or that the request's credentials match a user name and password provided in the profile record. |
The WS-Security Profiles module lists the WS-Security profiles that are currently in effect.

WS-Security error logging
The glide.processor.debug.SOAPProcessor
system property allows error
messages about WS-security to be displayed in the transaction log.
The system property glide.processor.debug.SOAPProcessor
enables (true) or
disables (false) debugging messages for SOAP processing such as certificate and keystore
checks.
Field | Description |
---|---|
Type | true | false |
Default value | false |
Location | Add a system property to the System Properties [sys_properties] table |
WSS X.509 Token Profile
- subject name
- issuer name
- serial number
- validity interval
Use the X.509 authentication framework as defined by the Web Services Security: SOAP Message Security specification.
Upload the certificate and reference it in the X509 Certificate field. If a bound session, select the user to impersonate when the WS-Security authentication succeeds.

WSS UsernameToken Profile
When specifying the X.509 Token Profile, you can also supply a UsernameToken in the SOAP request.
A UsernameToken is used as a means of identifying the requester by "user name", and optionally using a password, shared secret, or password equivalent, to authenticate that identity.
There are two ways to authenticate a UsernameToken.
- Authenticate with existing user credentials.
Figure 5. Authenticate with existing user credentials Use the user name of the incoming SOAP request to look up a user by the specified User field to match the UserName value. The system uses the password value in the incoming UsernameToken to authenticate the request. When the Bind session option is selected, the user that authenticates successfully is used for the session.
- Authenticate with specified user credentials.
Figure 6. Authenticate with specified user credentials Authenticate using login credentials unrelated to users in the User table. When the Bind session option is selected, the user that is specified in the Run as user field is used for the session.
Strict security for web services
By default, basic authentication for web services only determines whether a user is authorized to access the instance with a SOAP connection. Once authorized, any user can access any table published as a web service.
The system property Enforce strict security on incoming SOAP requests changes this behavior and requires that users meet Contextual Security Manager requirements to access instance resources from web services.
With this property enabled, only users that have the proper SOAP role and also meet the ACL conditions the table and operation can perform that operation from a SOAP connection.
Mutual authentication for web services
Mutual authentication is supported for outbound web services.
SOAP session management and reporting
A SOAP session is a Glide session established with an instance by any external SOAP client, such as a web services client application, a ServiceNow MID Server, or the ServiceNow ODBC driver. SOAP sessions are included in the list of user sessions at . The ?SOAP URLs identify SOAP sessions.
SOAP session properties
Certain properties control how SOAP sessions are maintained.
Property | Description |
---|---|
glide.soap.invalidate_session_timeout | Duration, in seconds, that an active session remains open. After this duration
is reached, the instance deactivates the session and reclaims any system resources.
If the client sends another request after the timeout duration is reached, the
instance establishes a new session. This property accepts values from 5 to 1200 seconds (20 minutes).
|
On this page
- Web service provider
- WSDL
- Long-running SOAP request support
- Timeout protection
- SOAP web services security
- SOAP roles
- Default web services role requirements
- Basic authentication
- SOAP security policies
- Certificates required for signed SOAP requests
- SOAP default security policy
- WS-Security
- WS-Security profiles
- WS-Security error logging
- WSS X.509 Token Profile
- WSS UsernameToken Profile
- Strict security for web services
- Mutual authentication for web services
- SOAP session management and reporting
- SOAP session properties