はじめに

この資料は公式ドキュメントを解説したものです。
(最終更新：2020/06)
https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms

用語説明

Token：メディア系 (Voice/Video) SDK用の Security Key (Dynamic Key) [new]
Channel Key：メディア系SDK用の Security Key [old]
RTM Token：RTM SDK用の Security Key

SDK	Token サポートバージョン	Channel Key サポートバージョン	SDK バージョン確認方法
Native SDK	2.1.0 以降	2.1.0 より前	getSdkVersion
Web SDK	2.4.0 以降	2.4.0 より前	AgoraRTC.VERSION
Gaming SDK	2.2.0 以降	2.2.0 より前	getSdkVersion

概要

Agora SDKではチャネル接続時にセキュリティ要件に応じて2種類の接続方法があります。
1. 低いセキュリティでの接続(テスト用アプリ等)
2. 高いセキュリティでの接続(製品用アプリ等)

(低いセキュリティの場合、App ID 漏洩した場合、不正に利用される可能性があります。)

認証設定手順

App ID のみを認証に利用する際の手順と Token を認証に利用する際の手順を説明します。

Channel Key の設定手順は、Channel Keys をご確認下さい。
RTM Token の設定手順は、Use Security Keys をご確認下さい。

App ID のみを認証に利用する場合

Agora Console で作成するプロジェクトごとに App ID が発行されます。

App ID の取得

https://sso.agora.io/signup?source_id=3 から Agora Console の開発者アカウント登録をします。
画面左側のナビゲーションメニューのを選択して Project Management ページを開きます。
Create を選択します。
プロジェクト名を入力し、認証方法は APP ID を選択して下さい。
Submit を選択すると App ID が発行されます。

App ID の適用

client 初期化時にアプリケーション認証のため、appId 変数に発行した App ID を appId 変数にセットして下さい。
※チャネル入室時の token 変数には、NULL をセットして下さい。

Token を認証に利用する場合

Token は App ID よりもより安全で複雑な認証方法です。Token を生成するためには、App ID と App Certificate が必要となります。
(App Certificate は、App ID と組み合わせて Token を生成するために利用されるため、単体で利用されることはありません。)

App Certificate の有効化

プロジェクト作成時に APP ID + APP certificate + Token (recommended) を選択すると、App Certificate はデフォルトで有効になります。

プロジェクト作成時に App ID を選択し、その後、"App ID + App Certificate + Token" に変更したい場合、App Certificate を有効にする必要があります。
App Certificate は以下の手順で有効にします。

対象プロジェクトで edit ボタンを選択します。
"Basic Info" ページで Enable を選択します。
About App Certificate を読み、Dynamic Key Server is ready, I'm going to enable app certificate を選択します。
メールが送信されるので、メールに記載の手順に従って、App Certificate を有効にします。
Edit project ページに戻り、App Certificate が有効になっていることを確認します。

Temporary Token の取得

アプリケーションのテスト版を開発する際、チャネル入室をするために Agora Console で Temporary Token を生成することができます。

Project Management ページでを選択します。
Token ページで、チャネル名を入力すると Temporary Token を取得できます。

Temporary Token はセキュリティ要件が低い場合に適用します。製品環境では、ご自身のサーバで Token を生成することを推奨します。
Temporary Token は RTM SDK には適用できません。

Token の取得

製品版のアプリケーションを開発した際は、ご自身のサーバで Token を生成して下さい。Token 生成方法については、Generate a Token on Your Server をご確認下さい。
GitHubにもサンプルコードが公開されています.

Token の適用

チャネル入室のために join メソッドをコールする際、Token を渡します。

チャネル入室に利用する channel ID (Channel Name) とユーザ名が Token 生成時に利用した channel ID とユーザ名と同じである必要があります。

Token のライフサイクル

メディア系 SDK と RTM SDK の Token のライフライクルについて説明します。

メディア系 SDK の Token ライフサイクル

Token 生成後、クライアントは24時間以内に Token を利用して、チャネルに入室する必要があります。
Token は生成時に [privilegeExpiredTs]で設定した時刻に失効します。
- 失効するとユーザはチャネル内から退出させられます。
- privilegeExpiredTs を 0 に設定した場合、有効期限はなくなります。
SDK は Token が失効したことをコールバックにより取得できます。その際、 renewToken というメソッドを利用して新しい Token を生成することができます。

例. Web SDK の場合

client.on("onTokenPrivilegeWillExpire", function(){
  //After requesting a new token
  client.renewToken(token);
});

RTM SDK の Token ライフサイクル

Token 生成後、クライアントは24時間以内に Token を利用して、チャネルに入室する必要があります。
RTM SDK の Token でも有効期限の変数 (expireTimeStamp) は存在しますが、2020年6月現在開発中で、まだ利用することができません。
- 失効してもチャネル内のユーザは強制退室させられません。 (失効後の再入室はできません。)
SDK は Token が失効したことをコールバックにより取得できます。その際、renewToken というメソッドを利用して新しい Token を生成することができます。

最後に

agora.ioに関するお問い合わせはこちらから

agora.io の Security Key について