SOAP Web Service
Le SOAP (Simple Object Access Protocol) est un protocole basé sur XML pour accéder aux services Web sur HTTP.
Fournisseur de services web
- Services Web directs : utilisez une requête d’URL pour demander le WSDL d’une table.
- Jeux d’importation de services web SOAP : utilisez des tables d’importation et des cartes de transformation pour automatiser les demandes de service web pour les tables.
- Services web SOAP scriptés : utilisez JavaScript personnalisé pour exécuter des demandes de services web SOAP.
WSDL
Toutes les tables et tous les jeux d’importation génèrent dynamiquement des documents XML WSDL (Web Service Definition Language) qui décrivent leur schéma de table et les opérations disponibles.
https://myinstance.service-now.com/incident.do?WSDL
Tous les WSDL générés et servis ServiceNow dynamiquement accessibles via HTTP peuvent être utilisés selon les termes définis dans le contrat de licence Open Source Initiative OSI - Apache License, Version 2.0.
Prise en charge des demandes SOAP de longue durée
Prend en charge les ServiceNow AI Platform requêtes SOAP de longue durée en empêchant les délais d’expiration des sockets dus à l’inactivité de la connexion réseau pendant le traitement des demandes.
Cette fonctionnalité améliore l’efficacité du pilote ODBC lors de la demande d’un grand nombre d’enregistrements, de l’exécution de requêtes agrégées ou de l’utilisation d’un ordre par expressions nécessitant un tri.
Par défaut, le système assure la protection du délai d’expiration pour les clients des services Web fournis par ServiceNow le pilote ODBC et le serveur MID. Vous pouvez ajouter une protection contre le délai d’expiration à vos services Web personnalisés avec des propriétés système.
Protection du délai d’expiration
Les clients des services Web reçoivent une redirection temporaire 307 pour maintenir les sessions longues en vie et éviter un délai d’expiration dû à l’inactivité du socket. Une redirection temporaire 307 oblige les clients de services Web qui prennent en charge le code d’état à répéter leur dernière demande à l’emplacement spécifié dans l’en-tête d’emplacement HTTP. La valeur de l’en-tête de l’emplacement est la même URL que celle spécifiée à l’origine par le client de services web. L’utilisation de redirections temporaires 307 est conforme à WS-I.
- La valeur de glide.soapprocessor.allow_long_running_threads est vrai.
- La demande inclut un paramètre d’URL redirectSupported=true .
- La demande est orientée session (prend en charge les cookies HTTP).
- Le nombre de redirections n’a pas dépassé la valeur définie par glide.soap.max_redirects.
Sécurité des services web SOAP
Une instance applique la sécurité des services Web à l’aide d’une combinaison d’authentification de base challenge/réponse sur le protocole HTTPS et de listes de contrôle d’accès (ACL) au niveau du système à l’aide de la sécurité contextuelle. Les administrateurs peuvent contrôler les ressources système auxquelles les utilisateurs de services Web peuvent accéder en leur accordant l’un des rôles SOAP.
Rôles SOAP
Pour utiliser les services Web SOAP, vous devez disposer du rôle approprié pour l’opération que vous souhaitez effectuer. En outre, vous devez disposer de tous les autres rôles requis pour accéder aux tables cibles.
| Rôle | Description |
|---|---|
| savon | Peut effectuer toutes les opérations SOAP. |
| soap_create | Peut insérer de nouveaux enregistrements. |
| soap_delete | Peut supprimer des enregistrements existants. |
| soap_ecc | Peut interroger, insérer et supprimer des enregistrements dans la table Files d’attente [ecc_queue]. |
| soap_query | Peut interroger des informations d’enregistrement. |
| soap_query_update | Peut interroger les informations d’enregistrement et mettre à jour les enregistrements. |
| soap_script | Peut exécuter des scripts qui spécifient un point de terminaison .do. Ce rôle est requis pour exécuter des services Web basés sur un script. |
| soap_update | Peut mettre à jour les enregistrements. |
| import_admin | Peut gérer tous les aspects des ensembles d’importation et des importations. Requis pour accéder à la table Ligne de jeu d’importation [sys_import_set_row]. |
| import_transformer | Peut gérer les jeux d’importation, les cartes de transformation et exécuter des transformations. Requis pour accéder à la table Ligne de jeu d’importation [sys_import_set_row]. |
Besoins du rôle de services Web par défaut
Par défaut, un ensemble de règles ACL de processeur exige que les utilisateurs disposent du rôle soap_query pour effectuer des demandes de schéma WSDL, XSD et XML.
Si vous souhaitez modifier ces exigences de rôle, vous pouvez désactiver les règles ACL.
Authentification de base
Pour appliquer l’authentification de base à l’utilisateur associé à l’instance pour chaque demande de message WSDL ou SOAP, les administrateurs peuvent définir la propriété glide.basicauth.required sur vrai.
Lorsque cette option est activée, chaque demande WSDL et SOAP doit contenir un en-tête « Autorisation » comme spécifié dans le protocole d’authentification de base .
Les demandes de services Web n’étant pas interactives, l’en-tête Authorization est toujours requis pendant une requête.
Fournir des informations d’authentification de base avec chaque demande (qu’elles soient requises ou non) présente l’avantage supplémentaire que l’utilisateur fourni dans les informations d’identification d’authentification de base peut être associé à l’invocation de service Web. Par exemple, lors de la création d’un enregistrement d’incident, le champ journal répertorie l’ID utilisateur contenu dans l’en-tête d’authentification de base au lieu de l’utilisateur invité par défaut.
Politiques de sécurité SOAP
- Activer ou désactiver la signature de demandes SOAP lors de l’utilisation d’un service Web externe
- Spécifiez les exigences d’authentification que les demandes SOAP doivent satisfaire lors de communication sur sécurité WS.
Pour en savoir plus sur la politique d’accès SOAP, consultez Politiques d’accès de l’API SOAP.
Certificats requis pour les demandes SOAP signées
Pour signer des demandes SOAP pour les communications de sécurité WS, les certificats suivants sont requis :
- Certificat X.509 du demandeur
- Certificat de l’autorité de certification X.509 de l’autorité de certification qui a signé le certificat du demandeur
Politique de sécurité par défaut SOAP
Les administrateurs peuvent spécifier la politique de sécurité SOAP utilisée par une instance avec la propriété système glide.soap.default_security_policy. La propriété système glide.soap.default_security_policy spécifie le nom de la politique de sécurité SOAP que l’instance utilise lors de l’application de la sécurité des services Web (WSS) pour les demandes entrantes.
| Champ | Description |
|---|---|
| Type | Chaîne |
| Valeur par défaut | Politique de sécurité par défaut |
| Emplacement | Ajouter une propriété système à la table Propriétés système [sys_properties] |
Utiliser pour la sécurité WS
- Vérifiez que les messages SOAP proviennent d’un expéditeur connu
- Vérifier que les messages SOAP n’ont pas été modifiés en transit
WS-Security est destiné à fonctionner avec une authentification de base. Lorsqu’une instance reçoit un message SOAP, elle examine l’en-tête d’authentification de base pour déterminer si l’utilisateur SOAP a des droits sur l’instance. Il examine l’en-tête WS-Security pour déterminer la validité du message entrant. Les demandes affectées par des attaques, telles qu’une attaque de l’intercepteur, ont un en-tête de sécurité WS non valide et sont bloquées.
Profils de sécurité WS
Un profil de sécurité WS détermine la façon dont un message de services Web est authentifié lorsque la sécurité WS est activée. Les mécanismes suivants peuvent être utilisés pour authentifier les demandes de services Web :
| Mécanisme d’authentification | Description |
|---|---|
| Vérification du certificat | Vérifie le certificat associé à la demande. La vérification du certificat de la demande nécessite le chargement du certificat et de l’autorité de certification du demandeur. |
| Informations d’identification de l’utilisateur | Authentifie la demande de services Web en vérifiant les informations d’identification de l’utilisateur associées à la demande. Ce type d’authentification peut vérifier que les informations d’identification de la demande correspondent aux informations d’identification d’un utilisateur existant ou que les informations d’identification de la demande correspondent à un nom d’utilisateur et un mot de passe fournis dans l’enregistrement de profil. |
Le module Profils de sécurité WS répertorie les profils de sécurité WS actuellement en vigueur.
Journalisation des erreurs de sécurité WS
La propriété système glide.processor.debug.SOAPProcessor permet d’afficher des messages d’erreur sur la sécurité WS dans le journal des transactions.
La propriété système glide.processor.debug.SOAPProcessor active (vrai) ou désactive (faux) les messages de débogage pour le traitement SOAP, tels que les vérifications de certificat et de magasin de clés.
| Champ | Description |
|---|---|
| Type | vrai | faux |
| Valeur par défaut | Faux |
| Emplacement | Ajouter une propriété système à la table Propriétés système [sys_properties] |
Profil de jeton WSS X.509
- Nom du sujet
- Nom de l’émetteur
- numéro de série
- Intervalle de validité
Utilisez le cadre de travail d’authentification X.509 tel que défini par la spécification Sécurité des services Web : sécurité des messages SOAP.
Chargez le certificat et référencez-le dans le champ Certificat X509 . S’il s’agit d’une session liée, sélectionnez l’utilisateur dont l’identité sera empruntée lorsque l’authentification WS-Security réussit.
Profil UsernameToken WSS
Lorsque vous spécifiez le profil de jeton X.509, vous pouvez également fournir un UsernameToken dans la demande SOAP.
Un UsernameToken est utilisé comme moyen d’identifier le demandeur par un « nom d’utilisateur », et éventuellement d’utiliser un mot de passe, un secret partagé ou l’équivalent d’un mot de passe, pour authentifier cette identité.
Il existe deux façons d’authentifier un UsernameToken.
- Authentifiez-vous avec les informations d’identification de l’utilisateur existant.
Figure 5. Authentifier avec les informations d’identification de l’utilisateur existant Utilisez le nom d’utilisateur de la demande SOAP entrante pour rechercher un utilisateur à l’aide du champ Utilisateur spécifié afin qu’il corresponde à la valeur UserName . Le système utilise la valeur de mot de passe dans le UsernameToken entrant pour authentifier la demande. Lorsque l’option Lier la session est sélectionnée, l’utilisateur qui s’authentifie avec succès est utilisé pour la session.
- Authentifiez-vous avec les informations d’identification de l’utilisateur spécifié.
Figure 6. Authentifier avec les informations d’identification de l’utilisateur spécifié Authentifiez-vous à l’aide d’informations d’identification de connexion non liées aux utilisateurs de la table Utilisateur. Lorsque l’option Lier la session est sélectionnée, l’utilisateur spécifié dans le champ Exécuter en tant qu’utilisateur est utilisé pour la session.
Sécurité stricte pour les services Web
Par défaut, l’authentification de base pour les services Web détermine uniquement si un utilisateur est autorisé à accéder à l’instance avec une connexion SOAP. Une fois autorisé, tout utilisateur peut accéder à n’importe quelle table publiée en tant que service web.
La propriété système Appliquer une sécurité stricte sur les demandes SOAP entrantes modifie ce comportement et exige que les utilisateurs répondent aux exigences du gestionnaire de sécurité contextuelle pour accéder aux ressources d’instance à partir de services Web.
Avec cette propriété activée, seuls les utilisateurs qui disposent du rôle SOAP approprié et qui remplissent également les conditions ACL que la table et l’opération peuvent effectuer cette opération à partir d’une connexion SOAP.
Authentification réciproque pour les services Web
L’authentification réciproque est prise en charge pour les services Web sortants.
Gestion des sessions SOAP et génération de rapports
Une session SOAP est une session Glide établie avec une instance par un client SOAP externe, tel qu’une application cliente de services Web, un ServiceNow serveur MID ou le ServiceNow pilote ODBC. Les sessions SOAP sont incluses dans la liste des sessions utilisateur à l’adresse . Le ? Les URL SOAP identifient les sessions SOAP.
Propriétés de la session SOAP
Certaines propriétés contrôlent la façon dont les sessions SOAP sont maintenues.
| Propriété | Description |
|---|---|
| glide.soap.invalidate_session_timeout | Durée, en secondes, pendant laquelle une session active reste ouverte. Une fois cette durée atteinte, l’instance désactive la session et récupère toutes les ressources système. Si le client envoie une autre demande après que la durée du délai d’expiration soit atteinte, l’instance établit une nouvelle session. Cette propriété accepte des valeurs de 5 à 1 200 secondes (20 minutes).
|