認証

Verify API は 2 種類の認証をサポートしています:

ベーシック認証とJWTのどちらを使うべきか?

Verifyでは、ベーシック認証とJWTベアラー認証の2つの認証方法がサポートされています。円滑な移行を実現し、その機能を最大限に活用するためには、これら2つの違いを理解することが重要です。

どちらのオプションも使えるが、両方を同時に使うことはできない。一般的には JWTを使用することをお勧めします。 認証を使用します。Basic認証の方が使い始めは簡単ですが、この認証では サイレント認証 チャンネル

方法 サポート Vonageのアプリケーションが必要です。 コールバック/ウェブフック ACLサポート こんな方におすすめ
基本認証 クイックテスト/POC
JWTベアラ 製造

基本認証

基本認証では、APIキーとAPIシークレットを送信します。 Base64エンコード での Authorization ヘッダで確認できます。これらの認証情報は API設定 をクリックします。

これは、Verifyの利用を始める上で最も簡単な方法です。Vonage Applicationsの設定が不要であり、認証情報は Vonageダッシュボード.

仕組み

Authorization: Basic <base64(api_key:api_secret)>

警告APIキー/シークレットは機密です!もしあなたがそれらを公開(フロントエンドのコード、GitHubのリポジトリなど)すれば、誰でもあなたのアカウントを悪用することができます。

リクエストヘッダーの作成

  • まず、API KeyとSecretを連結する: API_KEY:API_SECRET.
  • それからだ、 Base64エンコード その結果もっと詳しく これ.
  • 最後に、リクエストに Authorization: Basic BASE64_ENCODED_STRING.

これはアプリケーション・コードの中で、例えばJavaScriptの中で行うことができる:

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

リクエスト例

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

からBase64エンコードされた文字列を生成できます。 api_key:api_secret 標準的なBase64エンコーディングツールやライブラリを使用する。

制限事項

Basic Auth では、Verify リクエストの主要なフロー(送信、確認、キャンセル、次のワークフローの開始)を利用できますが、2つの重要な制限があります:

  • コールバック/ウェブフックはサポートされていません。 イベントまたはサマリーコールバックを受信するには、ステータスURLで設定されたVonage Applicationとともに、JWTベアラ認証が必要です。
  • ACL(アクセス制御リスト)のサポートはありません。 JWTトークンは、Basic Authでは不可能な、特定のAPIエンドポイントへのパーミッションのスコープを可能にします。

これらの制限を考慮すると、Basic認証は最初のテストやPOC統合に最適です。本番環境では、JWTベアラ認証を強く推奨します。

JWT

A JWT (JSON Web Token)は、オープンスタンダード(RFC 7519)を使用して、当事者間で情報をJSONオブジェクトとして安全に送信することができる。このオブジェクトはオプションで暗号化し、秘密鍵/公開鍵で署名することができます。

JWTベアラー認証では、Vonageアプリケーションの秘密鍵で署名されたJSON Web Tokenが使用されます。この方法により、イベントおよびサマリーのコールバック、Webhookの設定、ACLスコープのトークンなど、Verifyの全機能を利用できるようになります。

仕組み

Authorization: Bearer <JWT>

JWTはダッシュボードでVonageアプリケーションを作成する際に取得したアプリケーションIDと秘密鍵を使って生成されます。

JWTを生成するには application ID そして private keyこの2つは アプリケーション の設定を変更してください。 ダッシュボード.

警告すべてのJWTの生成はバックエンドで行うこと。トークンの有効期限を必要以上に長くしないでください。

新しいJWTを生成するにはいくつかの方法がある:

vonage auth set --app-id your_application_id --private-key /path/to/your/private.key vonage jwt create

ご注意ください:

  • Vonageのいずれかをご利用の場合 サーバーSDK すべてのSDKがJWTトークンの生成をサポートしているため、JWTを別途生成する必要はありません。

  • Vonage SDKsのような外部ツールやライブラリを使用してJWTを生成したくない場合は、独自のJWT生成を実装することができます。その場合 JWTの生成方法 ブログ記事には、外部依存なしにJWTを生成する方法を示すJavaScriptとPythonの例が含まれています。

トークンが生成されると、ユーザーはそのトークンを使って保護されたエンドポイントにアクセスできるようになります。これは通常、Bearerスキーマを使用したAuthorizationヘッダーを使用して行われます:

Authorization: Bearer <JWT>

Verifyの設定手順

  1. でVonageアプリケーションを作成します。 Vonageダッシュボード. 左側のパネルで、[ ] に移動します。 [ビルド] > [Applications].
  2. 公開鍵と秘密鍵のペアを生成し、秘密鍵をダウンロードして安全に保管する。
  3. Applicationsの「Verify」を有効にし、コールバックを受信するためのステータスURL(Webhookエンドポイント)を設定してください。
  4. アプリケーションIDと秘密鍵で署名されたJWTを生成します。その際 JWTジェネレーターその Vonage CLIまたは任意のVonage SDK。
  5. を使用して、すべてのAPIリクエストにJWTを含めます。 Authorization: Bearer ヘッダーを使用する。

リクエスト例

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

JWTトークンは、最大TTL(time-to-live)が 24時間.を避けるために、有効期限が切れる前にトークンをリフレッシュするようにしてください。 401 Unauthorized というエラーが出た。

JWTが解き放つもの

  • コールバックの概要 - すべての検証リクエストの最後に、完全なステータスレポートを受け取る。
  • イベント・コールバック - 例えば、Silent AuthやWhatsApp Interactiveチャネルの場合)。
  • ACLスコープ付きトークン - セキュリティを強化するために、トークンのパーミッションを特定のエンドポイントに制限する。
  • ウェブフックの設定 - コンフィグ verify_event_url そして verify_status_url Vonageアプリケーションによる。

Verify Legacy からの認証の移行

Verify Legacy から Verify へ移行する際の主な変更点の 1 つは、認証の処理方法の変更です。

Verify Legacy では、認証は以下を渡すことで処理されていました api_key そして api_secret クエリパラメータとして、またはリクエスト本文内に指定します。この方法はVerifyではサポートされていません。

レガシーの確認 Verify
api_key + api_secret クエリ・パラメータ/ボディ Authorization: Basic <base64(api_key:api_secret)> ヘッダー
申請不要 JWTに必要なVonageアプリケーション
ウェブフックのサポートなし JWTによるフル・コールバック・サポート

重要:必ず取り外してください。 api_key そして api_secret Verify への移行時には、リクエスト本文やクエリパラメータからこれらのフィールドを削除してください。Verify の API 呼び出しでは、これらのフィールドは受け入れられません。