2FA APIの活用法

NTT CPaaSの2FA APIは、一般的な2FA (OTP) のセットアップ手順で説明しているプロセスに従って標準のワンタイムパスワード (OTP) の検証を行います。

実装を開始する前に、2FA機能が正しくセットアップされているかを検証し、OTPトラフィックを送信する準備がすべて整っていることを確認します。

2FA APIの詳細については、以下のドキュメントをご参照ください。

2FA API - 以下で説明する手順では省略されている追加のAPIコールに関する手順の説明も含むAPIドキュメントの完全版です。
SDKとツール - 2FA（二要素認証） APIを含む NTT CPaaS の API の SDK および Postman コレクション。

APIのワークフロー

次の図は、2FA APIで実施するOTP検証プロセスのワークフローを示しています。

SMS APIの2FA

以下に、SMS経由でOTPを送信するプロセスの概要を示します。全体的なワークフローは、メールやVoiceチャネルの場合と同じで、その他にチャネル固有の追加要素がある場合は、その詳細がアプリケーションまたはテンプレートの構成に組み込まれています。

アプリケーションの構成 [#application-configuration-2FA-over-SMS-API]

アプリケーションは、2FAトラフィックの送信方法を構成する一連のパラメーターを表します。サービスごとに別々のアプリケーションを使用できます。さらに、同じサービスに対して個別のアプリケーションを定義して、固有の構成を必要とする様々なユースケースに対応できます。

例えば、1つのアプリケーションをユーザー登録時の2FAに使用し、別のアプリケーションをパスワード変更時の2FAに使用できます。これらのケースを異なるアプリケーションに分けることで、ユースケースごとに異なるオプションと動作を選択できます。

リクエスト本文の例：

json

2 {

3 "name":"User registration",

4 "configuration": {

5 "pinAttempts": 5,

6 "allowMultiplePinVerifications": true,

7 "pinTimeToLive": "5m",

8 "verifyPinLimit": "1/3s",

9 "sendPinPerApplicationLimit": "10000/1d",

10 "sendPinPerPhoneNumberLimit": "5/1d"

11 },

12 "enabled": true

13 }

アプリケーションを作成すると、その応答に、後でPINを送信する時に使用するアプリケーションID (applicationId) が付与されます。NTT CPaaS システムは、このアプリケーション ID (applicationId) を参照して、その特定のユースケースで許可される動作を認識します。

アプリケーションの管理に関する詳細については、2FA APIについて詳述しているドキュメントをご参照ください。

メッセージテンプレート [#message-templates-2FA-over-SMS-API]

テンプレートは、エンドユーザーに送信されるPINプレースホルダー付きのメッセージ本文を記述します。PINプレースホルダー \{\{pin\}\}は、メッセージのテキスト内にある必要があります。PIN の表示方法を変えたり、一部のチャネルや送信者固有のパラメーターを加えたりする構成変更も可能です。

1つのアプリケーション内に複数のメッセージテンプレートを作成できるため、異なる言語のサポートなど、様々なシナリオで同じアプリケーションを使用できます。

リクエスト本文の例：

json

2 {

3 "pinType": "NUMERIC",

4 "messageText": "Your pin is {{pin}}",

5 "pinLength": 4,

6 "senderId": "NTT CPaaS 2FA"

7 }

メッセージテンプレートを作成すると、後でPINを送信する時に使用するメッセージテンプレートID (messageId) が付与されます。

NTT CPaaSシステムは、参照したメッセージテンプレートID (messageId) に基づいてPINを生成し、そのPINをメッセージテンプレートに加えた後、 PINを含むメッセージをエンドユーザーに送信します。

2FA機能を有効にしたメッセージテンプレートの取得、作成や更新方法に関する詳細については、メッセージテンプレートの管理について詳述しているAPIドキュメントをご参照ください。

OTPメッセージの送信 [#sending-otp-messages-2FA-over-SMS-API]

アプリケーションとメッセージテンプレートの構成が完了したら、OTPの生成と対象となる受信者への送信を開始できるようになります。その際、前述した手順でアプリケーションIDとメッセージテンプレートIDを取得し、各IDがリクエストの本文に含まれていることを確認しておくようにします。

リクエスト本文の例：

json

2 {

3 "applicationId": "HJ675435E3A6EA43432G5F37A635KJ8B",

4 "messageId": "0130269F44AFD07AEBC2FEFEB30398A0",

5 "from": "NTT CPaaS 2FA",

6 "to": "41793026727"

7 }

メッセージが送信されると、PIN ID (pinId) が応答に含まれます。PIN 確認のために PIN ID を必ず保持してください。

PINをSMS、Voice、またはメールで送信する方法の詳細については、2FA APIについて詳述しているドキュメントをご参照ください。

OTPの検証 [#verifying-otps-2FA-over-SMS-API]

OTPを検証するには、PIN IDをクエリパラメーターとして指定し、ユーザーが提供したPINをリクエストの本文に加える必要があります。

このデータは、NTT CPaaSによって生成されたPINとユーザーが入力したPINの照合、OTPの確認ならびにユーザーの電話番号の検証に使用されます。

リクエスト本文の例：

json

2 {

3 "pin": "1598"

4 }

最終応答には、ユーザーの検証結果に関する情報が含まれます。

OTPの検証に関する詳細については、2FA APIについて詳述しているドキュメントをご参照ください。