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 un JavaScript personnalisé pour exécuter des demandes de SOAP Web Services.
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 son 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 et accessibles via HTTP peuvent être utilisés selon les termes définis dans l’accord de licence Open Source Initiative OSI - Apache License, Version 2.0.
Prise en charge des requêtes SOAP de longue durée
Le Now Platform prend en charge les demandes SOAP de longue durée en empêchant les délais d’expiration de socket 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 d’agrégat ou de l’utilisation de l’ordre par expressions qui nécessitent un tri.
Par défaut, le système assure une protection contre les délais d’expiration pour les clients de services Web fournis par ServiceNow , tels que 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 contre le délai d’expiration
Les clients des services Web reçoivent une redirection temporaire 307 pour maintenir les longues sessions en vie et éviter un délai d’expiration dû à l’inactivité du socket. Une redirection temporaire 307 entraîne la répétition de la dernière requête des clients de services Web qui prennent en charge le code d’état à l’emplacement spécifié dans l’en-tête d’emplacement HTTP. La valeur de l’en-tête d’emplacement est la même URL que celle spécifiée à l’origine par le client de services Web. L’utilisation des redirections temporaires 307 est conforme à la norme WS-I.
- La valeur de glide.soapprocessor.allow_long_running_threads est vrai.
- La demande inclut un paramètre d’URL redirectSupported=true .
- La requête 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 de défi/réponse à l’authentification de base 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, tous les autres rôles requis doivent être nécessaires 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 l’exécution de services Web scriptés. |
| soap_update | Peut mettre à jour des enregistrements. |
| import_admin | Peut gérer tous les aspects des ensembles d’importation et des importations. Requis pour accéder à la table Ligne du 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 du 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.
Lorsqu’elle est activée, chaque demande WSDL et SOAP doit contenir un en-tête « Autorisation » tel que spécifié dans le protocole d’authentification de base .
Étant donné que les demandes de services web ne sont pas interactives, l’en-tête d’autorisation est toujours requis au cours d’une demande.
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’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 d’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 les demandes SOAP pour les communications de sécurité WS, les certificats suivants sont requis :
- Certificat X.509 du demandeur
- Certificat X.509 CA 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 qu’une instance utilise 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 Web Services-Security (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érifiez que les messages SOAP n’ont pas été modifiés en transit
WS-Security est conçu pour 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 dispose des droits sur l’instance. Il examine l’en-tête de sécurité WS pour déterminer la validité du message entrant. Les demandes affectées par des attaques, telles qu’une attaque de l’homme du milieu, 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 service 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 du demandeur et de l’autorité de certification. |
| 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 concernant 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 tel que les vérifications de certificat et de magasin de clé.
| 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 l’infrastructure d’authentification X.509 telle que définie 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é emprunte lorsque l’authentification WS-Security réussit.
Profil UsernameToken WSS
Lors de la spécification du profil de jeton X.509, vous pouvez également fournir un UsernameToken dans la demande SOAP.
Un UsernameToken est utilisé comme un moyen d’identifier le demandeur par son « nom d’utilisateur » et, éventuellement, à l’aide d’un mot de passe, d’un secret partagé ou d’un mot de passe équivalent pour authentifier cette identité.
Il existe deux façons d’authentifier un UsernameToken.
- Authentifiez-vous avec les informations d’identification de l’utilisateur existantes.
Figure 5. Authentifier avec les informations d’identification existantes de l’utilisateur 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 du Nom d’utilisateur . 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ées.
Figure 6. Authentifier avec les informations d’identification de l’utilisateur spécifiées 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é, n’importe quel 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 des services Web.
Lorsque cette propriété est activée, seuls les utilisateurs disposant du rôle SOAP approprié et remplissant également les conditions ACL de la table et de 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 de session 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 à . Le ? Les URL SOAP identifient les sessions SOAP.
Propriétés de session SOAP
Certaines propriétés contrôlent la façon dont les sessions SOAP sont gérées.
| 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 avoir atteint le délai d’expiration, l’instance établit une nouvelle session. Cette propriété accepte des valeurs comprises entre 5 et 1 200 secondes (20 minutes).
|
- Contrôle d’accès Contrôle d’accès (renforcement de la sécurité de l’instance)
- Authentification de base : demandes SOAP