SkyWay Auth Tokenについて
❗ 本ページの情報はSkyWay Beta提供期間中に予告なく変更される可能性があります。
目次
概要
SkyWay Auth Tokenは、SkyWayを利用するために必要なJWT(JSON Web Token)形式のトークンです。
エンドユーザー毎に権限を細かく設定することでき、例えば Channel
ごとの入室を特定ユーザーに制限する、といったことができます。
SkyWay Auth Tokenを利用するためには、これを払い出すアプリケーションサーバーを構築する必要があります。SkyWay SDKを利用したクライアントアプリは、アプリケーションサーバからSkyWay Auth Tokenを取得し、これを用いて各種SkyWayの機能を利用します。
なお、サーバを構築せずにフロントエンドでSkyWay Auth Tokenを生成した場合、シークレットキーをエンドユーザーが取得できるため、誰でも任意の Channel
や Room
に入ることができる等のセキュリティ上の問題が発生します。
SkyWay Auth Tokenの構造
SkyWay Auth Tokenは前述の通りJWT形式を採用しており、ここではJWTにおけるヘッダー・ペイロード・署名について説明します。
ヘッダー
ヘッダーでは、署名生成に利用するアルゴリズムを記述します。
SkyWay Auth Tokenでは署名に HS256
のみを許可するため、下記の値となります。
{
"alg" : "HS256",
"typ" : "JWT"
}
ペイロード
SkyWay Auth Tokenのペイロードは、各種リソースが入れ子になった階層構造になっています。
ペイロードに記述されたリソース以外への操作はサーバ側で許可されないため、操作が必要なリソースはすべて記述する必要があります。
詳細なペイロードにおける各要素の説明は後述し、ここでは例を示します。
{
jti: "<任意のUUID>",
iat: 1645368600,
exp: 1645369200,
scope: {
app: {
id: "<アプリケーションID>",
turn: true,
actions: ["read"],
channels: [
{
id: "*",
name: "tutorial-room",
actions: ["write"],
members: [
{
id: "*",
name: "*",
actions: ["write"],
publication: {
actions: ["write"]
},
subscription: {
actions: ["write"]
}
}
],
sfuBots: [
{
actions: ["write"],
forwardings: [
{
actions: ["write"]
}
]
}
]
}
]
}
}
}
署名
シークレットキーを利用し、ヘッダとペイロードから HMAC-SHA256
を用いて生成した署名を利用します。
SkyWay Auth Tokenのペイロード詳細
ペイロードの各プロパティを順に説明します。(*: 必須マーク)
jti
*- トークンのユニーク性を担保するための一意な識別子 (
JWT ID
) - 形式はUUID v4
- 生成時に任意のUUIDを指定してください
- トークンのユニーク性を担保するための一意な識別子 (
iat
*- トークンが発行された日時 (
Issued At
) - 形式はUNIX時間(秒)
- トークンが発行された日時 (
exp
*- トークンの有効期限 (
Expiration Time
) - 形式はUNIX時間(秒)
- トークンが検証されるタイミングより
+30日未満
の値である必要があります
- トークンの有効期限 (
scope
*channel
やmember
などSkyWayの各種リソースに対する権限を指定するオブジェクト- 以下の通り階層化されている
app
channel
member
publication
subscription
以下より、 scope
内の各種リソースのパラメータについて説明します。
app
リソース
アプリケーションの設定を記載するオブジェクト。
id
*- アプリケーションIDを指定(SkyWayにログインして取得した値を記載します)。
turn
- TURNサーバの利用可否。形式は
boolean
。- trueにした場合はturnサーバを経由して通信することが可能となり、falseの場合は経由しません。
- TURNサーバの利用可否。形式は
actions
*- アプリケーション自体に関する権限。現在は'read'固定。(今後のSkyWayのアップデートにより、取りうる値が増える予定です。)
channels
*- channelリソースに関するオブジェクトを配列で指定
channel
リソース
当該アプリケーションにおける、channel
に対する権限を設定するオブジェクト。
Roomライブラリを利用する場合、内部的には channel
を利用するため、ここで Room
の id
または name
を指定します。
id
(id
またはname
のどちらかが必須 *)id
で対象のchannel
を指定'*'
を指定することで、すべてのchannel
を指定
name
(id
またはname
のどちらかが必須 *)name
で対象のchannel
を指定'*'
を指定することで、すべてのchannel
を指定
actions
*- 以下を複数指定可能
write
: プロパティ (id
,name
等)の閲覧、作成、削除、入室、metadata
の編集read
: プロパティの閲覧create
: 作成delete
: 削除updateMetadata
:metadata
の編集
- 以下を複数指定可能
members
*member
リソースに関するオブジェクトを配列で指定
sfuBots
*sfuBot
リソースに関するオブジェクトを配列で指定
member
リソース
当該 channel
における、 member
に対する権限を設定するオブジェクト。
当該 member
がWebRTCで他の member
と通信するためには signal
または write
権限が必要です。
id
(id
またはname
のどちらかが必須 *)id
で対象のmember
を指定'*'
を指定することで、すべてのmember
を指定
name
(id
またはname
のどちらかが必須 *)name
で対象のchannel
を指定'*'
を指定することで、すべてのmember
を指定
actions
*- 以下を複数指定可能
write
: 入室、退室、シグナリング情報のやり取り,metadata
の編集create
: 入室(入室時にmember
が作成される)delete
: 退室(入室時にmember
が削除される)signal
: シグナリング情報のやり取りupdateMetadata
:metadata
の編集
- 以下を複数指定可能
publication
publication
リソースに関するオブジェクトを指定
subscription
subscription
リソースに関するオブジェクトを指定
publication
リソース
当該 member
がもつ publication
に対する権限を設定するオブジェクト。
actions
*- 以下を複数指定可能
write
: publish、unpublishcreate
: publish(publish時にpublication
が作成される)delete
: unpublish(unpublish時にpublication
が削除される)
- 以下を複数指定可能
subscription
リソース
当該 member
がもつ subscription
に対する権限を設定するオブジェクト。
actions
*- 以下を複数指定可能
write
: subscribe、unsubscribecreate
: subscribe(subscribe時にsubscription
が作成される)delete
: unsubscribe(unsubscribe時にsubscription
が削除される)
- 以下を複数指定可能
sfuBot
リソース
当該 channel
における、sfuBot
に対する権限を設定するオブジェクト。
actions
*- 以下を複数指定可能
write
: 作成、削除create
: 作成delete
: 削除
- 以下を複数指定可能
forwardings
forwarding
リソースに関するオブジェクトを指定(forwardingオブジェクトについては後述)
forwarding
リソース
当該 sfuBot
における、forwarding
に対する権限を設定するオブジェクト。
actions
*- 以下を複数指定可能
write
: 作成、削除create
: 作成 (任意のメディアをSFU経由で新たに転送することができる)delete
: 削除 (SFU経由でのメディア転送を取りやめることができる)
- 以下を複数指定可能
channel
/ member
における name
と id
について
channel
と member
は、 name
または id
により、対象リソースを指定できます。
それぞれの特徴を以下に記載します。
一意性
id
: SkyWayサーバから自動的に払い出されるid
は一意に定まります。name
: 当該name
を持ったリソースは同時に存在することは出来ませんが、リソース削除後に別のリソースが同じname
で作成される可能性があります。
トークン作成タイミング
id
:id
はChannel
作成時、Member
作成時に自動的に払い出されるため、リソース作成後に、SkyWay Auth Tokenを生成する必要がありますname
: リソース作成前に払い出したトークンを用いて、リソースを作成することが出来ます。
ペイロードのリソース設定例
例1
- あらゆる
name
のChannel
に、あらゆるname
のMember
として入室可能 SFUBot
の作成や、新たなメディア転送も許可する
channels: [
{
name: "*",
actions: ["write"],
members: [
{
name: "*",
actions: ["write"],
publication: {
actions: ["write"],
},
subscription: {
actions: ["write"],
},
},
],
sfuBots: [
{
actions: ["write"],
forwardings: [
{
actions: ["write"]
}
]
}
]
},
]
例2
- "discussion-room"という
name
のChannel
を作成可能 - 当該
Channel
に対して、"Alice"または"Bob"というname
のMember
として入室可能
channels: [
{
name: "discussion-room",
actions: ["write"],
members: [
{
name: "Alice",
actions: ["write"],
publication: {
actions: ["write"],
},
subscription: {
actions: ["write"],
},
},
{
name: "Bob",
actions: ["write"],
publication: {
actions: ["write"],
},
subscription: {
actions: ["write"],
},
},
],
},
]
JavaScriptでのSkyWay Auth Tokenの生成について
@skyway-sdk/token
ライブラリには、SkyWay Auth Tokenを作成するためのクラスが用意されています。
SkyWayAuthToken
インスタンスを作成する際に、コンストラクタにJWTのペイロードとなるJSONオブジェクトを渡し、次に当該インスタンスのencode
メソッドにシークレットキー渡すことで、署名を実施しトークン文字列を作成します。
具体例を以下に示します。
import { SkyWayAuthToken, uuidV4 } from "@skyway-sdk/token";
const token = new SkyWayAuthToken({
jti: uuidV4(),
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 600,
scope: {
app: {
id: "<アプリケーションID>",
turn: true,
actions: ["read"],
channels: [
{
id: "*",
name: "tutorial-room",
actions: ["write"],
members: [
{
id: "*",
name: "*",
actions: ["write"],
publication: {
actions: ["write"],
},
subscription: {
actions: ["write"],
},
},
],
sfuBots: [
{
actions: ["write"],
forwardings: [
{
actions: ["write"]
}
]
}
]
},
],
},
},
});
const tokenString = token.encode(
"<シークレットキー>"
);
🗒️ 利用規約 🗒️ プライバシーポリシー 🌐 ブログ(note) 🐦 Twitter