認証・認可

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

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

Flow

  1. エンドユーザーに対応したセッショントークンやパスワードなどの認証情報を、ユーザーアプリケーションのバックエンドサーバーに送信する
  2. バックエンドサーバーの認証基盤で認証する
  3. エンドユーザーに応じて適切な権限を付与した SkyWay Auth Token を生成する
  4. SkyWay Auth Token をフロントエンドアプリケーションに送信する
  5. 取得した 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 (UUID v4)トークンのユニークな 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 は、各リソースに対する操作に関する権限を定義するクレームです。どのリソースについてどのような操作を可能とするか、を定義することができます。

リソースの階層構造

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

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

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

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

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

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

なお、SkyWayではnameを利用してリソースを指定することを推奨しています。詳細はこちらをご確認ください。

アクション

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

リソースアクション
Appread
Channelwrite, read, create, delete, updateMetadata
Memberwrite, create, delete, signal, updateMetadata
Publicationwrite, create, delete, updateMetadata, enable, disable
Subscriptionwrite, create, delete
SFU Botwrite, create, delete
Forwardingwrite, 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 リソース

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

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

Channel リソース

Channel を表すオブジェクト

プロパティ形式必須説明
idstring (UUID v4)| *指定する Channel の id。* を指定可能。
namestring | *指定する Channel の name。* を指定可能。
actions( write | read | create | delete | updateMetadata )[]✔️Channel アクションを配列で指定する。
membersMember Resource[]Member リソース に関するオブジェクトを配列で指定する。
sfuBotsSFU 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 を表すオブジェクト

プロパティ形式必須説明
idstring (UUID v4)| *指定する Member の id。* を指定可能。
namestring | *指定する Member の name。* を指定可能。
actions( write | create | delete | updateMetadata | signal)[]✔️Member アクションを配列で指定する。
publicationPublication ResourcePublication リソースに関するオブジェクトを指定する。
subscriptionSubscription ResourceSubscription リソースに関するオブジェクトを指定する。

※: 上記「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 アクション を配列で指定する。
forwardingsForwarding Resource[]Forwarding リソースに関するオブジェクトを配列で指定する。

SFU Bot アクション

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

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

Forwarding リソース

Forwarding を表すオブジェクト

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

Forwarding アクション

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

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