SOAP Web Services
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 を介してアクセス可能な WSDL ServiceNow 動的に生成および提供されるすべての条件は、Open Source Initiative OSI - Apache ライセンス、バージョン 2.0 ライセンス契約で定義されている条件に基づいて使用できます。
長時間実行される SOAP 要求のサポート
ServiceNow AI Platform は、要求の処理中にネットワーク接続が非アクティブになることによるソケットのタイムアウトを防ぐことで、長時間実行される SOAP 要求をサポートします。
この機能により、多数のレコードを要求する場合、集計クエリを実行する場合、または並べ替えが必要な順序式を使用する場合の ODBC ドライバーの効率が向上します。
デフォルトでは、ODBC ドライバーや MID サーバーなどの ServiceNow によって提供される Web サービスクライアントに対してタイムアウト保護が提供されます。システムプロパティを使用して、カスタム Web サービスにタイムアウト保護を追加できます。
タイムアウト保護
Web サービスクライアントは、長いセッションを存続させ、ソケットの非アクティブによるタイムアウトを防ぐために、307-Temporary リダイレクトを受け取ります。307-Temporary Redirect を使用すると、ステータスコードをサポートする Web サービスクライアントは、HTTP ロケーションヘッダーで指定された場所に最後の要求を繰り返します。location ヘッダーの値は、Web サービスクライアントが最初に指定した URL と同じです。307-一時リダイレクトの使用は WS-I に準拠しています。
- glide.soapprocessor.allow_long_running_threads の値は true です。
- 要求には redirectSupported=true URL パラメーターが含まれています。
- 要求はセッション対応です (HTTP cookie をサポート)。
- リダイレクトの数が glide.soap.max_redirects で設定された値を超えていません。
SOAP Web Services のセキュリティ
インスタンスは、HTTPS プロトコルを介したベーシック認証のチャレンジ/レスポンスと、コンテキストセキュリティを使用したシステムレベルのアクセス制御リスト (ACL) の組み合わせを使用して、Web サービスセキュリティを適用します。アドミニストレーターは、Web サービスユーザーにいずれかの SOAP ロールを付与することで、ユーザーがアクセスできるシステムリソースを制御できます。
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 サービスセキュリティ (WSS) を適用するときにインスタンスが使用する SOAP セキュリティポリシーの名前を指定します。
| フィールド | 説明 |
|---|---|
| タイプ | 文字列 |
| デフォルト値 | デフォルトのセキュリティポリシー |
| ロケーション | システムプロパティ [sys_properties] テーブルへのシステムプロパティの追加 |
WS-Security を使用
- 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 トークンプロファイル
- サブジェクト名
- 発行者名
- serial number
- 有効期間
Web サービスセキュリティ:SOAP メッセージセキュリティ仕様で定義されている X.509 認証フレームワークを使用します。
証明書をアップロードし、[ X509 証明書] フィールドで参照します。バインドされたセッションの場合は、WS-Security 認証が成功したときに代理操作するユーザーを選択します。
WSS ユーザー名トークンプロファイル
X.509 トークンプロファイルを指定する場合は、SOAP 要求でユーザー名トークンを指定することもできます。
ユーザー名トークンは、要求者を「ユーザー名」で識別する手段として使用され、オプションでパスワード、共有秘密、または同等のパスワードを使用してその ID を認証します。
ユーザー名トークンを認証するには、2 つの方法があります。
- 既存のユーザー認証情報で認証します。
図 : 5. 既存のユーザー認証情報で認証 着信 SOAP 要求のユーザー名を使用して、UserName 値と一致するように指定された [ユーザー] フィールドでユーザーを検索します。システムは、受信ユーザー名トークンのパスワード値を使用して要求を認証します。[ セッションのバインド] オプションを選択すると、正常に認証されたユーザーがセッションに使用されます。
- 指定されたユーザー認証情報で認証します。
図 : 6. 指定されたユーザー認証情報で認証 ユーザーテーブルのユーザーとは無関係のログイン認証情報を使用して認証します。[ セッションのバインド] オプションを選択すると、[ ユーザーとして実行 ] フィールドで指定されたユーザーがセッションに使用されます。
Web サービスの厳格なセキュリティ
デフォルトでは、Web サービスのベーシック認証では、ユーザーが SOAP 接続を使用してインスタンスにアクセスする権限を持っているかどうかのみが判断されます。認証されると、すべてのユーザーが Web サービスとして公開された任意のテーブルにアクセスできるようになります。
システムプロパティ [着信 SOAP 要求に厳格なセキュリティを強制する (Enforce strict security on incoming SOAP requests )] ではこの動作が変更され、ユーザーが Web サービスからインスタンスリソースにアクセスするために コンテキストセキュリティマネージャー の要件を満たす必要があります。
このプロパティを有効にすると、適切な SOAP ロールを持ち、テーブルと操作の ACL 条件も満たしているユーザーのみが、SOAP 接続からその操作を実行できます。
Web サービスの相互認証
送信 Web サービスでは相互認証がサポートされています。
SOAP セッションの管理とレポート
SOAP セッションは、Web サービスクライアントアプリケーション、 ServiceNow MID サーバー、 ServiceNow ODBC ドライバーなどの外部 SOAP クライアントによってインスタンスで確立される Glide セッションです。SOAP セッションは、のユーザーセッションのリストに含まれています . の ?SOAP URL は SOAP セッションを識別します。
SOAP セッションプロパティ
特定のプロパティは、SOAP セッションの維持方法を制御します。
| プロパティ | 説明 |
|---|---|
| glide.soap.invalidate_session_timeout | アクティブなセッションが開いたままになる期間 (秒)。この期間に達すると、インスタンスはセッションを非アクティブ化し、システムリソースを再利用します。タイムアウト時間に達した後にクライアントが別の要求を送信すると、インスタンスは新しいセッションを確立します。 このプロパティは、5 〜 1200 秒 (20 分) の値を受け入れます。
|