旧バージョン SkyWay Auth Token

このドキュメントは、SkyWay Auth Tokenの version 1(version未指定も含む)、または version 2 について記述されたドキュメントです。 SkyWay Auth Tokenの version プロパティが 3 となっているSkyWay Auth Tokenをご利用の場合は、SkyWay Auth Token(各種SDK用)のページを参照してください。また、現在 version 1、または 2 の SkyWay Auth Token をご利用中の方は、 version 3 への移行をご検討ください。

SkyWay は、ユーザーが認証していないエンドユーザーによる SkyWay の不正利用を防ぐため、トークンベースの認証・認可機能を提供しています。ユーザーは、自身が認証したエンドユーザーに対して適切な権限を付与したトークン（SkyWay Auth Token）を発行することで、エンドユーザーによる SkyWay の不正な利用を防ぐことができます。

次の図は、 SkyWay を利用した認証・認可のフローを示しています。

Flow

エンドユーザーに対応したセッショントークンやパスワードなどの認証情報を、ユーザーアプリケーションのバックエンドサーバーに送信する
バックエンドサーバーの認証基盤で認証する
エンドユーザーに応じて適切な権限を付与した SkyWay Auth Token を生成する
SkyWay Auth Token をフロントエンドアプリケーションに送信する
取得した SkyWay Auth Token を SkyWay SDK に設定し、 SkyWay へのリクエストに用いる

悪意のある攻撃者によるトークンの改ざんを防ぐため、 SkyWay Auth Token にはシークレットキーによる署名が必要です。シークレットキーは、 SkyWay コンソールにログイン後、アプリケーション一覧画面から取得できます。

認証・認可サンプル

GitHubでSkyWay Auth Tokenを生成・取得するサンプルコードを公開しています。このサンプルコードは、以下のような用途で利用できます。

バックエンドサーバーにおける SkyWay Auth Token 生成の参考実装
フロントエンド開発時の SkyWay Auth Token 払い出しサーバーのモックサーバー

基本仕様

SkyWay Auth Token は JWT（JSON Web Token）形式のトークンとして表されており、ヘッダー部・ペイロード部・署名部の 3 つから構成されます。ヘッダー部には署名の方式の情報、ペイロード部には発行する権限を示した情報、署名部には Base 64 URL に変換されたヘッダとペイロードの署名が含まれます。

ヘッダー部

ヘッダー部には、署名生成に利用するアルゴリズムを記述します。 JWT の仕様では、さまざまな署名アルゴリズムを指定できるよう規定されていますが、 SkyWay Auth Token ではアルゴリズムの指定に関するセキュリティ上の問題を回避するため HS256 にのみ対応しています。

{
  "alg" : "HS256",
  "typ" : "JWT"
}

ペイロード部

ペイロード部には JWT の仕様で定められるクレームの他、このトークンに付与する権限を定義する scope クレームを記述します。

クレーム	必須	形式	説明
iat	✔️	UNIX タイムスタンプ	トークンが発行された日時
jti	✔️	string (UUID v4)	トークンのユニークな id
exp	✔️	UNIX タイムスタンプ	このトークンが無効になる時間を表すタイムスタンプ
version		number	このトークンのバージョン
scope	✔️	Object	このトークンに付与する権限を表すクレーム

iat はトークンが発行された日時を示します。検証されるタイミングより後の時刻が iat として指定されているとエラーになります。ただし、時刻同期のズレを考慮して +2分 まで許容されます。

jti は、トークンを一意に識別するための値です。トークン生成時に UUID v4 を生成し、設定する必要があります。

exp は、このトークンが無効になる時間を表すタイムスタンプです。この値を過ぎた時刻において、このトークンを用いたリクエストは失敗します。iat で示した時刻から +3日 を超えた時刻を設定するとエラーになります。

version は、このトークンのバージョンです。指定していなければ1となります。2以上を指定することで、ChannelおよびMemberのNameにワイルドカードが利用できます。（後述）

scope は、このトークンに付与する権限を表すクレームです。詳しくは「スコープによる権限の付与」を参照してください。

署名部

署名部には、悪意のある攻撃者によるトークンの改ざんを防ぐために HS256 による署名を記述します。署名は Base 64 URL エンコードに変換されたヘッダとペイロードに対して行います。ユーザー独自の方法で JWT の署名を行うことも可能ですが、SkyWay が公式に提供している @skyway-sdk/token パッケージを用いることで、より簡単にトークンを作成することが可能です。

スコープによる権限の付与

scope は、各リソースに対する操作に関する権限を定義するクレームです。どのリソースについてどのような操作を可能とするか、を定義することができます。

リソースの階層構造

各リソースは次に示す階層構造となっております。

App リソース
- Channel リソース
  - Member リソース
    - Publication リソース
    - Subscription リソース
  - SFU Bot リソース
    - Forwarding リソース

Channel / Memberリソースの指定方法

ChannelリソースとMemberリソースは、idとnameを持ちます。 scope クレームでは、これらのリソースの指定のため少なくとも id または name のどちらか一方を指定する必要があります。

SkyWayでは name を利用してリソースを指定することを推奨しています。詳細は各 SDK の以下のドキュメントをご確認ください。

`*`の利用について

idおよびnameには、*のみを指定可能です。 *のみを指定した場合、あらゆる文字列にマッチします。また、nameに*のみを指定した場合、nameを持たないリソースにもマッチします。

また、versionに2以上を指定すると、nameに対して、ワイルドカードとしての*を利用可能です。例えば、lesson-room-*と指定することにより、lesson-room-1やlesson-room-aにマッチさせることができます。ワイルドカードは合計8個まで利用できます。

なお、version2でnameに*を含む値をマッチさせたい場合は、バックスラッシュでエスケープして\*と記載する必要があります。例えば、lesson-room-\*と指定することにより、lesson-room-1やlesson-room-aではなく、lesson-room-*にマッチさせることができます。

nameとidが両方指定された場合、指定されたidとnameの両方を持つリソースにマッチします。片方のみが指定された場合、指定されていない方が *のみとして扱われます。

アクション

リソースに対する操作の権限はアクション（actions）として定義します。各リソースに対して指定可能なアクションは以下の通りです。（各アクションの詳細は後述します）

リソース	アクション
App	read
Channel	write, read, create, delete, updateMetadata
Member	write, create, delete, signal, updateMetadata
Publication	write, create, delete, updateMetadata, enable, disable
Subscription	write, create, delete
SFU Bot	write, create, delete
Forwarding	write, create, delete

例

例として、すべてのリソースについて権限を指定したスコープを以下に示します。このスコープはトークンに以下の権限を付与します。

App（id: sample-app-id）において、
- Channel（Name: lesson-room-1）を作成・削除できる。
- Channel（Name: lesson-room-1）について、
  - alice という名前の Member を作成・削除できる。
  - alice が Publisher である Publication を作成・削除できる。
  - alice が Subscriber となる Subscription を作成・削除できる。
  - SFU Bot を Channel に作成・削除できる。
    - SFU Bot に Forwarding の作成・削除をさせることができる。

scope: {
  app: {
    id: "sample-app-id",
    actions: ["read"],
    channels: [
      {
        name: "lesson-room-1",
        actions: ["create", "delete"],
        members: [
          {
            name: "alice",
            actions: ["create", "delete"],
            publication: {
              actions: ["create", "delete"]
            },
            subscription: {
              actions: ["create", "delete"]
            }
          },
        ],
        sfuBots: [
          {
            actions: ["write"],
            forwardings: [
              {
                actions: ["create", "delete"]
              }
            ]
          }
        ]
      },
    ]
  }
}

また、一部のリソースは、複数のリソースを下位の階層に含めることができます。例えば、 1 つの Channel に複数の Member を含め、次のようなスコープを定義できます。

App（ID: sample-app-id）において、
- Channel（Name: lesson-room-1）を作成・削除できる。
- Channel（Name: lesson-room-1）について、
  - alice という名前の Member を作成・削除できる。
    - alice が Publisher である Publication を作成・削除できる。
    - alice が Subscriber となる Subscription を作成・削除できる。
  - （*を使用しているので）すべての Member を削除できる。

scope: {
  app: {
    id: "sample-app-id",
    actions: ["read"],
    channels: [
      {
        name: "lesson-room-1",
        actions: ["create", "delete"],
        members: [
          {
            name: "alice",
            actions: ["create", "delete"],
            publication: {
              actions: ["create", "delete"]
            },
            subscription: {
              actions: ["create", "delete"]
            }
          },
          {
            name: "*",
            actions: ["delete"],
            publication: {
              actions: []
            },
            subscription: {
              actions: []
            }
          }
        ],
      },
    ]
  }
}

App リソース

あるアプリケーションを表すオブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	✔️	アプリケーションの id。 `*` は指定できない。
turn	boolean		TURN サーバーの利用可否。true の場合、 TURN サーバーを経由して通信することが可能となる。省略された場合は true となる。
analytics	boolean		Analytics の利用有無。true の場合、通信ログをサーバーに送信する。省略された場合は false となる。
actions	read []	✔️	アプリケーション自体に対する権限を配列で指定する。`read` のみ指定可能。
channels	ChannelResource[]	✔️	Channel リソースに関するオブジェクトを配列で指定する。

Channel リソース

Channel を表すオブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)\| `*`	※	指定する Channel の id。`*` を指定可能。
name	string \| `*`	※	指定する Channel の name。`*` を指定可能。
actions	( write \| read \| create \| delete \| updateMetadata )[]	✔️	Channel アクションを配列で指定する。
members	Member Resource[]		Member リソースに関するオブジェクトを配列で指定する。
sfuBots	SFU Bot Resource[]		SFUbot リソースに関するオブジェクトを配列で指定する。

※: 上記「Channel / Memberリソースの指定方法」を参照

Channel アクション

Channel リソースの actions には、以下の値が指定可能

read: Channel の取得
write: Channel のすべての操作
create: Channel の作成
delete: Channel の削除
updateMetadata: metadata の編集

ただし、書き込み権限（write | create | delete | updateMetadata）のいずれかが設定されている場合、暗黙的に読み込み権限（read）も付与される。

Member リソース

Member を表すオブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)\| `*`	※	指定する Member の id。`*` を指定可能。
name	string \| `*`	※	指定する Member の name。`*` を指定可能。
actions	( write \| create \| delete \| updateMetadata \| signal )[]	✔️	Member アクションを配列で指定する。
publication	Publication Resource		Publication リソースに関するオブジェクトを指定する。
subscription	Subscription Resource		Subscription リソースに関するオブジェクトを指定する。

※: 上記「Channel / Memberリソースの指定方法」を参照

Member アクション

Member リソースの actions には、以下の値が指定可能

write: Member のすべての操作
create: Member の作成、MemberTtl の Update
delete: Member の削除
updateMetadata: metadata の編集
signal: シグナリング情報のやり取り ※3

※3: Pub/Sub を行う場合に必要

Publication リソース

親リソースである Member リソースによって表される Member を Publisher とする Publication を表すオブジェクト

プロパティ	形式	必須	説明
actions	( write \| create \| delete \| updateMetadata \| enable \| disable )[]	✔️	Publication アクションを配列で指定する。

Publication アクション

Publication リソースの actions には、以下の値が指定可能

write: Publication のすべての操作
create: Publication の作成
delete: Publication の削除
updateMetadata: metadata の編集
enable: Publication の有効化
disable: Publication の無効化

Subscription リソース

親リソースである Member リソースによって表される Member を Subscriber とする Subscription を表すオブジェクト

プロパティ	形式	必須	説明
actions	( write \| create \| delete )[]	✔️	Subscription アクションを配列で指定する。

Subscription アクション

Subscription リソースの actions には、以下の値が指定可能

write: Subscription のすべての操作
create: Subscription の作成
delete: Subscription の削除

SFU Bot リソース

SFU Bot を表すオブジェクト

プロパティ	形式	必須	説明
actions	( write \| create \| delete ) []	✔️	SFU Bot アクションを配列で指定する。
forwardings	Forwarding Resource[]		Forwarding リソースに関するオブジェクトを配列で指定する。

SFU Bot アクション

SFU Bot リソースの actions には、以下の値が指定可能

write: SFU Bot のすべての操作
create: SFU Bot の作成
delete: SFU Bot の削除

Forwarding リソース

Forwarding を表すオブジェクト

プロパティ	形式	必須	説明
actions	( write \| create \| delete ) []	✔️	Forwarding アクションを配列で指定する。

Forwarding アクション

Forwarding リソースの actions には、以下の値が指定可能

write: Forwarding のすべての操作
create: Forwarding の作成
delete: Forwarding の削除

SkyWay Auth Token(各種SDK用)

SkyWay Admin Auth Token(SkyWay Channel API, SkyWay Recording API用)