--- lang: ja path: user-guide/authentication/skyway-auth-token labels: ユーザーガイド/認証・認可/SkyWay Auth Token(各種SDK用) metaTitle: SkyWayAuthToken ｜ 認証・認可 ｜ ユーザーガイド ｜ SkyWay（スカイウェイ） --- # SkyWay Auth Token 正規のエンドユーザーがあらかじめ許可された操作のみを実行できるようにするために、SkyWay はトークンベースの認証・認可機能を提供しています。 ユーザーは、自身が認証したエンドユーザーに対して適切な権限を付与したトークン（SkyWay Auth Token）を発行することで、SkyWay に対するエンドユーザーの操作を制限できます。 次の図は、 SkyWay を利用した認証・認可のフローを示しています。 ![Flow](/media/posts/docs/00_02_authentication_flow_jp.png) 1. エンドユーザーに対応したセッショントークンやパスワードなどの認証情報を、ユーザーアプリケーションのバックエンドサーバーに送信する 2. バックエンドサーバーの認証基盤で認証する 3. エンドユーザーに応じて適切な権限を付与した SkyWay Auth Token を生成する 4. SkyWay Auth Token をフロントエンドアプリケーションに送信する 5. 取得した 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用)](/ja/docs/user-guide/authentication/skyway-auth-token-legacy/)のページを参照してください。 > SkyWay Auth Token version 3は、各SDKのバージョンが以下のいずれかの場合に利用できます。 > > JavaScript SDK: v1.11.0以降 > > iOS SDK: v2.1.7以降 > > Android SDK: v2.4.0以降 > > Linux®︎ SDK: v2.0.0以降 ## 認証・認可サンプル GitHubで[SkyWay Auth Tokenを生成・取得するサンプルコード](https://github.com/skyway/authentication-samples)を公開しています。 このサンプルコードは、以下のような用途で利用できます。 - バックエンドサーバーにおける SkyWay Auth Token 生成の参考実装 - フロントエンド開発時の SkyWay Auth Token 払い出しサーバーのモックサーバー ## 基本仕様 SkyWay Auth Token は JWT（JSON Web Token）形式のトークンとして表されており、ヘッダー部・ペイロード部・署名部の 3 つから構成されます。ヘッダー部には署名の方式の情報、ペイロード部には発行する権限を示した情報、署名部には Base 64 URL 方式で変換されたヘッダとペイロードの署名が含まれます。 ### ヘッダー部 ヘッダー部には、署名生成に利用するアルゴリズムを記述します。 JWT の仕様では、さまざまな署名アルゴリズムを指定できるよう規定されていますが、 SkyWay Auth Token ではアルゴリズムの指定に関するセキュリティ上の問題を回避するため HS256 にのみ対応しています。 ```js { "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 パッケージ](https://www.npmjs.com/package/@skyway-sdk/token) を用いることで、より簡単にトークンを作成することが可能です。 ## スコープによる権限の付与 `scope` は、各リソースに対する操作の権限を定義するクレームです。 SDK のメソッド呼び出しに対応する各リソースの操作を許可するかどうかを設定します。 ### リソースの階層構造 各リソースは次に示す階層構造となっています。 - TURN リソース - Analytics リソース - NoiseCancelling リソース - 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` を利用してリソースを指定することを推奨しています。詳細は各 SDK の以下のドキュメントをご確認ください。 - [JavaScript SDK　セキュアな運用のためのnameの指定の推奨について](/ja/docs/cookbook/javascript-sdk/recommendation-for-using-name) - [iOS SDK　セキュアな運用のためのnameの指定の推奨について](/ja/docs/cookbook/ios-sdk/recommendation-for-using-name) - [Android SDK　セキュアな運用のためのnameの指定の推奨について](/ja/docs/cookbook/android-sdk/recommendation-for-using-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 の操作 ```ts 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 を有効化 - NoiseCancelling を有効化 - 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 を作成・削除できる。 ```js scope: { appId: "sample-app-id", turn: { enabled: true }, analytics: { enabled: true }, noiseCancelling: { 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 を有効化 - NoiseCancelling を有効化 - 文字起こしを有効化 - 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 を作成・削除できる。 ```js scope: { appId: "sample-app-id", turn: { enabled: true }, analytics: { enabled: true }, noiseCancelling: { enabled: true }, stt: { 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` となります。 ### NoiseCancelling リソース AI Noise Canceller の利用有無を設定するためのオブジェクト | プロパティ | 形式 | 必須 | 説明 | | ---------- | ------- | ---- | --------------------------------------------------------------------- | | enabled | boolean | ✔️ | AI Noise Canceller の利用有無。true の場合、AI Noise Cancellerが利用可能になる。 | なお、NoiseCancelling リソースの指定が省略された場合は、 `enabled` に `true` が指定されたものとみなされます。 ### STT リソース 文字起こし(Speach-To-Text)の利用有無を設定するためのオブジェクト | プロパティ | 形式 | 必須 | 説明 | | ---------- | ------- | ---- | --------------------------------------------------------------------- | | enabled | boolean | ✔️ | 文字起こしの結果を受信できる | なお、STT リソースの指定が省略された場合は、 `enabled` に `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 の数の上限。値は0から99まで指定可能。publish時に引数で指定した `maxSubscribers` の値がこの値よりも大きい場合、 publish 時にエラーとなる。| なお、SFU リソースの指定が省略された場合は、 `enabled` に `true` が、 `maxSubscribersLimit` に `99` が指定されたものとみなされます。 > SFU リソースの `enabled` を `false` に設定した場合、Room (type: default) もしくは SFURoom を利用しようとすると、権限不足によりエラーが発生します。 > 対処として、P2PRoom を利用するか、SFU リソースの権限を与えてください。 > Room の種類に関しては、[Room と P2PRoom・SFURoom の併用](/ja/docs/user-guide/commons/default-room/)のページを参照してください。 ### 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)が暗黙的に許可されます。 ## 商標 Linux®︎は、米国およびその他の国における Linus Torvalds の登録商標です。