################
認証ウェブフック
################
概要
====
Sora 自体はクライアントの接続を認証する機能を持っていません。認証する場合は外部に認証サーバーを用意する必要があります。
Sora はシグナリング経由で送られてきた情報や、
そのチャネルに接続している情報を POST リクエストで ``sora.conf`` の :ref:`auth_webhook_url` に指定された URL へ送信します。
このとき送信する情報は JSON 形式です。
注意
====
シグナリング :json:`"type": "connect"` 経由で送られてきた情報がそのまま認証ウェブフックのリクエストとして送信されるわけではありません。
ログの出力
-------------------
``sora.conf`` の :ref:`auth_webhook_url` を有効にしない場合でも ``log/auth_webhook.jsonl`` は生成されます。
HTTP ヘッダー
=====================================
.. warning:: この機能は :doc:`実験的機能 ` のため、正式版では仕様が変更される可能性があります
.. note:: JSON のパース時の判断などに利用してください。
sora-connection-id
-----------------------------------
認証ウェブフックの HTTP ヘッダー に ``sora-connection-id`` というヘッダー名でコネクション ID が入ってきます。
コネクション ID が ``WCJC78EWK935N7P7Z8FYAKFW9M`` の場合は ``sora-connection-id: WCJC78EWK935N7P7Z8FYAKFW9M`` のように値が入ってきます。
設定
======================
auth_webhook_url
--------------------
:デフォルト: 未設定
認証可否の判断に使用する HTTP リクエストの送信先を ``sora.conf`` の :ref:`auth_webhook_url` に設定します。
認証ウェブフック機能を使用する場合は指定してください。
HTTP のレスポンスは認証の可否に関わらず、 200 OK 等 200 番台のステータスコードを返す必要があります。
.. code-block:: ini
auth_webhook_url = http://127.0.0.1:8080/sora/auth/webhook
認証処理時に送信する JSON
================================
Sora は、 ``sora.conf`` の :ref:`auth_webhook_url` に設定した URL に対して **POST リクエスト** で次のような JSON を送ります。
.. code-block:: javascript
{
"audio": true,
"audio_codec_type": "OPUS",
"channel_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"connection_id": "VSMDDJG3ZH1RHB93W260APVEQW",
"data_channel_signaling": true,
"data_channels": [
{
"compress": false,
"direction": "sendrecv",
"label": "#abc",
"ordered": true
}
],
"e2ee": false,
"ignore_disconnect_websocket": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"node_name": "node1@192.0.2.10",
"role": "sendrecv",
"simulcast": false,
"sora_client": {
"environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.109 Safari/537.36",
"raw": "Sora JavaScript SDK 2023.2.0",
"type": "Sora JavaScript SDK",
"version": "2023.2.0"
},
"spotlight": false,
"timestamp": "2022-06-08T07:51:32.593704Z",
"version": "2023.2.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9"
}
- version
- Sora のバージョンが ``文字列`` で入ってきます
- label
- ``sora.conf`` の :ref:`label` で指定した値が入ってきます
- node_name
- Sora のノード名が入ってきます
- timestamp
- ウェブフックリクエスト送信時のタイムスタンプが RFC3339 フォーマットで入ってきます
- マイクロ秒まで含まれています
- id
- Base32-UUIDv4 です
- ウェブフック毎に割り当てられるユニークな値です
- e2ee
- クライアントが E2EE を有効にしているかどうかが入ってきます
- ``true`` の場合は E2EE を利用する接続です
- multistream
- マルチストリームでの接続要求を出しているかどうかの値が入ってきます
- クライアントが送ってこない場合は ``true`` が設定されます
- ``true`` の場合はマルチストリームを希望している接続です
- simulcast
- サイマルキャストでの接続要求を出しているかどうかの値が入ってきます
- ``true`` の場合はサイマルキャストを希望している接続です
- クライアントが送ってこない場合は ``false`` が設定されます
- simulcast_rid
- ``simulcast`` が ``true`` かつ ``spotlight`` が ``false`` の場合のみこの値が入ってきます
- サイマルキャストでの受け取る rid を指定します
- spotlight
- スポットライトでの接続要求を出しているかどうかの値が入ってきます
- クライアントが送ってこない場合は ``false`` が設定されます
- spotlight_focus_rid
- ``spotlight`` が ``true`` の場合のみこの値が入ってきます
- スポットライトでフォーカスされた参加者の映像を受信する rid を指定します
- spotlight_unfocus_rid
- ``spotlight`` が ``true`` の場合のみこの値が入ってきます
- スポットライトでフォーカスされていない参加者の映像を受信する rid を指定します
- spotlight_number
- **この項目はオプションです**
- クライアントが送ってこない場合は、この値は含まれません
- ``spotlight_number`` をシグナリングの connect 時に送ってきた場合に値が入ります
- role
- 以下が入ってきます
- ``sendrecv`` (送受信)
- ``sendonly`` (送信)
- ``recvonly`` (受信)
- metadata
- **この項目はオプションです**
- ユーザーが定義を自由にできる値です
- JSON で使用できる形式ならどんな値でも指定できます
- ``"type": "connect"`` で ``metadata`` が送られてこない場合、アプリケーション側にも送られません
- authn_metadata
- この項目は metadata と同じです
- metadata の別名です
- ``"type": "connect"`` で ``metadata`` が送られてこない場合、アプリケーション側にも送られません
- channel_id
- 認証対象のクライアントが接続要求を出しているチャネル ID です
- client_id
- 認証対象のクライアントが利用要求を出しているクライアント ID です
- bundle_id
- 認証対象のコネクションが利用要求を出しているバンドル ID です
- connection_id
- Base32-UUIDv4 です
- 認証対象のコネクションに割り当てられたユニークな ID です
- channel_connections
- 現在そのチャネルの接続数です
- 自分は含まれません
- channel_sendrecv_connections
- 現在そのチャネルで送受信をしている配信者の接続数です
- 自分は含まれません
- channel_sendonly_connections
- 現在そのチャネルで送信のみをしている配信者の接続数です
- 自分は含まれません
- channel_recvonly_connections
- 現在そのチャネルの配信を受信のみしている視聴者の接続数です
- 自分は含まれません
- audio
- ``true`` または ``false`` が入ってきます
- ``false`` の場合は ``audio`` を使用しません
- audio_codec_type
- **この項目はオプションです**
- ``audio`` が ``false`` の場合は含まれません
- コーデックの種類は ``OPUS`` または ``LYRA`` です
- audio_bit_rate
- **この項目はオプションです**
- ``audio`` が ``false`` やクライアントが送ってこない場合、含まれません
- この設定は ``audio_codec_type`` が ``OPUS`` の時のみ有効です
- :ref:`default_audio_bit_rate` に値を指定していた場合はその値が利用されます
- 最小が 6 で、最大が 510 です
- 単位は ``kbps`` です
- video
- ``true`` または ``false`` が入ってきます
- ``false`` の場合は ``video`` を使用しません
- video_codec_type
- **この項目はオプションです**
- ``video`` が ``false`` の場合は含まれません
- コーデックはクライアントが送ってこない場合はデフォルトで ``VP9`` が使用されます
- コーデックの種類は ``VP8``、 ``VP9``、 ``AV1``、 ``H264``、 ``H265`` です
- video_bit_rate
- **この項目はオプションです**
- ``video`` が ``false`` の場合は含まれません
- ビットレートはクライアントが送ってこない場合は ``sora.conf`` の :ref:`default_video_bit_rate` が使用されます
- デフォルトは 500 です
- 最小が 1 で、最大が 30000 です
- 15000 より大きい値は現時点でサポート範囲外です
- 単位は ``kbps`` です
- metadata
- **この項目はオプションです**
- ユーザーが定義を自由にできる値です
- JSON で使用できる形式ならどんな値でも指定できます
- ``"type": "connect"`` で ``metadata`` が送られてこない場合、アプリケーション側にも送られません
- authn_metadata
- **この項目はオプションです**
- この項目は metadata と同じです
- metadata の別名です
- ``"type": "connect"`` で ``metadata`` が送られてこない場合、アプリケーション側にも送られません
- data_channel_signaling
- シグナリングの DataChannel 切り替えをするかどうか
- ignore_disconnect_websocket
- シグナリングの DataChannel 切り替え時に WebSocket の切断を無視するかどうか
- data_channels
- **この項目はオプションです**
- DataChannel を利用したメッセージングの定義が入ってきます
- forwarding_filter
- **この項目はオプションです**
- 転送フィルターが入ってきます
- クライアントが指定しない場合は入ってきません
- sora_client
- **この項目はオプションです**
- クライアントから送られてきた情報が入ってきます
.. _auth-webhook-channel-ongoing-connections-count:
認証ウェブフックに含まれる同時接続数について
================================================
.. important: 認証ウェブフックで送られてくる同時接続数、そのウェブフックが送られたタイミングの値であり、
厳密にそのチャネルの同時接続数を制限する値としては利用できません。
- channel_connections
- channel_sendrecv_connections
- channel_sendonly_connections
- channel_recvonly_connections
これら認証ウェブフックに含まれる同時接続数は WebRTC が確立した後に +1 され、WebRTC が切断されたタイミングで -1 されます。
そのため認証タイミングと WebRTC 確立時の時間差が存在します。
さらに、認証ウェブフックは並列で処理されるため、アプリ側でこの同時接続数の値を利用した厳密な同時接続数の制限を行う事はできません。
もし厳密なチャネル単位での同時接続数を制限したい場合は、
イベントウェブフック ``connection.created`` を利用して、
アプリ側でデータベースでロックを取ってカウントを行い、ロックを取って数値をチェックして認証を行ってください。
sora_client
======================
認証ウェブフックの ``sora_client`` にはクライアントから送られてきた情報が入ってきます。
クライアントから情報が送られてこなければ含まれません。 Sora SDK を利用している場合は必ず入ってきます。
.. code-block:: javascript
"sora_client": {
"environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36",
"raw": "Sora JavaScript SDK 2021.1.0",
"type": "Sora JavaScript SDK",
"version": "2023.2.0"
},
- type
- オプションです
- クライアントから送られてきた Sora SDK またはクライアントのタイプが入ってきます
- raw
- オプションです
- クライアントから送られてきた sora_client の値がそのまま入ってきます
- version
- オプションです
- クライアントから送られてきた Sora SDK またはクライアントのバージョンが入ってきます
- commit_short
- オプションです
- クライアントから送られてきた Sora SDK のコミットハッシュが入ってきます
- environment
- オプションです
- クライアントから送られてきた端末情報が入ってきます
- libwebrtc
- オプションです
- クライアントから送られてきた libwebrtc のバージョン情報が入ってきます
認証成功時のレスポンス JSON
==============================
認証に成功した場合は、以下の JSON を 200 番台で返してください。
.. code-block:: javascript
{
"allowed": true
}
Sora は "allowed" が true の場合は認証を成功と判断して処理をします。
認証成功時の払い出し項目
----------------------------------
認証成功時に様々な項目を払い出すことができます。
詳細は :doc:`認証ウェブフック成功時の払い出し ` をご確認ください。
認証失敗時のレスポンス JSON
====================================
認証に失敗した場合は、以下の JSON を返してください。
.. code-block:: javascript
{
"allowed": false,
"reason": ""
}
.. note:: 認証失敗の場合も HTTP レスポンスのステータスコードは 200 番台である必要があります
Sora は ``"allowed"`` が ``false`` で、 ``"reason"`` が含まれている場合に認証失敗と判断して処理します。
``"reason"`` は必須です、何かしらエラー理由を **100 バイト以内** の文字列を指定してください。
認証に失敗した場合、認証サーバーから送られてきた "reason" の内容は文字列としてクライアントに送られます。
::
"<認証サーバーから送られてきた reason>"
認証ウェブフック成功時の払い出し
=======================================
認証サーバーは認証成功時に様々な値を出すことができます。
.. code-block:: javascript
{
"allowed": true,
"event_metadata": {
"pk": 1
}
}
詳細は :doc:`認証ウェブフック成功時の払い出し ` をご確認ください。
.. _auth-webhook-log:
認証ウェブフックログ
====================
``sora.conf`` の :ref:`auth_webhook_log` を ``true`` にしている場合は ``log/auth_webhook.jsonl`` が出力されます。
.. important:: ``auth_webhook_log`` はデフォルトで ``true`` です。
このログには認証ウェブフックのリクエストとレスポンス、ウェブフック URL、タイムスタンプが含まれます。
- req
- 認証ウェブフックの送信リクエストがそのまま入ります
- res
- 認証ウェブフックの戻り値がそのまま入ります
- url
- auth_webhook_url を指定していない場合はログに含まれません
- timestamp
- RFC3339 フォーマットのタイムスタンプが入ります
- UTC です
auth_webhook_url あり / レスポンスあり
---------------------------------------
.. code-block:: javascript
{
"req": {
"audio": true,
"audio_codec_type": "OPUS"
"channel_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"connection_id": "F2SMT1W59S5ADDZ84CMQ8CDBX4",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"node_name": "node1@192.0.2.10",
"role": "sendrecv",
"simulcast": false,
"sora_client": {
"environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
"raw": "Sora JavaScript SDK 2020.5.0",
"type": "Sora JavaScript SDK",
"version": "2023.2.0"
},
"spotlight": false,
"timestamp": "2020-12-07T09:16:54.079650Z",
"version": "2023.2.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9"
},
"res": {
"allowed": true,
"event_metadata": {
"abc": "efg"
},
"metadata": "abc",
"signaling_notify_metadata": {
"a": "b"
}
},
"timestamp": "2020-12-07T09:16:54.089962Z",
"url": "http://127.0.0.1:3001/sora/auth/webhook"
}
auth_webhook_url あり / レスポンスなし
--------------------------------------
- res がありません
.. code-block:: javascript
{
"req": {
"audio": true,
"audio_codec_type": "OPUS",
"channel_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"connection_id": "0FBC8HF84544ZDHYYN9BCRNZG8",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"node_name": "node1@192.0.2.10",
"role": "sendrecv",
"simulcast": false,
"sora_client": {
"environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
"raw": "Sora JavaScript SDK 2020.5.0",
"type": "Sora JavaScript SDK",
"version": "2023.2.0"
},
"spotlight": false,
"timestamp": "2020-12-07T06:30:56.240917Z",
"version": "2023.2.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9"
},
"timestamp": "2020-12-07T06:30:56.252785Z",
"url": "http://127.0.0.1:3001/sora/authn/webhook"
}
auth_webhook_url なし
--------------------------
- url がありません
.. code-block:: javascript
{
"req": {
"audio": true,
"audio_codec_type": "OPUS",
"channel_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"client_id": "K8PCW533MN1WK24YNZ83HDP74C",
"connection_id": "K8PCW533MN1WK24YNZ83HDP74C",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"node_name": "node1@192.0.2.10",
"role": "sendrecv",
"simulcast": false,
"sora_client": {
"environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_0_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
"raw": "Sora JavaScript SDK 2020.5.0",
"type": "Sora JavaScript SDK",
"version": "2023.2.0"
},
"spotlight": false,
"timestamp": "2020-12-07T06:26:58.916204Z",
"version": "2023.2.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9"
},
"res": {
"allowed": true
},
"timestamp": "2020-12-07T06:26:58.916242Z"
}
エラーメッセージ
================================
これらエラーメッセージは sora.jsonl に出力されます。
AUTH_WEBHOOK_RESPONSE_UNEXPECTED_STATUS_CODE
------------------------------------------------
認証サーバーが返すステータスコードが 200 系ではなかった場合に出力されます。
例えばステータスコードが 400 だと出力されます。
INVALID_AUTH_WEBHOOK_RESPONSE_JSON
-----------------------------------------
認証サーバーが返す JSON に必須で項目が含まれていない場合に出力されます。
例えば ``allowed`` が含まれていない場合に出力されます。
AUTH-WEBHOOK-RESPONSE-BAD-JSON
--------------------------------------
認証サーバーが返す JSON のデコードに失敗した場合に出力されます。
例えば ``{"a: b"}`` といったような JSON と判断できない場合に出力されます。
.. _mermaid-auth-webhook:
シーケンス図
================
.. _mermaid-auth-webhook-accept:
認証成功
----------------
.. mermaid::
sequenceDiagram
autonumber
participant C as クライアント
participant S as Sora
participant A as アプリケーションサーバー
C->>+S: "type": "connect"
S->>+A: 認証ウェブフック
A-->>-S: 200OK
{"allowed": true}
S-->>-C: "type": "offer"
C->>S: "type": "answer"
note over C,A: WebRTC 確立
.. _mermaid-auth-webhook-reject:
認証拒否
----------------
.. mermaid::
sequenceDiagram
autonumber
participant C as クライアント
participant S as Sora
participant A as アプリケーションサーバー
C->>+S: "type": "connect"
S->>+A: 認証ウェブフック
A-->>-S: 200OK
{"allowed": false, "reason": "reject"}
S->>C: WebSocket Close
{"reason": "reject"}