API連携
FAX API・Webhookのセキュリティ設定
キー管理と二重送信対策
FAX APIは基幹システムから送信・取得を自動化し、Webhookは受信や送信結果をリアルタイムで通知できます。その一方、漏えいしたキーや権限設定の誤りは、FAX原本の取得や外部送信へ直結します。
最低限の構成
- 用途別APIキーと最小権限スコープ
- TLS、秘密管理、失効・ローテーション
- 送信APIの冪等性キーと状態照会
- Webhookの署名・時刻・イベントID検証
- 要求ID、FAXジョブID、結果の監査
APIキー管理10項目
- 送信、参照、OCRなど用途ごとにキーを分ける。
- 必要なテナント・操作だけを許可する。
- 開発、検証、本番のキーを分離する。
- ソースコード、Git、チケット、チャットへ記載しない。
- 秘密管理サービスから実行時に取得する。
- ログ、エラー、画面ではキーをマスクする。
- 可能なら接続元IP/CIDRを制限する。
- 有効期限、最終利用、作成者、用途を棚卸しする。
- 漏えい時に即時失効し、新旧キーを安全に切り替える。
- 退職・委託終了・システム廃止時に削除する。
OWASP API Security Top 10では、オブジェクト単位・機能単位の認可不備が主要リスクとして整理されています。キーが有効でも、別テナントのFAXや管理操作を呼び出せないことが必要です。
送信APIの二重送信を防ぐ
タイムアウトは「FAX送信に失敗した」ことを意味しません。サーバー側では受け付け済みでも、応答だけ届かなかった可能性があります。同じ要求をそのまま再実行すると二重送信になり得ます。
- 業務処理ごとに一意な冪等性キーを発行する。
- タイムアウト時は同じキーで再試行するか、状態照会する。
- FAXジョブIDと業務側IDを保存する。
- 成功、失敗、処理中、再試行可能を区別する。
- 利用者の手動再送と自動再試行を同じ監査画面で確認する。
Webhook受信チェック
| 確認 | 目的 |
|---|---|
| HTTPS | 通信中の盗聴・改ざんを抑える |
| 署名／共有秘密 | 正規の配信元で本文が変わっていないか確認 |
| 時刻・許容時間 | 古い正規リクエストの再送攻撃を抑える |
| イベントID | 再配信されても後続処理を一度だけ実行 |
| 先に受領、後で処理 | 短時間で2xxを返し、重いOCR・基幹登録はキューへ分離 |
| 失敗・再試行ログ | 欠落、遅延、重複を調査 |
署名方式はサービスごとに異なります。提供された生のリクエスト本文を使う、比較を一定時間で行う、時刻を検証するなど、サービス公式手順に従います。
SP-FAXの現在の範囲
SP-FAXはAPIキーごとのFAX送信・参照・OCR等の権限スコープ、有効期限・失効・最終利用日時、IPv4/CIDR制限、テナント単位のレート制御、冪等性キー、API操作監査を提供します。Webhook通知は利用できますが、監査ログをSIEMへ自動送信する監査Webhookは今後追加予定です。両者を混同しないでください。
APIセキュリティの提供状況、調査項目はFAX監査ログを参照してください。
参考資料
よくある質問
Q. APIキーを環境変数に入れれば安全ですか？
十分とは限りません。秘密管理、閲覧権限、マスキング、ローテーションを組み合わせます。
Q. IP制限があれば認証は不要ですか？
不要にはなりません。認証、最小権限、TLS、監査への追加防御です。
Q. Webhookの二重受信は異常ですか？
再試行で複数回届く場合があります。イベントIDで後続処理を一度にします。