SOAP Web サービス
Simple Object Access Protocol (SOAP) は、HTTP 経由で Web サービスにアクセスするための XML ベースのプロトコルです。
Web サービスプロバイダー
- ダイレクト Web サービス：URL クエリを使用してテーブルの WSDL を要求します。
- SOAP Web サービスインポートセット：インポートテーブルと変換マップを使用して、テーブルの Web サービス要求を自動化します。
- スクリプト化された SOAP Web サービス：カスタム JavaScript を使用して SOAP Web サービス要求を実行します。
WSDL
すべてのテーブルとインポート セットは、そのテーブルスキーマと利用可能な操作を記述する Web サービス定義言語 (WSDL) XML ドキュメントを動的に生成します。
https://myinstance.service-now.com/incident.do?WSDL
動的に生成され、HTTP を介してアクセス可能なすべての ServiceNow WSDL は、Open Source Initiative OSI - Apache ライセンス、バージョン 2.0 のライセンス契約で定義された条件に基づいて使用できます。
長時間実行される SOAP 要求のサポート
ServiceNow AI Platform は、要求の処理中にネットワーク接続の滞留アクティビティによるソケットタイムアウトを防ぐことで、実行時間の長い SOAP 要求をサポートします。
この機能により、多数のレコードを要求するとき、集計クエリを実行するとき、またはソートが必要な order by 式を使用するときに、ODBC Driver の効率が向上します。
デフォルトでは、ServiceNow によって提供される ODBC Driver や MID Server などの Web サービスクライアントに対してタイムアウト保護が提供されます。システムプロパティを使用して、カスタム Web サービスにタイムアウト保護を追加できます。
タイムアウト保護
Web サービスクライアントは、307-Temporary Redirect を受信して長時間セッションを維持し、ソケットの滞留によるタイムアウトを防止します。ステータスコードをサポートする Web サービスクライアントは、307-Temporary Redirect により、HTTP 場所ヘッダーで指定された場所に最後の要求を繰り返します。場所ヘッダーの値は、Web サービスクライアントが最初に指定した URL と同じです。307-Temporary Redirect の使用は WS-I に準拠しています。
- glide.soapprocessor.allow_long_running_threads の値が true です。
- 要求に redirectSupported=true URL パラメーターが含まれています。
- 要求がセッション認識型です (HTTP cookie をサポートしています)。
- リダイレクトの数が glide.soap.max_redirects で設定された値を超えていません。
SOAP Web サービスのセキュリティ
インスタンスは、HTTP プロトコルを介した基本のチャレンジ/レスポンス認証と Contextual Security を使用したシステムレベルのアクセス制御リスト (ACL) との組み合わせを使用して、Web サービスセキュリティを強制します。管理者は、Web サービスユーザーに SOAP ロールの 1 つを付与することで、ユーザーがアクセスできるシステムリソースを制御できます。
SOAP ロール
SOAP Web サービスを使用するには、実行する操作に適したロールが必要です。また、ターゲットテーブルにアクセスするために必要な他のロールも必要です。
| ロール | 説明 |
|---|---|
| soap | すべての SOAP 操作を実行できます。 |
| soap_create | 新規レコードを挿入できます。 |
| soap_delete | 既存のレコードを削除できます。 |
| soap_ecc | キュー [ecc_queue] テーブルのレコードをクエリ、挿入、削除できます。 |
| soap_query | レコード情報のクエリを実行できます。 |
| soap_query_update | 拡張クエリパラメーター |
| soap_script | .do エンドポイントを指定するスクリプトを実行できます。このロールは、スクリプト化された Web サービスを実行するために必要です。 |
| soap_update | レコードを更新できます。 |
| import_admin | インポートセットとインポートのあらゆる側面を管理できます。インポートセット行 [sys_import_set_row] テーブルへのアクセスに必要です。 |
| import_transformer | インポートセットの変換マップを管理し、変換を実行できます。インポートセット行 [sys_import_set_row] テーブルへのアクセスに必要です。 |
デフォルトの Web サービスロールの要件
デフォルトでは、プロセッサーの一連の ACL ルールでは、WSDL、XSD、および XML スキーマ要求を行うために soap_query ロールが必要です。
これらのロール要件を変更する場合は、ACL ルールを無効にすることができます。
基本認証
WSDL または SOAP メッセージ要求ごとにインスタンスに関連付けられたユーザーに対して基本認証を強制するために、管理者はプロパティ glide.basicauth.required を true に設定できます。
有効にすると、WSDL および SOAP の各要求には、基本認証プロトコルで指定されているように「認証」ヘッダーを含める必要があります。
Web サービス要求は非インタラクティブであるため、要求の実行中は常に認証ヘッダーが必要になります。
(必要かどうかに関わらず) すべての要求で基本認証資格情報を提供すると、基本認証資格情報で提供されたユーザーを Web サービスの呼び出しに関連付けることができるというメリットがあります。たとえば、インシデントレコードの作成時、ジャーナルフィールドには、デフォルトのゲストユーザーではなく、基本認証ヘッダーに含まれるユーザー ID のリストが表示されます。
SOAP セキュリティポリシー
- 外部 Web サービスの使用時に SOAP 要求の署名を有効または無効にします。
- WS-Security を介して通信するときに SOAP 要求が満たす必要がある認証要件を指定します。
SOAP アクセスポリシーの詳細については、「 SOAP API アクセスポリシー」を参照してください。
署名済み SOAP 要求に必要な証明書
WS-Security 通信の SOAP 要求に署名するには、次の証明書が必要です。
- 要求者からの X.509 証明書
- 要求者の証明書に署名した認証局の X.509 CA 証明書
SOAP デフォルトセキュリティポリシー
管理者は、インスタンスが使用する SOAP セキュリティポリシーをシステムプロパティ glide.soap.default_security_policyで指定できます。glide.soap.default_security_policy システムプロパティは、Web Services-Security (WSS) を受信要求に強制するときにインスタンスが使用する SOAP セキュリティポリシーの名前を指定します。
| フィールド | 説明 |
|---|---|
| タイプ | 文字列 |
| デフォルト値 | デフォルトセキュリティポリシー |
| 場所 | システムプロパティ [sys_properties] テーブルへのシステムプロパティの追加 |
WS セキュリティを使用
- 既知の送信者からの SOAP メッセージの確認
- 送信中に SOAP メッセージが変更されていないことの確認
WS-Security は基本認証で動作するように意図されています。インスタンスが SOAP メッセージを受信すると、基本認証ヘッダーを確認して、SOAP ユーザーがインスタンスに対する権限を持っているかどうかを判断します。WS-Security ヘッダーを確認して、受信メッセージの有効性を判断します。中間者攻撃などの攻撃の影響を受ける要求は、無効な WS-Security ヘッダーを持っており、ブロックされます。
WS-Security プロファイル
WS-Security プロファイルは、WS-Security が有効になっている場合の Web サービスメッセージの認証方法を決定します。次のメカニズムを使用して、Web サービス要求を認証できます。
| 認証メカニズム | 説明 |
|---|---|
| 証明書の検証 | 要求に関連付けられた証明書を検証します。要求の証明書を検証するには、要求者の証明書と認証局をアップロードする必要があります。 |
| ユーザー資格情報 | 要求に関連付けられたユーザー資格情報を確認して、Web サービス要求を認証します。このタイプの認証では、要求の資格情報が既存のユーザーの資格情報と一致すること、または要求の資格情報がプロファイルレコードで指定されたユーザー名とパスワードと一致することを確認できます。 |
WS-Security プロファイルモジュールには、現在有効な WS-Security プロファイルがリストされます。
WS-Security エラーログ記録
glide.processor.debug.SOAPProcessor システムプロパティを使用すると、WS-Security に関するエラーメッセージをトランザクションログに表示できます。
システムプロパティ glide.processor.debug.SOAPProcessor は、証明書やキーストアのチェックなどの SOAP 処理のデバッグメッセージを有効 (true) または無効 (false) にします。
| フィールド | 説明 |
|---|---|
| タイプ | True | False |
| デフォルト値 | false |
| 場所 | システムプロパティ [sys_properties] テーブルへのシステムプロパティの追加 |
WSS X.509 トークンプロファイル
- サブジェクト名
- 発行者名
- シリアル番号
- 有効間隔
Web Services Security: SOAP Message Security specification (Web サービスセキュリティ：SOAP メッセージセキュリティ仕様) で定義されている通りに X.509 認証フレームワークを使用します。
証明書をアップロードして、[X509 証明書] フィールドで参照します。バインドされたセッションの場合は、WS-Security 認証が成功したときになりすますユーザーを選択します。
WSS ユーザー名トークンプロファイル
X.509 トークンプロファイルを指定するときに、SOAP 要求のユーザー名トークンも指定できます。
ユーザー名トークンは、「ユーザー名」で要求者を識別する手段として使用され、オプションでパスワード、共有シークレット、またはパスワードと同等のものを使用して、その ID を証明します。
ユーザー名トークンを認証する方法は 2 種類あります。
- 既存のユーザー資格情報を使用して認証する方法。
図 : 5. 既存のユーザー資格情報を使用した認証 受信 SOAP 要求のユーザー名を使用して、指定された [ユーザー] フィールドで UserName 値に一致するユーザーを検索します。受信ユーザー名トークンのパスワード値を使用して、要求が認証されます。[セッションのバインド] オプションを選択すると、認証に成功したユーザーがセッションに使用されます。
- 指定されたユーザー資格情報を使用して認証する方法。
図 : 6. 指定されたユーザー資格情報を使用した認証 ユーザーテーブル内のユーザーに関連しないログイン資格情報を使用して認証します。[セッションのバインド] オプションが選択されている場合、[ユーザーとして実行] フィールドで指定されているユーザーがセッションに使用されます。
Web サービスの厳格なセキュリティ
デフォルトでは、Web サービスの基本認証では、ユーザーが SOAP 接続を使用してインスタンスにアクセスする権限があるかどうかのみが判断されます。許可されると、すべてのユーザーが Web サービスとして公開されたテーブルにアクセスできるようになります。
システムプロパティ [着信 SOAP 要求に厳格なセキュリティを適用する] は、この動作を変更し、ユーザーが Web サービスからインスタンスリソースにアクセスするために コンテキストセキュリティマネージャー の要件を満たす必要があります。
このプロパティを有効にすると、適切な SOAP ロールを持ち、テーブルと操作の ACL 条件を満たすユーザーのみが、SOAP 接続からその操作を実行できます。
Web サービスの相互認証
相互認証は、送信 Web サービスでサポートされています。
SOAP セッションの管理とレポート
SOAP セッションは、Web サービスクライアントアプリケーション、ServiceNow MID Server、ServiceNow ODBC Driver などの外部 SOAP クライアントによりインスタンスで確立された Glide セッションです。SOAP セッションは、次のユーザーのセッションのリストに含まれています。 .?SOAP URL は SOAP セッションを識別します。
SOAP セッションプロパティ
SOAP セッションの維持方法を制御するプロパティがあります。
| プロパティ | 説明 |
|---|---|
| glide.soap.invalidate_session_timeout | アクティブなセッションを開いたままにする期間 (秒)。この期間に達すると、インスタンスはセッションを非アクティブ化し、システムリソースを再利用します。タイムアウト期間に達した後にクライアントが別の要求を送信すると、インスタンスは新しいセッションを確立します。 このプロパティは、5 〜 1200 秒 (20 分) の値を受け入れます。
|