SOAP Web Service
Simple Object Access Protocol (SOAP) ist ein XML-basiertes Protokoll für den Zugriff auf Webservices über HTTP.
Webservice-Provider
- Direkte Webservices: Verwenden Sie eine URL-Abfrage, um die WSDL einer Tabelle anzufordern.
- SOAP-Webservice-Importsätze: Verwenden Sie Importtabellen und Transformationszuordnungen, um Webservice-Anforderungen für Tabellen zu automatisieren.
- Geskriptete SOAP-Webservices: Verwenden Sie benutzerdefiniertes JavaScript, um SOAP-Webservice-Anforderungen auszuführen.
WSDL
Alle Tabellen und Import Sets generieren dynamisch WSDL-XML-Dokumente (Web Service Definition Language), die das Tabellenschema und die verfügbaren Vorgänge beschreiben.
https://myinstance.service-now.com/incident.do?WSDL
Alle dynamisch generierten und bereitgestellten ServiceNow WSDLs, auf die über HTTP zugegriffen werden kann, können unter den in der Open Source Initiative OSI - Apache License, Version 2.0, definierten Bedingungen verwendet werden.
Unterstützung für lange SOAP-Anforderungen
Now Platform unterstützt lange SOAP-Anforderungen, indem Socket-Zeitüberschreitungen aufgrund von Inaktivität der Netzwerkverbindung verhindert werden, während die Anforderungen verarbeitet werden.
Diese Funktionalität verbessert die Effizienz des ODBC-Treibers, wenn eine große Anzahl von Datensätzen angefordert wird, Abfragen zusammengefasst werden, oder Ausdrücke sortiert werden müssen.
Standardmäßig bietet das System einen Zeitüberschreitungsschutz für von ServiceNow bereitgestellte Webservices-Clients wie den ODBC-Treiber und den MID Server. Sie können Ihren benutzerdefinierten Webservices mit Systemeigenschaften einen Zeitüberschreitungsschutz hinzufügen.
Zeitüberschreitungsschutz
Webservices-Clients erhalten eine temporäre 307-Weiterleitung, um lange Sitzungen aufrecht zu erhalten, und ein Timeout aufgrund von Socket-Inaktivität zu verhindern. Eine temporäre 307-Weiterleitung bewirkt, dass Websservices-Clients, die den Statuscode unterstützen, ihre letzte Anforderung an die in der HTTP-Standortkopfzeile angegebene Position wiederholen. Der Wert der Standortkopfzeile ist dieselbe URL, die der Webservices-Client ursprünglich angegeben hat. Die Verwendung von temporäre 307-Weiterleitungen ist WS-I-kompatibel.
- Der Wert von glide.soapprocessor.allow_long_running_threads ist „true“.
- Die Anforderung enthält einen URL-Parameter redirectSupported=true.
- Die Anforderung ist sitzungsbezogen (unterstützt HTTP-Cookies).
- Die Anzahl der Umleitungen hat den von glide.soap.max_redirectsfestgelegten Wert nicht überschritten.
SOAP Web Services-Sicherheit
Eine Instanz erzwingt die Sicherheit von Webservices mithilfe einer Kombination aus Abfrage/Rückmeldung der Basic Authentication über das HTTPS-Protokoll und Zugriffssteuerungslisten (ACLs) auf Systemebene mit kontextbezogener Sicherheit. Administratoren können steuern, auf welche Systemressourcen Webservices-Benutzer zugreifen können, indem sie ihnen eine der SOAP-Rollen zuweisen.
SOAP-Rollen
Um SOAP Web Services verwenden zu können, müssen Sie über die entsprechende Rolle für den Vorgang verfügen, den Sie ausführen möchten. Außerdem müssen Sie über andere Rollen verfügen, die für den Zugriff auf die Zieltabellen erforderlich sind.
| Rolle | Beschreibung |
|---|---|
| soap | Kann alle SOAP-Vorgänge ausführen. |
| soap_create | Kann neue Datensätze einfügen. |
| soap_delete | Kann vorhandene Datensätze löschen. |
| soap_ecc | Kann Datensätze in der Warteschlangen-Tabelle [ecc_queue] abfragen, einfügen und löschen. |
| soap_query | Kann Datensatzinformationen abfragen. |
| soap_query_update | Kann Datensatzinformationen abfragen und Datensätze aktualisieren. |
| soap_script | Kann Skripts ausführen, die einen .do-Endpunkt angeben. Diese Rolle ist zum Ausführen von geskripteten Webservices erforderlich. |
| soap_update | Kann Datensätze aktualisieren. |
| import_admin | Kann alle Aspekte von Importsätzen und Importen verwalten. Erforderlich für den Zugriff auf die Tabelle „Import Set-Zeile“ [sys_import_set_row]. |
| import_transformer | Kann Import Set-Transformationszuordnungen verwalten und Transformationen ausführen. Erforderlich für den Zugriff auf die Tabelle „Import Set-Zeile“ [sys_import_set_row]. |
Standardanforderungen für Webservices-Rollen
Standardmäßig erfordern eine Reihe von Prozessor-ACL-Regeln, dass Benutzer über die Rolle „soap_query“ verfügen, um WSDL-, XSD- und XML-Schemaanforderungen zu stellen.
Wenn Sie diese Rollenanforderungen ändern möchten, können Sie die ACL-Regeln deaktivieren.
Standardauthentifizierung
Um die Basic Authentication für den mit der Instanz verknüpften Benutzer für jede WSDL- oder SOAP-Nachrichtenanforderung durchzusetzen, können Administratoren die Eigenschaft glide.basicauth.required auf true setzen.
Wenn diese Option aktiviert ist, muss jede WSDL- und SOAP-Anforderung eine Autorisierungskopfzeile enthalten, wie im Protokoll Basic Authentication angegeben.
Da Webserviceanforderungen nicht interaktiv sind, ist die Autorisierungskopfzeile immer während einer Anforderung erforderlich.
Die Angabe von Basic Authentication-Informationen bei jeder Anforderung (unabhängig davon, ob dies erforderlich ist oder nicht) hat den zusätzlichen Vorteil, dass der in den Basic Authentication-Anmeldeinformationen angegebene Benutzer dem Webservice-Aufruf zugeordnet werden kann. Beispiel: Beim Erstellen eines Incident-Datensatzes wird im Journalfeld anstelle des Standardgastbenutzers die Benutzer-ID im Header der Basic Authentication aufgelistet.
SOAP-Sicherheitsrichtlinien
- Signieren von SOAP-Anforderungen aktivieren oder deaktivieren, wenn ein externer Webservice verwendet wird
- Geben Sie die Authentifizierungsanforderungen an, die SOAP-Anforderungen erfüllen müssen, wenn Sie über WS-Security kommunizieren.
Weitere Informationen zur SOAP-Zugriffsrichtlinie finden Sie unter SOAP-API-Zugriffsrichtlinien.
Für signierte SOAP-Anforderungen erforderliche Zertifikate
Zum Signieren von SOAP-Anforderungen für die WS-Security-Kommunikation sind die folgenden Zertifikate erforderlich:
- X.509-Zertifikat von der anfordernden Person
- X.509-Zertifizierungsstellenzertifikat der Zertifizierungsstelle, die das Zertifikat der anfordernden Person signiert hat
SOAP-Standardsicherheitsrichtlinie
Administratoren können die SOAP-Sicherheitsrichtlinie angeben, die eine Instanz mit der Systemeigenschaft glide.soap.default_security_policy verwendet. Die Systemeigenschaft glide.soap.default_security_policy gibt den Namen der SOAP-Sicherheitsrichtlinie an, die die Instanz beim Erzwingen von Webservices-Security (WSS) für eingehende Anforderungen verwendet.
| Feld | Beschreibung |
|---|---|
| Typ | Zeichenfolge |
| Standardwert | Standardsicherheitsrichtlinie |
| Standort | Fügen Sie der Tabelle „Systemeigenschaften“ [sys_properties] eine Systemeigenschaft hinzu |
WS-Sicherheit verwenden
- Stellen Sie sicher, dass SOAP-Nachrichten von einem bekannten Absender stammen
- Stellen Sie sicher, dass SOAP-Nachrichten während der Übertragung nicht geändert wurden
WS-Security ist auf die Verwendung der Standardauthentifizierung ausgelegt. Wenn eine Instanz eine SOAP-Nachricht empfängt, überprüft sie den Basic Authentication-Header, um festzustellen, ob der SOAP-Benutzer über Rechte für die Instanz verfügt. Es überprüft den WS-Security-Header, um die Gültigkeit der eingehenden Nachricht zu ermitteln. Anforderungen, die von Angriffen wie einem Man-in-the-Middle-Angriff betroffen sind, weisen einen ungültigen WS-Security-Header auf und werden blockiert.
WS-Security-Profile
Ein WS-Security-Profil bestimmt, wie eine Webservices-Nachricht authentifiziert wird, wenn WS-Security aktiviert ist. Die folgenden Mechanismen können zur Authentifizierung von Webserviceanforderungen verwendet werden:
| Authentifizierungsmechanismus | Beschreibung |
|---|---|
| Zertifikatverifizierung | Überprüft das der Anforderung zugeordnete Zertifikat. Um das Zertifikat der Anforderung zu überprüfen, müssen das Zertifikat und die Zertifizierungsstelle der anfordernden Person hochgeladen werden. |
| Benutzeranmeldeinformationen | Authentifiziert die Webserviceanforderung durch Überprüfung der mit der Anforderung verknüpften Benutzeranmeldeinformationen. Diese Art der Authentifizierung kann entweder überprüfen, ob die Anmeldeinformationen der Anforderung mit den Anmeldeinformationen eines vorhandenen Benutzers übereinstimmen, oder ob die Anmeldeinformationen der Anforderung mit einem im Profildatensatz angegebenen Benutzernamen und Passwort übereinstimmen. |
Das Modul WS-Security Profiles listet die derzeit gültigen WS-Security-Profile auf.
Fehlerprotokollierung für WS-Security
Die Systemeigenschaft glide.processor.debug.SOAPProcessor ermöglicht die Anzeige von Fehlermeldungen zu WS-Security im Transaktionsprotokoll.
Die Systemeigenschaft glide.processor.debug.SOAPProcessor aktiviert (true) oder deaktiviert (false) Debugging-Nachrichten für die SOAP-Verarbeitung, wie z. B. Zertifikat- und Keystore-Prüfungen.
| Feld | Beschreibung |
|---|---|
| Typ | true | false |
| Standardwert | false |
| Standort | Fügen Sie der Tabelle „Systemeigenschaften“ [sys_properties] eine Systemeigenschaft hinzu |
WSS X.509-Token-Profil
- Name des Antragstellers
- Name des Ausstellers
- Seriennummer
- Gültigkeitsintervall
Verwenden Sie das X.509-Authentifizierungs-Framework, wie durch Webservices-Sicherheit: Spezifikation für die SOAP-Nachrichtensicherheit definiert.
Laden Sie das Zertifikat hoch, und referenzieren Sie es im Feld X509-Zertifikat. Wählen Sie bei einer gebundenen Sitzung den Benutzer aus, dessen Identität angenommen werden soll, wenn die WS-Security-Authentifizierung erfolgreich ist.
WSS UsernameToken-Profil
Bei der Angabe des X.509-Token-Profils können Sie auch einen UsernameToken in der SOAP-Anforderung angeben.
Ein UsernameToken wird verwendet, um die anfordernde Person anhand des „Benutzernamens“ zu identifizieren und optional ein Passwort, einen gemeinsamen geheimen Schlüssel oder ein entsprechendes Passwort zu verwenden, um diese Identität zu authentifizieren.
Es gibt zwei Möglichkeiten, ein UsernameToken zu authentifizieren.
- Authentifizieren Sie mit vorhandenen Benutzeranmeldeinformationen.
Abbildung : 5. Authentifizieren Sie mit vorhandenen Benutzeranmeldeinformationen Verwenden Sie den Benutzernamen der eingehenden SOAP-Anforderung, um einen Benutzer anhand des angegebenen Felds Benutzer zu suchen, das dem Wert UserName entspricht. Das System verwendet den Passwortwert im eingehenden UsernameToken, um die Anforderung zu authentifizieren. Wenn die Option Sitzung binden ausgewählt ist, wird der Benutzer, der sich erfolgreich authentifiziert, für die Sitzung verwendet.
- Authentifizieren Sie mit den angegebenen Benutzeranmeldeinformationen.
Abbildung : 6. Mit angegebenen Benutzeranmeldeinformationen authentifizieren Authentifizieren Sie mit Anmeldeinformationen, die sich nicht auf Benutzer in der Tabelle „Benutzer“ beziehen. Wenn die Option Sitzung binden ausgewählt ist, wird der Benutzer, der im Feld Als Benutzer ausführen angegeben ist, für die Sitzung verwendet.
Strikte Sicherheit für Webservices
Standardmäßig bestimmt die Basic Authentication für Webservices nur, ob ein Benutzer über eine SOAP-Verbindung zum Zugriff auf die Instanz berechtigt ist. Nach der Autorisierung kann jeder Benutzer auf jede als Webservice veröffentlichte Tabelle zugreifen.
Die Systemeigenschaft Strikte Sicherheit für eingehende SOAP-Anforderungen durchsetzen ändert dieses Verhalten und erfordert, dass Benutzer die Contextual Security Manager -Anforderungen für den Zugriff auf Instanzressourcen von Webservices erfüllen.
Wenn diese Eigenschaft aktiviert ist, können nur Benutzer, die über die richtige SOAP-Rolle verfügen und auch die ACL-Bedingungen der Tabelle und des Vorgangs erfüllen, diesen Vorgang über eine SOAP-Verbindung ausführen.
Gegenseitige Authentifizierung für Webservices
Die gegenseitige Authentifizierung wird für ausgehende Webservices unterstützt.
SOAP-Sitzungsverwaltung und -Berichterstellung
Eine SOAP-Sitzung ist eine Glide-Sitzung, die von einer Instanz von einem externen SOAP-Client wie z. B. einer Webservice-Client-Anwendung, einem ServiceNow-MID-Server oder einen ServiceNow-ODBC-Treiber eingerichtet wird. SOAP-Sitzungen werden in die Liste der Benutzersitzungen unter aufgenommen . Die ?SOAP- URLs identifizieren SOAP-Sitzungen.
SOAP-Sitzungseigenschaften
Bestimmte Eigenschaften steuern, wie SOAP-Sitzungen verwaltet werden.
| Eigenschaft | Beschreibung |
|---|---|
| glide.soap.invalidate_session_timeout | Dauer in Sekunden, während der eine aktive Sitzung geöffnet bleibt. Nachdem diese Zeit verstrichen ist, deaktiviert die Instanz die Sitzung und stellt Systemressourcen in Anspruch. Wenn der Client nach Erreichen der Zeitüberschreitungsdauer eine weitere Anforderung sendet, richtet die Instanz eine neue Sitzung ein. Diese Eigenschaft akzeptiert Werte zwischen 5 und 1200 Sekunden (20 Minuten).
|