Simple Object Access Protocol (SOAP) is an XML-based protocol for accessing web services over HTTP.

You can use SOAP to access data on your instance. Available SOAP web services are WS-I compliant, as outlined in the WS-I Basic Profile 1.0.

Web service provider

ServiceNow publishes its underlying table structures and associated data using the following web service methods:
Note: SOAP messages are sent with the assumption that the recipient is XML compliant. No encoding is applied to a SOAP message. SOAP always decodes responses as UTF-8, the XML encoding header is not used.

WSDL

All tables and import sets dynamically generate Web Service Definition Language (WSDL) XML documents that describe its table schema and available operations.

You can obtain a table's WSDL by issuing a URL call to your instance that contains the name of the table and the WSDL parameter. For example:
https://myinstance.service-now.com/incident.do?WSDL

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.

A web service request that exceeds the timeout limit specified in glide.soap.request_processing_timeout can only receive a 307-Temporary Redirect when all of these conditions are met:
  • 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.
If any of these conditions is not met, the web service client receives a 408 Request Timeout error.
Note: To ensure that applications experience a socket timeout rather than a 408 Request Timeout, set the glide.soap.request_processing_timeout property to a value larger than the shortest socket timeout setting in effect for the connection between the application and the instance (300 seconds for hosted instances).

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.

Table 1. SOAP Roles
RoleDescription
soap Can perform all SOAP operations.
soap_create Can insert new records.
soap_delete Can delete existing records.
soap_ecc Can query, insert, and delete records on the Queues [ecc_queue] table.
soap_query Can query record information.
soap_query_update Can query record information and update records.
soap_script Can run scripts that specify a .do endpoint. This role is required for running scripted web services.
soap_update Can update records.
import_admin Can manage all aspects of import sets and imports. Required for access to the Import Set Row [sys_import_set_row] table.
import_transformer Can manage import set transform maps and run transforms. Required for access to the Import Set Row [sys_import_set_row] table.

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.

Figure 1. Web service processor ACLs

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.

Note: If configured, basic authentication refers to local credentials or LDAP authentication.

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

The Enhanced Web Service Provider - Common plugin adds the SOAP Security Policies module to the System Web Services application. This module allows administrators to set the following 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.

Figure 2. SOAP security 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.

Table 2. SOAP default security policy settings
Field Description
Type String
Default value Default Security Policy
Location Add a system property to the System Properties [sys_properties] table

WS-Security

You can validate signed web services requests using WS-security. Enable WS-Security to:
  • Verify that SOAP messages originate from a known sender
  • Verify that SOAP messages have not been altered in transit
ServiceNow supports WS-Security 1.1 to validate signed web services requests.
Note: WS-Security is not used as an encryption mechanism, HTTPS protocol is used to encrypt all communications.

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:

Table 3. Web service authentication mechanisms
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.
Specify the authentication mechanism you want to use when you create a new WS-security profile.

The WS-Security Profiles module lists the WS-Security profiles that are currently in effect.

Figure 3. WS-Security Profiles module

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.

Table 4. glide.processor.debug.SOAPProcessor fields
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

Use the X.509 framework for a WSS X.509 security profile. An X.509 certificate is used to validate a public key that is then used to sign the incoming SOAP message. It specifies a binding between a public key and a set of attributes that includes at least the following:
  • 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.

Figure 4. WSS X.509 Security Profile

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.

  1. 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.

  2. 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.

Note: The UsernameToken Profile cannot be used independent of the X.509 Token Profile.

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 User Administration > Logged in users. The ?SOAP URLs identify SOAP sessions.

SOAP session properties

Certain properties control how SOAP sessions are maintained.

Table 5. SOAP session properties
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).

  • Type: integer
  • Default value: 60
  • Location: Add to the System Properties [sys_properties] table
Note: To learn more about properties that affect SOAP web services processing, see the following topics in Instance Security Hardening Settings: