安全なコールバック

Video API で使用する Webhook を、署名付きコールバックによってセキュリティ保護されるように設定できます。

セキュアコールバック機能は、WebhookコールバックリクエストがVonageから送信されたものであり、そのペイロードが転送中に改ざんされていないことを、アプリケーションがVerifyするための方法を提供します。リクエストを受信する際、受信側のコールバックWebhookの認証ヘッダーには、お客様の署名シークレットで署名されたJWTトークンが含まれます。

以下のAPIコールバックは、署名付きコールバックによってセキュリティ保護が可能であり、それぞれ独自の署名用シークレットを使用して設定できます：

  • セッション・モニタリング — コールバックURLを登録して、セッションのアクティビティを監視します。セッションイベントが検出されると、セッション監視用のWebhookコールバックが当該URLに送信されます。

  • アーカイブ監視 — コールバックURLを登録して、アーカイブのステータスを監視します。アーカイブの録画および生成されたファイルに関するステータスイベントを通知するために、アーカイブのコールバックが送信されます。

  • SIPコールモニタリング — コールバックURLを登録して、SIP通話の状況を監視します。SIP通話イベントが検出されると、そのURLにHTTPリクエストが送信されます。

  • ブロードキャスト・モニタリング — コールバックURLを登録して、ブロードキャストのアクティビティを監視します。ブロードキャストイベントが検出された際（たとえば、ブロードキャストが作成、更新、または破棄されたときなど）、ブロードキャストのコールバックイベントが送信されます。

  • エクスペリエンス・コンポーザーのモニタリング — コールバックURLを登録して、Experience Composerの動作を監視します。Experience Composerのステータスが変更されると、Experience Composerのコールバックイベントが送信されます。

  • ライブ・キャプション・モニタリング — コールバック URL を登録して、ライブキャプションの動作を監視します。ライブキャプションのコールバックイベントは、ライブキャプションの開始、停止、およびエラー発生時に送信されます。

安全なコールバックの設定

以下の手順に従って、セキュアなコールバックによるセッションモニタリングを有効にすることができます。また、他のコールバック（アーカイブモニタリング、SIPコールモニタリング、エクスペリエンスコンポーザーモニタリングなど）についても、同様の手順に従うことができます。

  1. ログイン Vonage Video API アカウント.

  2. 左側のメニューから、目的のAccountを選択してください。

  3. 左側のメニューから、セキュアコールバックを登録したいプロジェクトを選択してください。

  4. 探す セッション監視 （または該当するセクション）をクリックして 設定.

  5. ユーザーインターフェースには、コールバックURLや（オプションで）署名用シークレットを設定するためのオプションが含まれています。

  6. 署名秘密フィールドが有効になるたびに、ランダムに生成された署名秘密がシステムから提供される。この事前に入力された署名の秘密の値は、使用することも、ユーザーが選択した値で上書きすることもできます。コールバックを受信すると、受信したウェブフックはフィールドに設定された署名秘密で署名されます。をクリックします。 送信 このシークレットを、セキュアなコールバックに使用するように設定します。（注：署名用シークレットは文字列でなければならず、長さは1文字以上50文字以下でなければなりません。）

  7. システムは、URLと署名シークレットを使用してセキュアコールバックが設定されたことを通知します。なお、プラットフォームに設定が反映されるまで、最大30分ほどかかる場合がありますのでご注意ください。

安全なコールバックの検証

セキュアなコールバックを検証することで、以下のようなセキュリティ上の利点がある：

  • リクエストがVonageから発信されたものであることを確認する機能

  • 転送中にメッセージが改ざんされていないことの確認

  • インターセプトとリプレーに対するディフェンス

安全なコールバックの検証には2つの部分がある：

  • リクエストの検証

  • ペイロードの検証（オプション）

リクエストの検証

コールバックはAuthorizationヘッダーにJWTを含む。JWTクレームに含まれるAPIキーを使用して、どの署名秘密がリクエストに署名するために使用されたかを識別する。リクエストに署名するために使用される秘密鍵は、JWTクレームに含まれるapi_keyに関連付けられた署名秘密鍵に対応する。署名の秘密は Vonage Video API アカウントポータル.

ペイロードが輸送中に改ざんされていないことを検証する。

リクエストの正当性を確認したら、オプションとして、ペイロードの SHA-256 ハッシュ値を JWT クレーム内の `payload_hash` フィールドと比較することで、リクエストのペイロードが改ざんされていないかを確認できます。これらが一致しない場合、転送中にペイロードが改ざんされたことになります。 ペイロードのVerifyが必要なのは、HTTPSではなくHTTPを使用している場合のみです。これは、トランスポート層セキュリティ（TLS）によって MITM攻撃.

コード例

以下のExpressの例では、Webhookの署名をVerifyする方法を示しています。クライアント側とサーバー側の両方でリクエストとレスポンスが確実に暗号化されるため、HTTPSプロトコルを使用することをお勧めします。

const express = require('express');
const jwt = require('jsonwebtoken');
const sha256 = require('js-sha256');
const app = express();


app.use(express.json());

const VONAGE_API_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const userAgent = request.headers['user-agent'];
    if (userAgent !== 'Vonage/Callback/v1.0') {
      console.log('Bad token detected');
      return response.status(401).send();
    } else {
      const payload = request.body;
      let token = request.headers.authorization.split(" ")[1];
      // replace VIDEO_CALLBACK_SECRET with the secret value set at the Dashboard
      var decoded = jwt.verify(
        token,
        VONAGE_API_SIGNATURE_SECRET,
        { algorithms: ['HS256'] },
        );
      if (sha256(JSON.stringify(payload)) != decoded['payload_hash']) {
        console.log('tampering detected');
        response.status(401).send();
      }
    }
    console.log('Success');
    return response.status(204).send();
  } catch (err) {
    if (err instanceof JsonWebTokenError  || err instanceof TokenExpiredError){
      console.log('Token Error', err.message);
    } else {
      console.error(err);
    }
    return response.status(401).send();
  }
});

app.listen(4242, () => console.log('Running on port 4242'));

既知の制限／考慮事項

次のセクションでは、この機能を有効にする前の制限と考慮事項について説明します。

コールバックIPアドレス

セキュアコールバックを有効にすると、Vonageコールバックサービスで使用されるIPアドレスの範囲は、以前のVideo APIコールバックとは異なります。Vonageセキュアコールバックとのシームレスな通信を可能にするには、以下の範囲を許可してください： 216.147.0.0/18.

相互TLS (mTLS)

セキュアコールバックフローでは mTLS がサポートされています（以前はサポートされていませんでした）。

コールバックの再試行およびバックオフポリシーの変更

セキュアコールバックを有効にすると、コールバックの再試行とバックオフポリシーの動作が変更される。

なお、再試行が行われるのは接続に関する問題の場合のみであり（その他のエラーについては行われません）、ご注意ください。

アプリケーションのコールバックイベントがダウンしたらどうなりますか？

  • これまでの動作：Vonageは、アプリケーションサーバーへの配信に失敗した各イベントについて、4回再試行を行います。

    セッションモニタリングのみ - プラットフォームが30分間に50件の配信失敗を検出した場合、セッションモニタリングのコールバックに対するイベント転送が無効化されました。 コールバックが無効化されたことを通知するため、お客様宛てに通知メールが送信されました。イベント転送を再度有効にするには、Vonage Video API アカウントポータルからセッションモニタリングのコールバック URL を再設定する必要があります。

  • 新しい動作：24時間経過すると、個別のコールバックの再試行ロジックは停止し、その個別のコールバックイベントは送信されなくなります。ただし、新しいイベントに対するコールバックの再試行は引き続き行われます。

重要だ： 配信失敗が過度に発生した場合でも、新しいサービスではリトライおよびバックオフの仕組みが採用されるため、イベントの転送が無効化されることはなくなります。したがって、新しいサービスではコールバックが一切停止・無効化されないため、コールバックが無効化されており、再有効化が必要であることを通知するメールが送信されることはもうありません。