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を生成した場合、シークレットキーをエンドユーザーが取得できるため、誰でも任意の ChannelRoom に入ることができる等のセキュリティ上の問題が発生します。

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 *
    • channelmember などSkyWayの各種リソースに対する権限を指定するオブジェクト
    • 以下の通り階層化されている
      • app
        • channel
          • member
            • publication
            • subscription

以下より、 scope 内の各種リソースのパラメータについて説明します。

app リソース

アプリケーションの設定を記載するオブジェクト。

  • id *
    • アプリケーションIDを指定(SkyWayにログインして取得した値を記載します)。
  • turn
    • TURNサーバの利用可否。形式はboolean
      • trueにした場合はturnサーバを経由して通信することが可能となり、falseの場合は経由しません。
  • actions *
    • アプリケーション自体に関する権限。現在は'read'固定。(今後のSkyWayのアップデートにより、取りうる値が増える予定です。)
  • channels *
    • channelリソースに関するオブジェクトを配列で指定

channel リソース

当該アプリケーションにおける、channel に対する権限を設定するオブジェクト。

Roomライブラリを利用する場合、内部的には channel を利用するため、ここで Roomid または 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、unpublish
      • create: publish(publish時に publication が作成される)
      • delete: unpublish(unpublish時に publication が削除される)

subscription リソース

当該 member がもつ subscription に対する権限を設定するオブジェクト。

  • actions *
    • 以下を複数指定可能
      • write: subscribe、unsubscribe
      • create: 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 における nameid について

channelmember は、 name または id により、対象リソースを指定できます。

それぞれの特徴を以下に記載します。

  • 一意性

    • id: SkyWayサーバから自動的に払い出される id は一意に定まります。
    • name: 当該 name を持ったリソースは同時に存在することは出来ませんが、リソース削除後に別のリソースが同じ name で作成される可能性があります。
  • トークン作成タイミング

    • id: idChannel 作成時、 Member 作成時に自動的に払い出されるため、リソース作成後に、SkyWay Auth Tokenを生成する必要があります
    • name: リソース作成前に払い出したトークンを用いて、リソースを作成することが出来ます。

ペイロードのリソース設定例

例1

  • あらゆる nameChannel に、あらゆる nameMember として入室可能
  • SFUBot の作成や、新たなメディア転送も許可する
channels: [
  {
    name: "*",
    actions: ["write"],
    members: [
      {
        name: "*",
        actions: ["write"],
        publication: {
          actions: ["write"],
        },
        subscription: {
          actions: ["write"],
        },
      },
    ],
    sfuBots: [
      {
        actions: ["write"],
        forwardings: [
          {
            actions: ["write"]
          }
        ]
      }
    ]
  },
]

例2

  • "discussion-room"という nameChannel を作成可能
  • 当該 Channel に対して、"Alice"または"Bob"という nameMember として入室可能
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