Webhookのセキュリティ

Webhookのセキュリティ

お知らせ:当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Zoho Signでは、エンドポイントに送信される要求の認証(Zoho Signから送信されたことの確認)と、各ペイロードの整合性の検証(改ざんされていないことの確認)という2つの方法でWebhookを保護できます。どちらもWebhookの作成時または編集時に[セキュリティ設定]で設定でき、組み合わせることで保護を強化できます。

認証

認証は、エンドポイントの呼び出し元を確認するためのものです。[設定]→[開発者向け設定]→[Webhook]→[セキュリティ設定]→[認証]で、1つ以上の認証方法を有効にします。

ベーシック認証

HTTPベーシック認証を使用して、ユーザー名とパスワードでWebhookエンドポイントを保護できます。ベーシック認証を有効にし、エンドポイントでの検証に使用するユーザー名とパスワードを入力します。

メモ:認証情報はBase64でエンコードされ、すべてのWebhook要求のAuthorizationヘッダーで送信されます。

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

// ベーシック認証ヘッダーの生成方法:

credentials = 'username:password'

encoded = base64(credentials)

header = 'Basic ' + encoded

OAuth 2.0

OAuth 2.0を使用してWebhookを認証します。Zoho Signは、クライアント認証情報による付与方式でトークンURLからアクセストークンを取得し、すべてのWebhook要求のAuthorizationヘッダーでBearerトークンとして送信します。

  1. OAuth 2.0を有効にし、プロバイダーを選択します。
  2. トークンURL、クライアントID、クライアントシークレットを入力します。
  3. (任意)スコープを入力します。
  4. (任意)[追加パラメーター]で、トークン要求の本文にそのまま含めて送信する独自の名前と値の組み合わせ(例:audience)を追加します。さらに追加するには、[+]アイコンをクリックします。
メモ
メモ:OAuth 2.0とベーシック認証は同時に有効にできません。一方を有効にすると、もう一方は無効になります。

Authorizationヘッダーの例:

Authorization: Bearer <access_token>

// アクセストークンは、クライアントIDとクライアントシークレットを使用し、

// クライアント認証情報による付与方式でトークンURLから取得され、有効期限が切れるまでキャッシュされます。

相互TLS(mTLS)

相互TLS検証用のクライアント証明書を使用して、Webhookエンドポイントを認証できます。相互TLS(mTLS)を有効にし、次のいずれかの形式で証明書を指定します:
  1. クライアント証明書(.pem)と秘密鍵(.pem/.key)。鍵が暗号化されている場合は、鍵のパスワードも指定します。または、
  2. PFX/P12証明書ファイルと、その鍵のパスワード。
メモ
メモ:2つのクライアント証明書形式のうち、一度に有効にできるのは1つのみです。

カスタム要求ヘッダー

認証の追加やルーティングのために、すべてのWebhook要求に独自のHTTPヘッダーを付加できます。

設定手順は次のとおりです:
  1. [カスタム要求ヘッダー]を有効にし、[ヘッダー名]と[ヘッダー値]を入力します。
  2. 別のヘッダーを追加するには、[+]アイコンをクリックします。カスタムヘッダーは最大5つまで追加できます。

整合性

整合性の設定では、ペイロードが正当なものであり、改ざんされていないことを確認します。[設定]→[開発者向け設定]→[Webhook]→[セキュリティ設定]→[整合性]で設定します。

HMAC署名

Zoho SignからWebhookが送信されると、要求ヘッダーにX-ZS-WEBHOOK-SIGNATUREという名前でHMAC署名が含まれます。Webhook要求を受信したアプリケーションは、同じシークレットキーを使用してHMAC署名を生成し、その結果を要求ヘッダーの値と比較します。値が一致すればデータは正当なものと判断され、一致しなければ改ざんされていると判断されます。Zoho SignはHMAC-SHA256アルゴリズムを使用してWebhookペイロードの署名を計算し、その結果をBase64形式で要求ヘッダーに含めて送信します。サンプルデータを用いた説明はこちらです:

payload
{{'requests':{'request_name':'Test Name'},'notifications':{'operation_type':'RequestSigningSuccess'}}
secret_key
thisisthesamplekeyfortestingpurposes
base64encode(HMAC SHA-256(payload+secret_key))
drbSrM4H816RYKpZiRBLddUa0yHaTrwjtY04sIZFZus=

こちらは、このWebhook要求ヘッダー(HMACヘッダー)の表示例です:


受信側アプリケーションでのHMAC署名の検証

  1. JSON形式で読み込むとキーの順序が変わる可能性があるため、ペイロードは必ず文字列として読み込んでください。
  2. シークレットキーを使用してペイロードのHMAC SHA-256ハッシュを計算し、結果をBase64でエンコードします。
  3. 手順2で取得した値を、受信したHMACヘッダー(X-ZS-WEBHOOK-SIGNATURE)の値と比較します。一致しない場合は、Webhook要求を拒否してください。


HMAC署名を検証するJavaのサンプルコード

  1. private static String verifyHmacHash(String secretKey, String payload, String hmacHash) throws Exception
  2. {
  3. String macAlgoName = 'HmacSHA256';
  4. byte[] secretKeyBytes = secretKey.getBytes(StandardCharsets.UTF_8);
  5. Mac mac = Mac.getInstance(macAlgoName);
  6. SecretKeySpec keySpec = new SecretKeySpec(secretKeyBytes, mac.getAlgorithm());
  7. mac.init(keySpec);
  8. byte[] macData = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
  9. String calculatedHmac = java.util.Base64.getEncoder().encodeToString(macData);
  10.         
  11. if(hmacHash.equals(calculatedHmac))
  12. {
  13.         System.out.println('Hashes match, Webhook payload is valid!!');
  14. }
  15. else
  16. {
  17.         System.out.println('Hashes doesn't match, Webhook payload is tampered!!');
  18. }
  19. return calculatedHmac;
  20. }

タイムスタンプ

タイムスタンプを有効にすると、正当な要求を傍受して後から再送信するリプレイ攻撃の防止に役立ちます。
  1. [整合性]で、[タイムスタンプを有効にする]を有効にします。
  2. Zoho Signは各要求に、X-ZS-WEBHOOK-SIGNATUREヘッダーとともにX-ZS-WEBHOOK-TIMESTAMPヘッダーを追加します。
  3. アプリケーション側では、タイムスタンプが短い許容時間の範囲を外れている要求を拒否し、HMAC署名の検証時にはタイムスタンプも含めてください。
要求ヘッダーの例:
x-zs-webhook-timestamp: 1704067200

X-ZS-WEBHOOK-SIGNATURE: 5d41402abc4b2a76b9719d911017c592
メモ
メモ:タイムスタンプを有効にすると、Webhookの設定画面に、そのまま使用できる検証用サンプルコードが表示されます。