こんにちは。KDDI ウェブコミュニケーションズ（KWC）の小原です。
Vonage の Voice API や Messages API の認証には JWT（JSON Web Token：ジョット）が利用されます。
SDK を使用する場合、JWT は SDK 内部で自動生成するため特別な作業は不要です。しかし、curl など SDK を使用しない場合は、手動で JWT を生成する必要があります。本記事では、JWT の生成方法について解説します。
要約
- Vonage CLI は安定版（2024年12月現在は 1.x）を使用してください
- Vonage の SDK でも JWT が生成可能です
JWT とは
API 認証において、API Key と API Secret を使用する方法はシンプルですが、流出時には速やかな変更が必要です。一方、JWT は以下の特徴を持ち、より安全です：
- 有効期限が設定可能
- 改ざん検知機能を搭載
- ペイロードにユーザ名やアクセス権限リスト（ACL）などを付加可能
- ステートレスな仕組みのためセッション管理が不要
JWT はアプリケーション ID と秘密鍵で生成します。
Vonage CLI を使用した JWT 生成
Vonage CLI はコマンドラインで動作するツールで、JWT 生成が可能です。
利用には LTS（Long Term Support）バージョンの Node.js が必要です。
Vonage CLI のインストール
Vonage CLI はバージョンによって JWT 生成方法が異なります。Vonage 公式の各種ドキュメントは 1.x がベースのため、ここでは 1.x をインストールします。
$ npm install -g @vonage/cli
$ vonage --version
@vonage/cli/1.x.0 wsl-x64 node-v22.12.0
もし 1.x 以外の場合はバージョン指定して再インストールしてください。
Vonage CLI の最新バージョンは @vonage/cli の Versions でご確認ください。
npm install -g @vonage/cli@1.x.y
Vonage CLI 1.x の JWT 生成
Vonage のアプリケーション ID と秘密鍵の取得はこちらの記事をご参照ください。
vonage jwt --key_file=$VONAGE_PRIVATE_KEY --app_id=$VONAGE_APP_ID
JWT を利用した SMS 送信例は下記です。
export JWT=$(vonage jwt --key_file=$VONAGE_PRIVATE_KEY --app_id=$VONAGE_APP_ID)
export TO_NUMBER=8160XXXXYYYY
curl -X POST https://api.nexmo.com/v1/messages \
-H 'Authorization: Bearer '$JWT \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"message_type": "text",
"text": "テストです",
"to": "'$TO_NUMBER'",
"from": "KWCPLUS",
"channel": "sms"
}'
Vonage CLI 2.x の JWT 生成
2.x と 3.x の JWT 生成は参考のために掲載します。
vonage jwt --private-key=$VONAGE_PRIVATE_KEY --application-id=$VONAGE_APP_ID --api-key=$VONAGE_API_KEY
Vonage CLI 3.x の JWT 生成
vonage jwt create --private-key $VONAGE_PRIVATE_KEY --app-id $VONAGE_APP_ID
Vonage SDK を使用した JWT 生成
Vonage は主要言語の SDK を提供しています。SDK を使用すると、Vonage CLI を使用せずに JWT を生成できます。
サーバ環境により Node.js のインストールが難しかったり、Vonage CLI の JWT 生成方法の非互換が気になるのであれば SDK でも生成可能です。
ここでは Python と Node.js の例を紹介します。
Python SDK の JWT 生成
Vonage Python SDK をインストールします。
pip install vonage
サンプルコードを vonage-jwt.py として保存して実行します。
import os
from vonage_jwt import JwtClient
application_id = os.environ["VONAGE_APP_ID"]
private_key = os.environ["VONAGE_PRIVATE_KEY"]
jwt_client = JwtClient(application_id, private_key)
jwt = jwt_client.generate_application_jwt()
print(jwt.decode('utf-8'))
$ python vonage-jwt.py
eyJhbGciOiJSUzI...
参考資料
Node.js SDK の JWT 生成
Vonage Server SDK for Node.js をインストールします。
npm install @vonage/server-sdk
サンプルコードを vonage-jwt.js として保存して実行します。
const fs = require('node:fs');
const { tokenGenerate } = require('@vonage/jwt');
const applicationId = process.env.VONAGE_APP_ID;
const privateKey = fs.readFileSync(process.env.VONAGE_PRIVATE_KEY, 'utf8');
const jwt = tokenGenerate(applicationId, privateKey);
console.log(jwt);
$ node vonage-jwt.js
eyJhbGciOiJSUzI...
参考資料
その他の JWT 生成方法
オンライン
下記ページで JWT が生成可能です。一時的に JWT が必要な場合に便利です。
独自実装
JWT は RFC 7519 で定義されています。そのため Vonage CLI や SDK を利用しなくても生成可能です。
下記記事は JavaScript や Python での実装例です。
How to Generate a JSON Web Tokens (JWTs) for Network APIs Authentication
独自生成した JWT の内容確認は下記 jwt.io が便利です。
Nexmo CLI（廃止）
Vonage 社が Nexmo 社を買収したことから、Vonage CLI の前身として Nexmo CLI があり、一部ドキュメントに残っています。しかしサポートは終了しているため、Vonage CLI をご利用ください。
nexmo jwt:generate $VONAGE_PRIVATE_KEY application_id=$VONAGE_APP_ID
JWT 認証以外の Vonage API
一部の API は JWT ではなく API Key と API Secret を利用します。
主要な API は JWT になり、Accounts や Application といった管理系が API Key になります。
SMS API は API Key ですが、SMS 送信可能な JWT による Messages API を推奨します。
古い Verify V1 API と Number Insight V1 API は API Key ですが、新しい Verify V2 API と Number Insight V2 API は JWT に移行しました。
認証方式の一覧は Authentication をご参照ください。
おわりに
本記事では Vonage の API 認証に必要な JWT の概要と生成方法について解説しました。
JWT を活用することで、安全性の高い API 認証を実現し、Vonage の多様なサービスをより便利にお使いいただけます。
もしこの記事や Vonage API の利用についてご不明点があれば、ぜひお気軽にお問い合わせください。
Discussion