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.
- SOAP-Webservices mit Skript: Verwenden Sie anwenderdefiniertes JavaScript, um SOAP-Webservices-Anforderungen auszuführen.
WSDL
Alle Tabellen und Importsätze 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, stehen unter den Bedingungen zur Verfügung, die in der Lizenzvereinbarung der Open Source Initiative OSI – Apache License, Version 2.0 definiert sind.
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 Zeitüberschreitungsschutz für Webservices-Clients, die von ServiceNow bereitgestellt werden, wie z. B. den ODBC-Treiber und den MID Server. Sie können Ihren anwenderdefinierten 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 des Speicherort-Headers ist die gleiche 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 wahr.
- Die Anforderung enthält einen URL-Parameter redirectSupported=true.
- Die Anforderung ist sitzungsfähig (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 Webdiensten mithilfe einer Kombination aus Abfrage/Rückmeldung-Standardauthentifizierung über das HTTPS-Protokoll und Zugriffssteuerungslisten (ACLs) auf Systemebene mit Kontextsicherheit. 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 alle anderen 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 „Importsatzzeile“ [sys_import_set_row]. |
| import_transformer | Kann Transformationszuordnungen für Importsätze verwalten und Transformationen ausführen. Erforderlich für den Zugriff auf die Tabelle „Importsatzzeile“ [sys_import_set_row]. |
Standardanforderungen für Webservices-Rollen
Standardmäßig benötigen Benutzer für eine Reihe von Prozessor-ACL-Regeln die Rolle „soap_query“, 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 Webservice-Anforderungen nicht interaktiv sind, ist der Autorisierungs- Header während einer Anforderung immer erforderlich.
Die Bereitstellung von Informationen zur Standardauthentifizierung bei jeder Anforderung (unabhängig davon, ob sie erforderlich sind oder nicht) hat den zusätzlichen Vorteil, dass dem in den Anmeldeinformationen für die Standardauthentifizierung angegebenen Benutzer der Aufruf des Webservice zugeordnet werden kann. Beispiel: Beim Erstellen eines Incident-Datensatzes wird im Feld „Journal“ die im Header der Standardauthentifizierung enthaltene Benutzer-ID anstelle des standardmäßigen Gastbenutzers aufgeführt.
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-CA-Zertifikat 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 Standardauthentifizierung ausgelegt. Wenn eine Instanz eine SOAP-Nachricht empfängt, überprüft sie den Header der Standardauthentifizierung, um zu bestimmen, 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 (z. B. Man-in-the-Middle-Angriffen) betroffen sind, weisen einen ungültigen WS-Security-Header auf und werden blockiert.
WS-Security-Profile
Ein WS-Sicherheitsprofil bestimmt, wie eine Webservices-Nachricht authentifiziert wird, wenn WS-Sicherheit aktiviert ist. Die folgenden Mechanismen können zur Authentifizierung von Webservice-Anforderungen verwendet werden:
| Authentifizierungsmechanismus | Beschreibung |
|---|---|
| Zertifikatverifizierung | Verifiziert das mit der Anforderung verknüpfte Zertifikat. Um das Zertifikat der Anforderung zu verifizieren, müssen das Zertifikat und die Zertifizierungsstelle der anfordernden Person hochgeladen werden. |
| Benutzeranmeldeinformationen | Authentifiziert die Webservice-Anforderung durch Verifizieren der mit der Anforderung verknüpften Anmeldeinformationen. Diese Art der Authentifizierung kann entweder überprüfen, ob die Anmeldeinformationen der Anforderung mit den Anmeldeinformationen eines vorhandenen Anwenders übereinstimmen oder ob die Anmeldeinformationen der Anforderung mit einem im Profildatensatz angegebenen Anwendernamen und Passwort übereinstimmen. |
Das Modul „WS-Sicherheitsprofile“ listet die derzeit gültigen WS-Sicherheitsprofile 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 Anwender 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 „Anwendernamens“ zu identifizieren und optional ein Passwort, ein gemeinsames Geheimnis oder ein entsprechendes Passwort zu verwenden, um diese Identität zu authentifizieren.
Es gibt zwei Möglichkeiten, ein UsernameToken zu authentifizieren.
- Authentifizieren Sie sich mit vorhandenen Anmeldeinformationen.
Abbildung : 5. Authentifizieren Sie sich mit vorhandenen Anmeldeinformationen Verwenden Sie den Anwendernamen der eingehenden SOAP-Anforderung, um einen Anwender anhand des angegebenen Felds „Anwender“ zu suchen, um den Wert „UserName“ abzugleichen. 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 hat, 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 erzwingen ändert dieses Verhalten und erfordert, dass Benutzer die Anforderungen des Kontextsicherheitsmanagers erfüllen, um über Webservices auf Instanzressourcen zugreifen zu können.
Wenn diese Eigenschaft aktiviert ist, können nur Benutzer, die über die richtige SOAP-Rolle verfügen und die ACL-Bedingungen für die Tabelle und den Vorgang 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 der Liste der Benutzersitzungen unter aufgeführt . 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, die 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 Ablauf der Zeitüberschreitungsdauer eine weitere Anforderung sendet, erstellt die Instanz eine neue Sitzung. Diese Eigenschaft akzeptiert Werte von 5 bis 1200 Sekunden (20 Minuten).
|