# 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입니다. [ 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가 있어야 합니다. 영숫자, 하이픈(-) 및 밑줄(\$1) 문자만 포함하여 최대 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`은 스테이지 ARN에서 추출할 수 있는 스테이지의 ID입니다. 예를 들어, 스테이지 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 인코딩 텍스트가 포함될 수 있습니다. 이 필드의 최대 길이는 총 1KB입니다. **이 필드는 모든 스테이지 참가자에게 노출되며 개인 식별 정보, 기밀 정보 또는 민감한 정보에 사용해서는 안 됩니다.
+ `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/ko_kr/ivs/latest/RealTimeUserGuide/images/Distribute_Participant_Tokens.png)
위에 표시된 것처럼 클라이언트 애플리케이션은 서버 애플리케이션에 토큰을 요청하고 서버 애플리케이션은 AWS SDK 또는 SigV4 서명 요청을 사용하여 CreateParticipantToken을 직접적으로 호출합니다. AWS 자격 증명은 API를 직접적으로 호출하는 데 사용되므로 토큰은 클라이언트 측 애플리케이션이 아닌 안전한 서버 측 애플리케이션에서 생성되어야 합니다.
참가자 토큰을 생성 시 선택 사항으로 속성 및/또는 기능을 지정할 수 있습니다.
+ 애플리케이션에서 제공되는 속성을 지정하여 토큰에 인코딩하고 스테이지에 연결할 수 있습니다. 맵 키와 값에는 UTF-8 인코딩 텍스트가 포함될 수 있습니다. 이 필드의 최대 길이는 총 1KB입니다. **이 필드는 모든 스테이지 참가자에게 노출되며 개인 식별 정보, 기밀 정보 또는 민감한 정보에 사용해서는 안 됩니다.
+ 토큰을 통해 활성화되는 기능을 지정할 수 있습니다. 기본값은 참가자가 오디오와 비디오를 전송하고 수신을 수 있도록 하는 `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. 스테이지 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 패키지를 설치해야 합니다. 자세한 내용은 [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);
```