# 步驟 3：分發參與者權杖
現在您有了一個舞台，需要建立權杖，並將其分發給參與者，使參與者能夠加入此舞台，並開始傳送和接收影片。有兩種權杖產生方法：
+ 使用金鑰對[建立](#getting-started-distribute-tokens-self-signed)權杖。
+ [使用 IVS 即時串流 API 建立權杖](#getting-started-distribute-tokens-api)。
這兩種方法皆在下面有所描述。
## 使用金鑰對建立權杖
您可以在伺服器應用程式建立權杖，然後將權杖分發給參與者，用以加入舞台。您需要產生 ECDSA 公有/私有金鑰對來簽署 JWT，並且將公有金鑰匯入至 IVS。然後，IVS 就可以在有人加入舞台時驗證權杖。
IVS 不會自動刪除到期的金鑰。如果私有金鑰遭到盜用，您必須刪除舊的公有金鑰。
### 建立新的金鑰對
有多種方法可以建立金鑰對。以下提供兩個範例。
若要在主控台中建立新的金鑰對，請依照下列步驟執行：
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. 依照提示進行操作並選擇 **Import** (匯入)。
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 都有三個欄位：標頭、承載和簽章。
JWT 標頭和承載的 JSON 結構描述如下所述。您也可以從 IVS 主控台複製範例 JSON。若要從 IVS 主控台取得標頭和承載 JSON：
1. [開啟 Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。如果您尚未在舞台中，請選擇舞台區域。
1. 在左側導覽功能表中，選擇**即時串流 > 舞台**。
1. 選取您要使用的舞台。請選取**檢視詳細資訊**。
1. 在**參與者權杖**區段中，選取**建立權杖**旁的下拉式清單。
1. 選取**建置權杖標頭和承載**。
1. 填寫表單並複製彈出視窗底部顯示的 JWT 標頭和承載。
#### 權杖結構描述：標頭
標頭指定：
+ `alg` 是簽章演算法。這是 ES384，一種使用 SHA-384 雜湊演算法的 ECDSA 簽章演算法。
+ `typ` 是符記類型，JWT。
+ `kid` 是用來簽署權杖的公有金鑰 ARN。此 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 時間戳記。(請參閱 `exp` 有關 Unix 時間戳記的備註。) 此值必須為整數類型。
+ `jti` (JWT ID) 是參與者 ID，此 ID 會用於追蹤和指代獲得權杖的參與者。每個權杖都必須具有唯一的參與者 ID。此 ID 必須是區分大小寫的字串、長度上限為 64 個字元，且只包含英數字元、連字號 (-) 和底線 (\$1) 字元。不允許使用其他特殊字元。
+ `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 即時串流 API 建立權杖
![\[分發參與者權杖：階段權杖工作流程\]](http://docs.aws.amazon.com/zh_tw/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 命令列介面使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)》。請注意，使用 AWS CLI 產生符記適合在測試時使用，但對於生產用途，建議您使用 AWS SDK 在伺服器端產生符記 (請參閱下述說明)。
1. 執行 `create-participant-token` 命令與階段 ARN。納入任何或所有這些功能：`"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 套件。如需詳細資訊，請參閱[適用於 JavaScript 的 AWS SDK 入門](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);
```