OTP API の不正利用を防ぐ | OTP 日本語

認証コード送信がスクリプトで連続リクエストされると、ユーザーの携帯電話に無関係な認証コードが大量に届き、残高が急速に消費され、チャネルの評価が低下するなどの問題が発生します。EngageLab OTP は送信側の頻度と量を制限できますが、業務側の未認証の「認証コードを取得」API までは止められません。

本稿では、プラットフォーム機能と業務側の防御を組み合わせ、API の不正利用リスクを下げる方法を説明します。

正しいアーキテクチャ

EngageLab OTP API はサーバー側からのみ呼び出してください。ブラウザ、App クライアント、ミニプログラムから直接リクエストしないでください。

ユーザー → フロントエンド（ログイン / 登録 / パスワードリセット） → バックエンド（セッション確認、ボット対策、業務側レート制限） → EngageLab OTP API（API キーを付与し、end_user_ip を渡す）

              
              ユーザー → フロントエンド（ログイン / 登録 / パスワードリセット）
     → バックエンド（セッション確認、ボット対策、業務側レート制限）
     → EngageLab OTP API（API キーを付与し、end_user_ip を渡す）

このコードブロックはフローティングウィンドウ内に表示されます

dev_key と dev_secret はサーバー側にのみ保管し、フロントエンドコード、アプリのパッケージ、公開リポジトリには置かないでください。
フロントエンドは自前の「認証コードを取得」API だけを呼び出し、https://otp.api.engagelab.cc に直接接続しないでください。
本番の API キーには呼び出し元 IP のホワイトリストを設定することを推奨します。詳しくは API キーを参照してください。

2 種類の IP を混同しない

設定 / パラメータ	入力する値	防ぐ対象
API キーの IP ホワイトリスト	サーバーの出口 IP	未知の IP が Key を使って OTP API を直接呼び出すこと
送信リクエストの `end_user_ip`	エンドユーザーの IP	同一ユーザー IP が短時間に認証コードを繰り返しリクエストすること

セキュリティセンターで「IP アドレスごと」の頻度制限を有効にした後、OTP 送信リクエストに end_user_ip を渡さないと、この制限は有効になりません。サーバーの IP ではなく、ユーザー端末のグローバル IP を渡してください。

プラットフォーム側の防御

OTP コンソールで次の設定を行い、送信側が不正利用された場合の損失を抑えます。

実施内容	設定場所	目的
API キーに IP ホワイトリストと有効期限を設定し、いつでも無効化できるようにする	API キー	呼び出し元を制限し、漏洩時にすぐ停止する
同一番号・同一 IP の送信頻度制限を有効にする	セキュリティセンター	単一番号・単一 IP の連打をブロックする
送信リクエストに `end_user_ip` を渡す	OTP 送信	IP ごとの頻度制限を有効にする
日次 / 月次の警告値と上限値を設定する	セキュリティセンター	量の異常時にアラートまたは自動停止する
国 / 地域のホワイトリストまたはブラックリストを設定する	セキュリティセンター	業務対象外の地域への送信を避ける
緊急時に SMS チャネルをワンクリックで一時停止する	セキュリティセンター	不正利用中に迅速に損失を抑える

送信量の警告または上限に達したときに通知を受け取るには、先に Webhook で該当するコールバックイベントを設定してください。

業務側の防御

プラットフォームの頻度制限は、自前の「認証コードを取得」API の防御の代わりにはなりません。EngageLab を呼び出す前に、次の検証を完了してください。

送信前にボット対策（画像認証や Turnstile / reCAPTCHA など）を行い、サーバー側で結果を検証する。
同一の携帯電話番号に再送間隔（例: 60 秒）を設定し、フロントエンドでカウントダウンを表示する。
アカウント、端末、IP ごとに分・時間・暦日のリクエスト上限を設け、失敗リクエストも回数に含める。
「認証コードを取得」にはログイン状態、または未ログイン時の有効なセッションが必要です。文脈のない公開送信入口を設けないでください。
同一認証コードの試行回数を制限し、検証成功後は直ちに無効化する。EngageLab OTP は、検証済みの認証コードの再検証をサポートしません。

エラーコードを不正利用のシグナルとして扱う

OTP 送信は、送信前検証で次のエラーを返すことがあります。これらが表示されたら再試行を緩め、集中リクエストがないか確認してください。

エラーコード	HTTP ステータス	意味
`3004`	400	同一テンプレート・同一宛先の頻度制限を超過。制限ウィンドウはテンプレート設定に従います
`6001`	429	同一携帯電話番号の送信頻度が上限を超過。ウィンドウは分、時間、または暦日の場合があります
`6002`	429	同一エンドユーザー IP の送信頻度が上限を超過。`end_user_ip` を渡した場合のみ検査します
`6003`	429	アプリケーション全体の日次または月次送信量が上限に達しました
`6007`	403	SMS 認証コード送信サービスが停止されています。全地域または現在の国 / 地域が停止されている可能性があります

HTTP 429 を受け取ったときは、すぐに連続再試行しないでください。継続する場合は、先にセキュリティセンターで送信量上限や緊急停止の状態を確認してから、サポートに連絡してください。

シークレットが漏洩したとき

OTP コンソールで API キーを無効化またはローテーションします。
セキュリティセンターで緊急停止を使い、SMS 送信を一時停止します。
送信履歴とコールバックで異常な送信を確認します。
API キーの IP ホワイトリストを絞り、日次 / 月次の送信上限が妥当か確認します。
リスクがなくなってから送信を再開します。

本番公開前チェックリスト

API はサーバー側からのみ呼び出しており、dev_secret はフロントエンド、アプリ、公開リポジトリに含まれていません。
本番の API キーにサーバー出口 IP のホワイトリストを設定済みです。
セキュリティセンターで番号の頻度制限を有効にしています。IP 制限が必要な場合、送信リクエストに end_user_ip を渡しています。
日次 / 月次の送信上限を設定し、量に関するコールバックを設定済みです。
「認証コードを取得」API は EngageLab 呼び出し前にボット対策と業務側レート制限を実施しています。
不正利用時の対応順を把握しています：Key を無効化 → 緊急停止 → 送信記録を確認。