RTC 参加トークン
参加者がルームに参加するには、短期間有効な認証情報が必要です。バックエンドでは、 以下の2つの方法で取得できます:
| 方法 | 方法 | 以下の場合に使用してください |
|---|---|---|
| サーバー発行 | バックエンドは POST /v1/rooms/{roomId}/tokens キーAPIを使用して | デフォルト。参加ごとに1回の呼び出しAPI。 |
| オフライン発行 | バックエンドは、 参加トークン RTCを呼び出さずに、プロジェクト署名キーを使用してトークンに署名します。このトークンは POST /v1/join | 参加数が非常に多い場合、またはバックエンドが参加のたびに RTC を呼び出してはならない場合 |
どちらの場合も、同じ認証情報を提供し、同じルームの状態、収容人数、およびプランの チェックが適用されます。どちらの場合も どのルームに誰が参加できるかは、バックエンドで決定されます;決して クライアントに、独自のルーム、ロール、または権限を選ばせてはいけません。
サーバー発行の認証情報
Section titled “サーバー発行の認証情報”curl --fail-with-body \ --request POST "https://api.rtc.champrep.com/v1/rooms/$RTC_ROOM_ID/tokens" \ --header "Authorization: Bearer $RTC_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"canPublish":true}'このキーには、 tokens:write スコープ。応答には以下が含まれます token,
participantId, url, iceServers および expiresIn; 詳細は
API 参照 および
join フロー.
プロジェクトの署名キー
Section titled “プロジェクトの署名キー”署名キーは1つのプロジェクトに属します。その id は JWT です kid.
| アルゴリズム | RTCが保持するもの | 保管すべきもの |
|---|---|---|
HS256 (デフォルト) | 暗号化された共有シークレット | シークレット rtcsk_…、作成時に一度だけ表示されます |
ES256 | P-256 公開鍵 | 秘密鍵:RTC によって生成され、JWK として一度だけ表示されるもの、またはご自身で用意したもの(公開 JWK のみを送信してください) |
RTCコンソール、またはコンソールセッションを通じて、以下のコマンドを使用してキーを作成してくださいAPI:
| メソッドとパス | 結果 |
|---|---|
GET /v1/projects/{projectId}/signing-keys | キー: id, name, algorithm, prefix (HS256) または publicKeyJwk (ES256)、 createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201、鍵、および一度だけその secret (HS256) または privateKeyJwk (ES256、生成済み) |
DELETE /v1/projects/{projectId}/signing-keys/{keyId} | { "revoked": true };これを使用して署名されたトークンは、直ちに無効になります |
作成ボディは { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }.
expiresInDays は1から730までの値を指定できます。これを指定しない場合、キーの有効期限は設定されません。 1つのプロジェクトにつき、最大5つのアクティブなキーを 持つことができます(SIGNING_KEY_LIMIT)。シークレットや 秘密鍵は、サーバーのシークレットマネージャーにのみ保管してください。ブラウザ、モバイル アプリ、リポジトリ、チャットには絶対に保管しないでください。アシスタントCHAMPREP AIは署名用 キーの一覧を表示することはできますが、キーを作成したり、シークレットを表示したりすることは決してありません。
ローテーションを行うには、新しいキーを作成し、デプロイした後、古いキーを無効化してください。
Joinトークンの形式
Section titled “Joinトークンの形式”ジョイントークンとは、プロジェクトの署名キーで署名されたJWTのことです。
| パート | フィールド | ルール |
|---|---|---|
| ヘッダー | alg | HS256 または ES256、鍵のアルゴリズム |
| ヘッダー | kid | 署名キー id |
| クレーム | aud | 常に rtc-join |
| クレーム | roomId | キーのプロジェクト内のルーム |
| クレーム | iat, exp | 発行時刻と有効期限は秒単位で指定され、両者の差は最大1時間です。 |
| クレーム | jti | 一意の ID(8 ~ 128 文字)(A-Z a-z 0-9 . _ : -); 各トークンは使用可能です 一度 |
| クレーム(オプション) | sub または identity | 安定したユーザー ID(A-Z a-z 0-9 : _ -, 最大 128); 両方が設定されている場合は、一致している必要があります |
| クレーム(オプション) | name | 他の参加者に表示される表示名(最大80文字) |
| クレーム(オプション) | role | host, cohost, participant, panelist または attendee |
| クレーム(オプション) | permissions, canPublish | RESTトークンリクエストと同様に、参加者が公開できる内容 |
| クレーム(オプション) | metadata | 他の参加者に表示される、最大 1 KB までの独自の文字列 |
| クレーム(オプション) | ttlSeconds | エクスチェンジによって返されるメディア認証情報の有効期間:30~300 |
| クレーム(オプション) | transcribe | false: この参加者は決して 転記; それらのトラックは記録されますが、文字起こしではスキップされます |
トークンの有効期間は短く設定してください(参加には数分で十分です)。有効期限が切れた、 再利用された、または不正に署名されたトークンは、 401
JOIN_GRANT_INVALID または 409
JOIN_GRANT_USED.
Node.js (jose)
Section titled “Node.js (jose)”import { randomUUID } from 'node:crypto';import { SignJWT, importJWK } from 'jose';
// HS256: the key is the UTF-8 bytes of the whole rtcsk_ secret.const alg = 'HS256';const key = new TextEncoder().encode(process.env.RTC_SIGNING_SECRET);// ES256 instead:// const alg = 'ES256';// const key = await importJWK(JSON.parse(process.env.RTC_SIGNING_PRIVATE_JWK), 'ES256');
export async function mintJoinToken({ roomId, userId, displayName }) { return new SignJWT({ roomId, name: displayName, role: 'participant', canPublish: true }) .setProtectedHeader({ alg, kid: process.env.RTC_SIGNING_KEY_ID }) .setAudience('rtc-join') .setSubject(userId) .setIssuedAt() .setExpirationTime('5m') .setJti(randomUUID()) .sign(key);}Python (PyJWT)
Section titled “Python (PyJWT)”import jsonimport osimport timeimport uuid
import jwt # pip install "pyjwt[crypto]"
# HS256: the key is the whole rtcsk_ secret.KEY = os.environ["RTC_SIGNING_SECRET"]ALGORITHM = "HS256"# ES256 instead:# KEY = jwt.PyJWK(json.loads(os.environ["RTC_SIGNING_PRIVATE_JWK"])).key# ALGORITHM = "ES256"
def mint_join_token(room_id: str, user_id: str, display_name: str) -> str: now = int(time.time()) claims = { "aud": "rtc-join", "roomId": room_id, "sub": user_id, "name": display_name, "role": "participant", "canPublish": True, "iat": now, "exp": now + 300, "jti": str(uuid.uuid4()), } return jwt.encode(claims, KEY, algorithm=ALGORITHM, headers={"kid": os.environ["RTC_SIGNING_KEY_ID"]})
参加トークンの交換
Section titled “参加トークンの交換”POST /v1/join with { "token": "<join token>" } と同じボディを返します。
POST /v1/rooms/{roomId}/tokens。キーAPIは不要です。参加トークン自体が 認証となります。
curl --fail-with-body \ --request POST https://api.rtc.champrep.com/v1/join \ --header 'Content-Type: application/json' \ --data "{\"token\":\"$RTC_JOIN_TOKEN\"}"ご自身のサーバーから参加トークンを交換するか、またはそのサーバーを介して 交換を中継してください。RTC は CHAMPREP’s コンソールからのブラウザリクエストのみを受け入れるAPIため、
POST /v1/join お客様のドメインからブラウザによって送信されたリクエストは拒否されます。 交換された認証情報は、トークンが発行された対象ユーザーのみに、独自の 認証済み接続を介して送信し、トークンおよび認証情報は機密情報として扱ってください。 参加および再接続のたびに、新しい参加トークンを生成してください。