概要

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 (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 つから構成されます。

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

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

リソース親リソースアクション
Appread
ChannelAppwrite, read, create, delete, updateMetadata
MemberChannelwrite, create, delete, signal, updateMetadata
PublicationMemberwrite, create, delete, updateMetadata, enable, disable
SubscriptionMemberwrite, create, delete
SFU BotChannelwrite, create, delete
ForwardingSFU Botwrite, 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 リソース

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

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

Channel リソース

Channel を表すオブジェクト

NameTypeRequiredDescription
iduuid | *※1指定する Channel の ID を表す選択子。* を指定した場合は全称選択子として扱う。
namestring | *※1指定する Channel の name を表す選択子。* を指定した場合は全称選択子として扱う。
actions( write | read | create | delete | updateMetadata )[]✔️Channel アクションを配列で指定する。
membersMember Resource[]Member リソース に関するオブジェクトを配列で指定する。
sfuBotsSFU Bot Resource[]SFUbot リソース に関するオブジェクトを配列で指定する。

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

Channel アクション

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

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

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

Member リソース

Member を表すオブジェクト

NameTypeRequiredDescription
iduuid | *※2指定する member の ID を表す選択子。* を指定した場合は全称選択子として扱う。
namestring | *※2指定する member の name を表す選択子。* を指定した場合は全称選択子として扱う。
actions( write | create | delete | updateMetadata | signal)[]✔️Member アクションを配列で指定する。
publicationPublication ResourcePublication リソースに関するオブジェクトを指定する。
subscriptionSubscription ResourceSubscription リソースに関するオブジェクトを指定する。

※2: idname のどちらかが必須。両方指定された場合、その 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 を表すオブジェクト

NameTypeRequiredDescription
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 を表すオブジェクト

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

Subscription アクション

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

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

SFU Bot リソース

SFU Bot を表すオブジェクト

NameTypeRequiredDescription
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 を表すオブジェクト

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

Forwarding アクション

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

  • write: Forwarding のすべての操作
  • create: Forwarding の作成
  • delete: Forwarding の削除
当ウェブサイトでは、webサイトのパフォーマンス改善などを目的に、Cookie(クッキー)を利用しております。
「Cookieを受け入れる」をクリックすると、Cookieの利用に同意したこととみなします。詳細はこちら