概要

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

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

Flow

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

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

認証・認可サンプル

SkyWayで利用する認証情報を生成・取得するサンプルはこちらを参照ください。

基本仕様

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 (uuidv4)	トークンのユニークな ID
exp	✔️	UNIX タイムスタンプ	このトークンが無効になる時間を表すタイムスタンプ
scope	✔️	Object	このトークンに付与する権限を表すクレーム

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

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

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

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

署名部

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

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

scope カスタムクレームは、このトークンにどのようなリソースをどのように操作する権限を付与するかを定義するクレームです。例として、あるアプリケーション（ID: sample-app-id）で作成されたある Channel（Name: lesson-room-1）に対して書き込み権限（write）を与えるスコープは次のように表されます。

scope: {
  app: {
    id: 'sample-app-id'
    channels: [
      {
        name: 'lesson-room-1',
        action: ["write"]
      }
    ]
  }
}

このように、スコープでは次に示す階層構造によって各リソースを表し、そのリソースに対して与えられる権限を action フィールドに記述します。

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

各リソースは、アクションと選択子、子リソースの 3 つから構成されます。

アクションは、そのリソースに対する権限（read や write など）を指定するフィールドです。選択子は、そのリソースを選択する文字列を指定するフィールドです。特定の id を持つリソースを選択する ID 選択子と特定の名前を持つリソースを選択する名前選択子の二種類があります。ID 選択子と名前選択子が両方指定された場合は、両者を満たすリソースに対してアクションフィールドに指定された権限が許可されます。選択肢において * は全称選択子と呼ばれ、すべての文字列にマッチします。

指定可能なリソースとその親子関係、および、各リソースに対して指定可能なアクションは以下の通りです。

リソース	親リソース	アクション
App		read
Channel	App	write, read, create, delete, updateMetadata
Member	Channel	write, create, delete, signal, updateMetadata
Publication	Member	write, create, delete, updateMetadata, enable, disable
Subscription	Member	write, create, delete
SFU Bot	Channel	write, create, delete
Forwarding	SFU Bot	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',
        action: ["create", "delete"],
        members: [
          {
            name: 'alice',
            actions: ["create", "delete"],
            publication: {
              action: ["create", "delete"]
            },
            subscription: {
              action: ["create", "delete"]
            }
          },
        ],
        sfuBots: [
          {
            actions: ["create", "delete"],
            forwardings: [
              {
                actions: ["craete", "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',
        action: ["create", "delete"],
        members: [
          {
            name: 'alice',
            actions: ["create", "delete"],
            publication: {
              action: ["create", "delete"]
            },
            subscription: {
              action: ["create", "delete"]
            }
          },
          {
            name: '*',
            actions: ["delete"],
            publication: {
              action: []
            },
            subscription: {
              action: []
            }
          }
        ],
      },
    ]
  }
}

App リソース

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

Name	Type	Required	Description
id	uuid	✔️	アプリケーションの ID を表す選択子。全称選択子 `*` は使用できない。
turn	boolean		TURN サーバーの利用可否。true であれば TURN サーバーを経由して通信することが可能となる。省略された場合は true となる。
actions	read []	✔️	アプリケーション自体に対する権限を配列で指定する。`read` のみ指定可能。
channels	ChannelResource[]	✔️	Channel リソースに関するオブジェクトを配列で指定する。

Channel リソース

Channel を表すオブジェクト

Name	Type	Required	Description
id	uuid \| `*`	※1	指定する Channel の ID を表す選択子。`*` を指定した場合は全称選択子として扱う。
name	string \| `*`	※1	指定する Channel の name を表す選択子。`*` を指定した場合は全称選択子として扱う。
actions	( write \| read \| create \| delete \| updateMetadata )[]	✔️	Channel アクションを配列で指定する。
members	Member Resource[]		Member リソースに関するオブジェクトを配列で指定する。
sfuBots	SFU Bot Resource[]		SFUbot リソースに関するオブジェクトを配列で指定する。

※1: id か name のどちらかが必須。両方指定された場合、その id を持ちかつその name をもつ Channel を表す。片方のみが指定されている場合は指定されていないフィールドは全称選択子 * として扱う。

Channel アクション

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

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

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

Member リソース

Member を表すオブジェクト

Name	Type	Required	Description
id	uuid \| `*`	※2	指定する member の ID を表す選択子。`*` を指定した場合は全称選択子として扱う。
name	string \| `*`	※2	指定する member の name を表す選択子。`*` を指定した場合は全称選択子として扱う。
actions	( write \| create \| delete \| updateMetadata \| signal)[]	✔️	Member アクションを配列で指定する。
publication	Publication Resource		Publication リソースに関するオブジェクトを指定する。
subscription	Subscription Resource		Subscription リソースに関するオブジェクトを指定する。

※2: id か name のどちらかが必須。両方指定された場合、その id を持ちかつその name をもつ Member を表す。片方のみが指定されている場合は指定されていないフィールドは全称選択子 * として扱う。

Member アクション

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

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

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

Publication リソース

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

Name	Type	Required	Description
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 を表すオブジェクト

Name	Type	Required	Description
actions	( write \| create \| delete )[]	✔️	Subscription アクションを配列で指定する。

Subscription アクション

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

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

SFU Bot リソース

SFU Bot を表すオブジェクト

Name	Type	Required	Description
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 を表すオブジェクト

Name	Type	Required	Description
actions	( write \| create \| delete) []	✔️	Forwarding アクションを配列で指定する。

Forwarding アクション

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

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

はじめに

概要