agora.io の Security Key について

#はじめに
この資料は公式ドキュメントを解説したものです。
(最終更新：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. 高いセキュリティでの接続(製品用アプリ等)
<img width="388" alt="image.png" src="https://qiita-image-store.s3.amazonaws.com/0/300377/49f767b4-718d-36a7-0a91-f89f5519ace2.png">
(低いセキュリティの場合、App ID 漏洩した場合、不正に利用される可能性があります。)

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

- Channel Key の設定手順は、[Channel Keys](https://docs.agora.io/en/Agora%20Platform/channel_key?platform=All%20Platforms) をご確認下さい。
- RTM Token の設定手順は、[Use Security Keys](https://docs.agora.io/en/Real-time-Messaging/rtm_token?platform=All%20Platforms) をご確認下さい。

##App ID のみを認証に利用する場合
[Agora Console](https://docs.agora.io/en/Agora%20Platform/console_overview?platform=All%20Platforms) で作成するプロジェクトごとに App ID が発行されます。

###App ID の取得
1. [https://sso.agora.io/signup?source_id=3](https://sso.agora.io/signup?source_id=3) から Agora Console の開発者アカウント登録をします。
2. 画面左側のナビゲーションメニューの ![01.auth.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/f30012a6-8430-0c63-ebac-f3c3b5c9088d.png) を選択して **Project Management** ページを開きます。
3. **Create** を選択します。<img width="864" alt="02.auth.jfif" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/67d2a8b5-cd93-9559-534b-27a00918f1ed.jpeg">
4. プロジェクト名を入力し、認証方法は **APP ID** を選択して下さい。<img width="395" alt="auth03.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/69ab5ea6-631d-49dd-d7f6-6ec7cbff7a25.png">
5. **Submit** を選択すると **App ID** が発行されます。<img width="1010" alt="auth04.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/39481145-8c50-336d-2eb2-270caddf1966.png">

###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 はデフォルトで有効になります。
<img width="396" alt="auth05.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/9632343d-a58d-a65c-fdae-ac52e9fa1611.png">

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

1. 対象プロジェクトで **edit** ボタンを選択します。<img width="1005" alt="auth06.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/bf308221-790d-7208-eeeb-1974084d1d50.png">
2. "Basic Info" ページで **Enable** を選択します。<img width="504" alt="auth07.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/2c9d12c7-f6d1-1a44-4029-9f55a997026d.png">
3. **About App Certificate** を読み、**Dynamic Key Server is ready, I'm going to enable app certificate** を選択します。<img width="612" alt="auth08.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/fae7dde3-a4b5-309a-8599-fdd1ac677d13.png">
4. メールが送信されるので、メールに記載の手順に従って、App Certificate を有効にします。 
5. **Edit project** ページに戻り、App Certificate が有効になっていることを確認します。

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

1. **Project Management** ページで <img width="11" alt="auth11.jfif" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/35a6364a-b097-4055-1b07-2a208ec838a9.jpeg"> を選択します。<img width="1012" alt="auth09.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/ec2fdad9-7238-068b-6560-fc361d0de844.png">

2. **Token** ページで、チャネル名を入力すると Temporary Token を取得できます。<img width="786" alt="auth10.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/386074/0d25c697-d6b5-6aa7-2adf-eb082e0db5f4.png">

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

###Token の取得
製品版のアプリケーションを開発した際は、ご自身のサーバで Token を生成して下さい。Token 生成方法については、[Generate a Token on Your Server](https://docs.agora.io/en/Audio%20Broadcast/token_server_cpp) をご確認下さい。
GitHubにもサンプルコードが公開されています.
![auth11.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/7a0ad6d3-a90a-83b2-d376-27718962f2af.png)


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

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

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


###メディア系 SDK の Token ライフサイクル
![Token Expire_RTC_Ja_20200605.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/65b5243f-c5bb-8b0c-8f1f-2b9e33cca11b.jpeg)


- Token 生成後、クライアントは**24時間以内**に Token を利用して、チャネルに入室する必要があります。
- Token は生成時に [privilegeExpiredTs]で設定した時刻に失効します。
    - **失効するとユーザはチャネル内から退出させられます。**
    - privilegeExpiredTs を 0 に設定した場合、有効期限はなくなります。

- SDK は Token が失効したことをコールバックにより取得できます。その際、 renewToken というメソッドを利用して新しい Token を生成することができます。

例. Web SDK の場合

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

###RTM SDK の Token ライフサイクル
![Token Expire_RTM_Ja_20200605.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/d145b9f8-9430-8c0b-f108-9d627824e59c.jpeg)

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

#最後に
[**agora.ioに関するお問い合わせはこちらから**](https://jp.vcube.com/lp/agora?utm_campaign=Agora&utm_source=Qiita&arc_id=c43dd8b0241f03fedc1d)
[<img width="912" alt="スクリーンショット 0001-08-15 13.41.56.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/5d815376-9b89-08fa-9434-6fa7e8e67bcf.png">](https://jp.vcube.com/lp/agora?utm_campaign=Agora&utm_source=Qiita&arc_id=c43dd8b0241f03fedc1d)