# ステップ 3: 参加者トークンを配布する ステージができたら、トークンを作成して参加者に配布し、参加者がステージに参加してビデオの送受信を開始できるようにする必要があります。トークンを生成するには、次の 2 つの方法があります。 + キーペアを使用してトークンを[作成](#getting-started-distribute-tokens-self-signed)します。 + [IVS リアルタイムストリーミング API を使用してトークンを作成します](#getting-started-distribute-tokens-api)。 両方のアプローチを以下にて説明します。 ## キーペアを使用したトークンの作成 サーバーアプリケーションでトークンを作成し、参加者に配布してステージに参加できます。ECDSA パブリック/プライベートキーペアを生成して JWT に署名し、パブリックキーを IVS にインポートします。その後、IVS はステージ結合時にトークンを検証できます。 IVS にはキーの有効期限はありません。プライベートキーが侵害された場合は、古いパブリックキーを削除する必要があります。 ### 新しいキーペアの作成 キーペアを作成するには、複数の方法があります。以下に 2 つの例を示します。 コンソールを使用して新しいキーペアを作成するには、次の手順に従います。 1. [Amazon IVS コンソール](https://console.aws.amazon.com/ivs)を開きます。ステージのリージョンを選択していない場合は、リージョンを選択します。 1. 左側のナビゲーションメニューで、**[リアルタイムストリーミング] > [パブリックキー]**を選択します。 1. **[パブリックキーを作成]** を選択します。**[パブリックキーの作成]** ダイアログが表示されます。 1. プロンプトに従って、[**Create (作成)**] を選択します。 1. Amazon IVS が新しいキーペアを生成します。パブリックキーはパブリックキーリソースとしてインポートされ、プライベートキーはすぐにダウンロードできるようになります。パブリックキーは、必要に応じて後でダウンロードすることもできます。 Amazon IVS はクライアント側でキーを生成し、プライベートキーを保存しません。***キーは必ず保存してください。後で取得することはできません。*** OpenSSL で P384 EC キーペアを作成するには (最初に [OpenSSL](https://www.openssl.org/source/) のインストールが必要な場合があります)、次の手順を行います。このプロセスにより、プライベートキーとパブリックキーの両方にアクセスできます。パブリックキーは、トークンの検証をテストする場合にのみ必要です。 ``` openssl ecparam -name secp384r1 -genkey -noout -out priv.pem openssl ec -in priv.pem -pubout -out public.pem ``` 次に、以下の手順に従い、新しいパブリックキーをインポートします。 ### パブリックキーをインポートするには キーペアが作成できたら、パブリックキーを IVS にインポートできます。プライベートキーはシステムでは必要ありませんが、ユーザーがトークンを署名するのに使用されます。 コンソールで既存のパブリックキーをインポートするには 1. [Amazon IVS コンソール](https://console.aws.amazon.com/ivs)を開きます。ステージのリージョンを選択していない場合は、リージョンを選択します。 1. 左側のナビゲーションメニューで、**[リアルタイムストリーミング] > [パブリックキー]**を選択します。 1. [**インポート**] を選択します。**[パブリックキーのインポート]** ダイアログが表示されます。 1. プロンプトに従って、**[インポート]** を選択します。 1. Amazon IVS はパブリックキーをインポートし、パブリックキーリソースを生成します。 CLI で既存のパブリックキーをインポートするには、次のコマンドを実行します。 ``` aws ivs-realtime import-public-key --public-key-material "`cat public.pem`" --region ``` リージョンがローカルの AWS 設定ファイルにある場合、`--region ` を省略できます。 レスポンスの例を次に示します。 ``` { "publicKey": { "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/f99cde61-c2b0-4df3-8941-ca7d38acca1a", "fingerprint": "98:0d:1a:a0:19:96:1e:ea:0a:0a:2c:9a:42:19:2b:e7", "publicKeyMaterial": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEVjYMV+P4ML6xemanCrtse/FDwsNnpYmS\nS6vRV9Wx37mjwi02hObKuCJqpj7x0lpz0bHm5v1JBvdZYAd/r2LR5aChK+/GM2Wj\nl8MG9NJIVFaw1u3bvjEjzTASSfS1BDX1\n-----END PUBLIC KEY-----\n", "tags": {} } } ``` ### API リクエスト ``` POST /ImportPublicKey HTTP/1.1 { "publicKeyMaterial": "" } ``` ### トークンを生成して署名する JWT およびトークン署名用にサポートされているライブラリの操作の詳細については、[jwt.io](https://jwt.io/) を参照してください。jwt.io インターフェイスでは、プライベートキーを入力してトークンに署名する必要があります。パブリックキーは、トークンを検証する場合にのみ必要です。 すべての JWT には、ヘッダー、ペイロード、署名の 3 つのフィールドがあります。 JWT のヘッダーとペイロードの JSON スキーマを以下に示します。または、IVS コンソールからサンプル JSON をコピーすることもできます。IVS コンソールからヘッダーとペイロード JSON を取得するには 1. [Amazon IVS コンソール](https://console.aws.amazon.com/ivs)を開きます。ステージのリージョンを選択していない場合は、リージョンを選択します。 1. 左側のナビゲーションメニューで、**[リアルタイムストリーミング] > [ステージ]**を選択します。 1. 使用するステージを選択します。**[詳細を表示]** 選択します。 1. **[参加者トークン]** セクションで、**[トークンの作成]** の横にあるドロップダウンを選択します。 1. **[トークンヘッダーとペイロードをビルドする]**を選択します。 1. フォームに入力し、ポップアップの下部に表示される JWT ヘッダーとペイロードをコピーします。 #### トークンスキーマ: ヘッダー ヘッダーは以下を指定します。 + `alg` は署名アルゴリズムです。これは、SHA-384 ハッシュアルゴリズムを使用する ECDSA 署名アルゴリズムの ES384 です。 + `typ` はトークン型、JWT です。 + `kid` は、トークンの署名に使用されるパブリックキーの ARN です。[GetPublicKey](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_GetPublicKey.html) API リクエストから返されるのと同じ ARN である必要があります。 ``` { "alg": "ES384", "typ": "JWT" “kid”: “arn:aws:ivs:123456789012:us-east-1:public-key/abcdefg12345” } ``` #### トークンスキーマ: ペイロード ペイロードには、IVS 固有のデータが含まれています。`user_id` を除くすべてのフィールドは必須です。 + JWT 仕様の `RegisteredClaims` は、ステージトークンを有効にするために提供する必要がある予約クレームです。 + `exp` (有効期限) は、トークンの有効期限を示す Unix UTC タイムスタンプです。(Unix タイムスタンプは、うるう秒を無視した、1970-01-01T00:00:00Z UTC から、指定された UTC 日付/時刻までの秒数を表す数値です。) トークンは、参加者がステージに参加するときに検証されます。IVS は、デフォルト (かつ推奨値) の 12 時間 TTL を持つトークンを提供します。これは、公開時点 (iat) から最大 14 日間まで延長できます。整数型の値である必要があります。 + `iat` (発行時) は、JWT が発行されたときの Unix UTC タイムスタンプです。(Unix タイムスタンプについては、`exp` のメモを参照してください。) 整数型の値である必要があります。 + `jti` (JWT ID) は、トークンが付与される参加者を追跡および参照するために使用される参加者 ID です。すべてのトークンには一意の参加者 ID が必要です。英数字、ハイフン (-)、アンダースコア (\_) 文字のみを含む、最大 64 文字の大文字と小文字を区別する文字列である必要があります。他の特殊文字は使用できません。 + `user_id` は、トークンを識別するのに役立つ、顧客に割り当てられたオプションの名前です。これは、参加者を顧客自身のシステム内のユーザーにリンクするために使用できます。これは、[CreateParticipantToken](https://docs.aws.amazon.com/ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html) API リクエストの `userId` フィールドと一致する必要があります。任意の UTF-8 エンコードテキストにすることができ、最大 128 文字の文字列です。*このフィールドはすべてのステージ参加者に公開されます。これらを個人を特定する情報、機密情報や機微な情報には使用しないでください。* + `resource` はステージの ARN です。例: `arn:aws:ivs:us-east-1:123456789012:stage/oRmLNwuCeMlQ`。 + `topic` はステージの ID で、ステージ ARN から抽出できます。例えば、ステージ ARN が `arn:aws:ivs:us-east-1:123456789012:stage/oRmLNwuCeMlQ` の場合、ステージ ID は `oRmLNwuCeMlQ` です。 + `events_url` は、CreateStage または GetStage オペレーションから返されるイベントエンドポイントである必要があります。この値はステージ作成時にキャッシュすることをお勧めします。この値は最大 14 日間キャッシュできます。値の例は `wss://global.events.live-video.net` です。 + `whip_url` は、CreateStage または GetStage オペレーションから返される WHIP エンドポイントである必要があります。この値はステージ作成時にキャッシュすることをお勧めします。この値は最大 14 日間キャッシュできます。値の例は `https://453fdfd2ad24df.global-bm.whip.live-video.net` です。 + `capabilities` はトークンの機能を指定します。有効な値は `allow_publish` および `allow_subscribe` です。サブスクライブ専用トークンの場合は、`allow_subscribe` を `true` に設定するだけにします。 + `attributes` は、トークンにエンコードしてステージにアタッチするアプリケーション提供の属性を指定できるオプションのフィールドです。マップキーと値には、UTF-8 エンコードされたテキストを含めることができます。このフィールドの最大長は合計 1 KB です。*このフィールドはすべてのステージ参加者に公開されます。これらを個人を特定する情報、機密情報や機微な情報には使用しないでください。* + `version` は `1.0` である必要があります。 ``` { "exp": 1697322063, "iat": 1697149263, "jti": "Mx6clRRHODPy", "user_id": "", "resource": "", "topic": "", "events_url": "wss://global.events.live-video.net", "whip_url": "https://114ddfabadaf.global-bm.whip.live-video.net", "capabilities": { "allow_publish": true, "allow_subscribe": true }, "attributes": { "optional_field_1": "abcd1234", "optional_field_2": "false" }, "version": "1.0" } ``` #### トークンスキーマ: 署名 署名を作成するには、ヘッダー (ES384) で指定されたアルゴリズムを使用して、エンコードされたヘッダーとエンコードされたペイロードに署名します。 ``` ECDSASHA384( base64UrlEncode(header) + "." + base64UrlEncode(payload), ) ``` #### 指示 1. ES384 署名アルゴリズムと IVS に提供されるパブリックキーに関連付けられたプライベートキーを使用してトークンの署名を生成します。 1. トークンを組み立てます。 ``` base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + base64UrlEncode(signature) ``` ## IVS Real-Time Streaming API を使用したトークンの作成 ![参加者トークンの配布:ステージトークンのワークフロー](http://docs.aws.amazon.com/ja_jp/ivs/latest/RealTimeUserGuide/images/Distribute_Participant_Tokens.png) 上記のように、クライアントアプリケーションからサーバー側のアプリケーションにトークンを要求し、サーバー側のアプリケーションは AWS SDK または SigV4 署名付きリクエストを使用して CreateParticipantToken を呼び出します。AWS 認証情報が API の呼び出しに使用されるため、トークンはクライアント側のアプリケーションではなく、安全なサーバー側のアプリケーションで生成する必要があります。 参加者トークンを作成するときは、オプションで属性や機能を指定できます。 + アプリケーションが提供する属性を指定してトークンにエンコードし、ステージにアタッチできます。マップキーと値には、UTF-8 エンコードされたテキストを含めることができます。このフィールドの最大長は合計 1 KB です。*このフィールドはすべてのステージ参加者に公開されます。これらを個人を特定する情報、機密情報や機微な情報には使用しないでください。* + トークンで有効になっている機能を指定できます。デフォルトは `PUBLISH` および `SUBSCRIBE` であり、これにより参加者はオーディオとビデオを送受信できるようになりますが、機能のサブセットを持つトークンを発行することもできます。たとえば、モデレーター向けに `SUBSCRIBE` 機能のみを備えたトークンを発行することができます。その場合、モデレーターはビデオを送信している参加者を見ることができますが、自分のビデオを送信することはできません。 詳細については、「[CreateParticipantToken](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html)」を参照してください。 テストや開発用に、コンソールまたは CLI を使用して参加者トークンを作成できますが、ほとんどの場合には、実稼働環境の AWS SDK を使用して作成することをお勧めします。 サーバーから各クライアントにトークンを配布する方法が必要になります (API リクエスト経由など)。この機能は提供していません。このガイドでは、以下の手順でトークンをコピーしてクライアントコードに貼り付けるだけです。 **重要**: トークンは不透明なものとして扱ってください。つまり、トークンの内容に基づいて機能を構築しないでください。トークンの形式は将来変更される可能性があります。 ### コンソールでの手順 1. 前のステップで作成したステージに移動します。 1. **[トークンの作成]** を選択します。**トークンの作成**ウィンドウが表示されます。 1. トークンに関連付けるユーザー ID を入力します。任意の UTF-8 でエンコードされたテキストを使用できます。 1. **[作成]** を選択します。 1. トークンをコピーします。*重要:トークンは必ず保存してください。IVS にトークンは保存されないため、後で取得することはできません*。 ### CLI の手順 AWS CLI を使用してトークンを作成するには、最初に CLI をダウンロードし、コンピューターに設定する必要があります。詳細については、「[AWS Command Line Interface のユーザーガイド](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」を参照してください。AWS CLI を使用してトークンを生成するのはテスト目的には適していますが、本番環境で使用する場合は、AWS SDK を使用してサーバー側でトークンを生成することをお勧めします (下記の手順を参照)。 1. ステージ ARN で `create-participant-token` コマンドを実行します。以下の機能のいずれか、またはすべてを含めます: `"PUBLISH"`、`"SUBSCRIBE"`。 ``` aws ivs-realtime create-participant-token --stage-arn arn:aws:ivs:us-west-2:376666121854:stage/VSWjvX5XOkU3 --capabilities '["PUBLISH", "SUBSCRIBE"]' ``` 1. これにより、参加者トークンが返されます。 ``` { "participantToken": { "capabilities": [ "PUBLISH", "SUBSCRIBE" ], "expirationTime": "2023-06-03T07:04:31+00:00", "participantId": "tU06DT5jCJeb", "token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NjE1NDE0MjAsImp0aSI6ImpGcFdtdmVFTm9sUyIsInJlc291cmNlIjoiYXJuOmF3czppdnM6dXMtd2VzdC0yOjM3NjY2NjEyMTg1NDpzdGFnZS9NbzhPUWJ0RGpSIiwiZXZlbnRzX3VybCI6IndzczovL3VzLXdlc3QtMi5ldmVudHMubGl2ZS12aWRlby5uZXQiLCJ3aGlwX3VybCI6Imh0dHBzOi8vNjZmNzY1YWM4Mzc3Lmdsb2JhbC53aGlwLmxpdmUtdmlkZW8ubmV0IiwiY2FwYWJpbGl0aWVzIjp7ImFsbG93X3B1Ymxpc2giOnRydWUsImFsbG93X3N1YnNjcmliZSI6dHJ1ZX19.MGQCMGm9affqE3B2MAb_DSpEm0XEv25hfNNhYn5Um4U37FTpmdc3QzQKTKGF90swHqVrDgIwcHHHIDY3c9eanHyQmcKskR1hobD0Q9QK_GQETMQS54S-TaKjllW9Qac6c5xBrdAk" } } ``` 1. このトークンを保存します。ステージに参加してビデオを送受信する際に必要となります。 ### AWS SDK での手順 AWS SDK を使用してトークンを作成することができます。以下は、JavaScript を使用する AWS SDK の手順です。 **重要:** このコードは、サーバー側で実行し、その出力をクライアントに渡す必要があります。 **前提条件:** 以下のコードサンプルを使用するには、aws-sdk/client-ivs-realtime パッケージをインストールする必要があります。詳細については、「[AWS SDK for JavaScript の開始](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html)」を参照してください。 ``` import { IVSRealTimeClient, CreateParticipantTokenCommand } from "@aws-sdk/client-ivs-realtime"; const ivsRealtimeClient = new IVSRealTimeClient({ region: 'us-west-2' }); const stageArn = 'arn:aws:ivs:us-west-2:123456789012:stage/L210UYabcdef'; const createStageTokenRequest = new CreateParticipantTokenCommand({ stageArn, }); const response = await ivsRealtimeClient.send(createStageTokenRequest); console.log('token', response.participantToken.token); ```