SkyWay Auth Token

正規のエンドユーザーがあらかじめ許可された操作のみを実行できるようにするために、SkyWay はトークンベースの認証・認可機能を提供しています。ユーザーは、自身が認証したエンドユーザーに対して適切な権限を付与したトークン（SkyWay Auth Token）を発行することで、SkyWay に対するエンドユーザーの操作を制限できます。

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

Flow

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

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

このドキュメントは、SkyWay Auth Tokenの最新版であるversion 3について記述されたドキュメントです。 SkyWay Auth Tokenの version プロパティが 1 、 2 、未指定の場合は、旧バージョン SkyWay Auth Token(各種SDK用)のページを参照してください。

SkyWay Auth Token version 3は、各SDKのバージョンが以下のいずれかの場合に利用できます。

JavaScript SDK: v1.11.0以降

iOS SDK: v2.1.7以降

Android SDK: v2.4.0以降

認証・認可サンプル

GitHubで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 ( `3` )	このトークンのバージョン。最新のバージョンである `3` を指定してください
scope	✔️	Object	このトークンに付与する権限を表すクレーム

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

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

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

version は、このトークンのバージョンです。最新のバージョンは 3 です。本ドキュメントでは、version 3 の SkyWay Auth Token について説明します。

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

署名部

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

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

scope は、各リソースに対する操作の権限を定義するクレームです。 SDK のメソッド呼び出しに対応する各リソースの操作を許可するかどうかを設定します。

リソースの階層構造

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

TURN リソース
Analytics リソース
Room リソース
- SFU リソース
- Member リソース

SkyWay では Room ライブラリの利用をお勧めしているため、SkyWay Auth Token では、Room と記述する仕様となっています。

Core ライブラリなど、Channel という名称を用いるライブラリを利用している場合は、本ドキュメントの説明文において Room と表記している箇所を Channel と読み替えてください。なお、Core ライブラリで SkyWay Auth Token を利用する場合であっても、 scope における指定は rooms である必要があります。

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

Room リソースと Member リソースは、id と name のプロパティを持ちます。 Room リソースや Member リソースを指定する際は、少なくとも id または name のどちらか一方のプロパティを指定する必要があります。

SkyWayでは name を利用してリソースを指定することを推奨しています。詳細はセキュアな運用のためのnameの指定の推奨についてをご確認ください。

プロパティにおけるワイルドカードの指定

id および name の各プロパティでは、ワイルドカードとして * を指定できます。 * を指定した場合、0 文字以上のあらゆる文字列にマッチします。加えて、name に * を指定した場合は name を持たないリソースにもマッチします。

また、name のプロパティを lesson-room-* のように指定することにより、lesson-room-1 や lesson-room-a にマッチさせることができます。ワイルドカードは合計8個まで利用できます。

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

name と id が両方指定された場合、指定された id と name の両方を持つリソースにマッチします。片方のみが指定された場合、指定されていない方のプロパティは * が単体で指定されたとみなされます。

メソッド

Room リソースと Member リソースに対する操作の権限はメソッド（methods）として定義します。各リソースに対して指定可能なメソッドは以下の通りです。（各メソッドの詳細は後述します）

リソース	メソッド
Room	create, close, updateMetadata
Member	publish, subscribe, updateMetadata

Member リソースの publish メソッドは、その Member が Publisher である Publication の unpublish 、および updateMetadata の操作も許可します。 Member リソースの subscribe メソッドは、その Member が Subscriber である Subscription の unsubscribe の操作も許可します。

なお、指定したリソースのプロパティの参照(読み取り)は、メソッドの指定に関わらず、リソースの指定がなされている場合は暗黙的に許可されます。したがって、メソッドの指定を空にした場合は、指定したリソースの読み取り専用のトークンとして利用できます。

Room リソースが複数指定されている場合の適用順

Room リソースの指定は、 rooms として複数を同時に指定することができます。 Room リソースが複数指定されている場合は、操作の対象となる Room と Member にマッチする最初の要素の指定のみが適用されます。

例

meeting-room-1 という name を持つ Room において、以下の操作を許可するための SkyWay Auth Token の例を示します。

manager という name を持つ Member による publish の操作
それ以外の Member による subscribe の操作

scope: {
  // ...省略

  rooms: [
    {
      id: "*",
      name: "meeting-room-1",
      methods: [],
      member: {
        id: "*",
        name: "manager",
        methods: ["publish"]
      }
    },
    {
      id: "*",
      name: "meeting-room-1",
      methods: [],
      member: {
        id: "*",
        name: "*",
        methods: ["subscribe"]
      }
    }
  ]
}

manager という name を持つ Member は先に 1 つ目の Room リソースの要素にマッチするため、subscribe の権限は付与されないことに注意してください。この Member にも subscribe の権限を付与する場合は、 1 つ目の要素の Member リソースの指定において、subscribe のメソッドを明示的に指定するようにしてください。

SkyWay Auth Token の例

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

App（id: sample-app-id）において、
- TURN を有効化
- Analytics を有効化
- Room（name: lesson-room-1）の作成・削除、metadataの更新ができる。
- Room（name: lesson-room-1）において SFU を有効化
  - SFU サーバーを介して publish されている Publication に同時に紐づけられる Subscription の数を最大 99 に制限
- Room（name: lesson-room-1）について、
  - alice という名前の Member として入室できる。
  - alice という名前の Member のmetadataの更新ができる。
  - alice が Publisher である Publication を作成・削除できる。
  - alice が Subscriber となる Subscription を作成・削除できる。

scope: {
  appId: "sample-app-id",
  turn: {
    enabled: true
  },
  analytics: {
    enabled: true
  },
  rooms: [
    {
      id: "*",
      name: "lesson-room-1",
      methods: ["create", "close", "updateMetadata"],
      sfu: {
        enabled: true,
        maxSubscribersLimit: 99,
      },
      member: {
        id: "*",
        name: "alice",
        methods: ["publish", "subscribe", "updateMetadata"]
      }
    }
  ]
}

また、Room リソースは、複数の定義を含めることができます。例えば、 2 つの Room に同時に join し、それぞれの Room で実行可能な操作の権限を個別に設定したい場合は以下の例のようになります。

App（id: sample-app-id）において、
- TURN を有効化
- Analytics を有効化
- Room（name: lesson-room-1）の作成・削除、metadataの更新ができる。
- Room（name: lesson-room-1）において SFU を有効化
  - SFU サーバーを介して publish されている Publication に同時に紐づけられる Subscription の数を最大 99 に制限
- Room（name: lesson-room-1）について、
  - alice という名前の Member として入室できる。
  - alice という名前の Member のmetadataの更新ができる。
  - alice が Publisher である Publication を作成・削除できる。
  - alice が Subscriber となる Subscription を作成・削除できる。
- Room（name: lesson-room-2）の参照ができる。
- Room（name: lesson-room-2）において SFU を有効化
  - SFU サーバーを介して publish されている Publication に同時に紐づけられる Subscription の数を最大 99 に制限
- Room（name: lesson-room-2）について、
  - bob という名前の Member として入室できる。
  - bob が Subscriber となる Subscription を作成・削除できる。

scope: {
  appId: "sample-app-id",
  turn: {
    enabled: true
  },
  analytics: {
    enabled: true
  },
  rooms: [
    {
      id: "*",
      name: "lesson-room-1",
      methods: ["create", "close", "updateMetadata"],
      sfu: {
        enabled: true,
        maxSubscribersLimit: 99,
      },
      member: {
        id: "*",
        name: "alice",
        methods: ["publish", "subscribe", "updateMetadata"]
      }
    },
    {
      id: "*",
      name: "lesson-room-2",
      methods: [],
      sfu: {
        enabled: true,
        maxSubscribersLimit: 99,
      },
      member: {
        id: "*",
        name: "bob",
        methods: ["subscribe"]
      }
    }
  ]
}

TURN リソース

TURN サーバーの利用可否を設定するためのオブジェクト

プロパティ	形式	必須	説明
enabled	boolean	✔️	TURN サーバーの利用可否。true の場合、 TURN サーバーを経由して通信することも可能となる。

なお、TURN リソースの指定が省略された場合は、 enabled に true が指定されたものとみなされます。

Analytics リソース

Analytics 機能の利用有無を設定するためのオブジェクト

プロパティ	形式	必須	説明
enabled	boolean	✔️	Analytics 機能の利用有無。true の場合、通信ログをサーバーに送信する。

なお、Analytics リソースの指定が省略された場合は、 enabled に true が指定されたものとみなされます。

SkyWay Auth Token version 1、2 と異なり、 version 3 では analytics を省略した場合は true となります。

Room リソース

Room を表すオブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)\| `*`	※	指定する Room の id。`*` を指定可能。
name	string \| `*`	※	指定する Room の name。`*` を指定可能。
methods	( create \| close \| updateMetadata )[]	✔️	Room メソッドを配列で指定する。
sfu	SFU Resource		SFU リソースに関するオブジェクトを指定する。
member	Member Resource		Member リソースに関するオブジェクトを指定する。

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

member プロパティが指定されている場合は、そのトークンを用いた Room への入室(join)と退室(leave)が暗黙的に許可されます。

Room メソッド

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

create: Room の作成ができる
close: Room の削除ができる
updateMetadata: Room の metadata の編集ができる

なお、Room リソースの指定がなされている場合は、メソッドの指定内容に関わらず暗黙的に参照(読み取り)が許可されます。

SFU リソース

SFU サーバーの利用可否を設定するためのオブジェクト

プロパティ	形式	必須	説明
enabled	boolean	✔️	SFU サーバーの利用有無。true の場合、P2P での通信に加えて SFU サーバーを利用した通信も可能になる。
maxSubscribersLimit	number		SFU サーバーを介して publish されている Publication に同時に紐づけられる Subscription の数の上限。指定した `maxSubscribers` の値がこの値よりも大きい場合は publish 時にエラーとなる。省略された場合は 99 となる。

なお、SFU リソースの指定が省略された場合は、 enabled に true が、 maxSubscribersLimit に 99 が指定されたものとみなされます。

Member リソース

Member を表すオブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)\| `*`	※	指定する Member の id。`*` を指定可能。
name	string \| `*`	※	指定する Member の name。`*` を指定可能。
methods	( publish \| subscribe \| updateMetadata )[]	✔️	Member メソッドを配列で指定する。

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

Member メソッド

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

publish: publish・unpublish、Publication の metadata の編集ができる
subscribe: subscribe・unsubscribe ができる
updateMetadata: Member の metadata の編集ができる

なお、Member リソースの指定がなされている場合は、メソッドの指定内容に関わらず、その Member リソースが指定されている Room に対する参照(読み取り)、および Room への入室(join)と退室(leave)が暗黙的に許可されます。

はじめに

旧バージョン SkyWay Auth Token(各種SDK用)