コンテンツにスキップ

2FA（OTP）セットアップとAPI実装ガイド

このページでは、2FA（OTP）の基本概念から、APIを使った送信・検証の具体的な実装フローまでをまとめて解説します。

2FA と OTP の基本

2FA は、ユーザーがアカウントにアクセスしたり重要な操作を行ったりする前に、複数の認証要素で本人確認する仕組みです。 NTT CPaaS の 2FA API では、SMS・メール・Voice などのチャネルを使って OTP を配信し、その入力値を検証できます。

代表的な用途

  • パスワードに加える追加認証
  • 電話番号だけを使う本人確認
  • パスワードレスログインの補助
  • 高リスク操作前の追加確認

実装のワークフロー

実装全体の流れは以下のようになります。

sequenceDiagram
    participant App as アプリケーション
    participant API as NTT CPaaS 2FA API
    participant User as ユーザー

    App->>API: アプリケーション作成
    API-->>App: applicationId
    App->>API: メッセージテンプレート作成
    API-->>App: messageId
    App->>API: OTP送信
    API-->>App: pinId
    API->>User: OTPを配信
    User->>App: OTPを入力
    App->>API: pinId + pin で検証
    API-->>App: 検証結果

1. 事前準備：APIとチャネルのセットアップ

まず、2FA API を呼び出せる状態にし、利用するチャネルの送信条件を満たしておきます。 - SMS: 送信元や利用条件を確認する - Voice: 音声チャネルの準備を行う - メール: 標準メール機能とテンプレート設定を完了する

2. アプリケーションを作成する

2FA アプリケーションは、OTP の振る舞いを定義する単位です。ユースケース（登録時、パスワード変更時など）ごとに分ける設計が向いています。

POST /2fa/2/applications
Content-Type: application/json
Authorization: App {API_KEY}


{
    "name": "2FAサンプル",
    "pinAttempts": 5,
    "pinTimeToLive": "300s"
}
アプリケーション作成後のレスポンスには applicationId が含まれます。以後の OTP 送信で必須です。

3. メッセージテンプレートを作成する

テンプレートには OTP の差し込み位置を表す {{pin}} を必ず含めます。1 つのアプリケーションの下に複数テンプレートを作成できるため、言語別や用途別に分けられます。

POST /2fa/2/applications/{appId}/messages
Content-Type: application/json
Authorization: App {API_KEY}


{
    "pinType": "NUMERIC",
    "messageText": "認証コードは {{pin}} です。",
    "pinLength": 4,
    "senderId": "NTTCPAAS"
}
テンプレート作成後のレスポンスには messageId が含まれます。OTP 送信時に使用します。

4. OTP を送信する

アプリケーションとテンプレートの準備ができたら、applicationId と messageId を指定して OTP を送信します。

POST /2fa/2/pin
Content-Type: application/json
Authorization: App {API_KEY}


{
    "applicationId": "YOUR_APPLICATION_ID",
    "messageId": "YOUR_MESSAGE_ID",
    "from": "NTT CPaaS 2FA",
    "to": "819012345678"
}
送信成功時には pinId が返ります。これは OTP 検証で必須です。

pinId を失うと検証できません

送信処理の直後に pinId をアプリケーション内の認証セッションへ保存してください。

5. OTP を検証する

OTP を検証する際は、pinId とユーザー入力の PIN を使用します。

POST /2fa/2/pin/{pinId}/verify
Content-Type: application/json
Authorization: App {API_KEY}


{
    "pin": "1598"
}
最終レスポンスには検証結果が含まれます。

実装時のポイントと確認事項

  • アプリケーションはユースケース単位で分ける: 登録時とパスワード変更時を分けることで、有効期限や送信制限を個別に調整できます。
  • テンプレートは言語別に分けられる: 同じ applicationId 配下に複数の messageId を持たせれば、多言語対応や文面切り替えがしやすくなります。
  • 送信と検証のログを残す: 調査しやすくするため、少なくとも applicationId、messageId、pinId、宛先、送信時刻、検証結果を記録しておいてください。

詳細なエンドポイントやパラメータは 2FA API リファレンスを参照してください。

次に読む