認証ウェブフック¶
概要¶
Sora は認証機能を持っていますが、クライアントからの接続可否を判断する機能は持っていません。 接続可否は外部のアプリケーションサーバーにウェブフックを送信し、その戻り値で判断します。
Sora はシグナリング経由で送られてきた情報や、
そのチャネルに接続している情報を HTTP/1.1 POST で sora.conf の auth_webhook_url に指定された URL へ送信します。
このとき送信する情報は JSON 形式です。
注意¶
シグナリング "type": "connect" 経由で送られてきた情報がそのまま認証ウェブフックのリクエストとして送信されるわけではありません。
ログの出力¶
sora.conf の auth_webhook_url を有効にしない場合でも log/auth_webhook.jsonl は生成されます。
HTTP ヘッダー¶
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
注釈
JSON のパース時の判断などに利用してください。
sora-connection-id¶
認証ウェブフックの HTTP ヘッダー に sora-connection-id というヘッダー名でコネクション ID が入ってきます。
コネクション ID が WCJC78EWK935N7P7Z8FYAKFW9M の場合は sora-connection-id: WCJC78EWK935N7P7Z8FYAKFW9M のように値が入ってきます。
設定¶
auth_webhook_url¶
- デフォルト:
未設定
認証可否の判断に使用する HTTP リクエストの送信先を sora.conf の auth_webhook_url に設定します。
認証ウェブフック機能を使用する場合は指定してください。
HTTP のレスポンスは認証の可否に関わらず、 200 OK 等 200 番台のステータスコードを返す必要があります。
auth_webhook_url = http://127.0.0.1:8080/sora/auth/webhook
auth_webhook_log¶
危険
何か特別な理由がない限り false へ変更しないでください。
- デフォルト:
true
認証ウェブフックがログを出力するかどうかを sora.conf の auth_webhook_log で設定します。
認証ウェブフックが 正常に処理された場合 は
log/auth_webhook.jsonlにログが出力されます認証ウェブフックの 処理が失敗した場合 は
log/auth_webhook_error.jsonlにログが出力されます戻りのステータスコードが 200 番台以外の場合
戻りの JSON に
"allowed"項目が含まれていない場合戻りの JSON が
"allowed": falseで"reason"が含まれていない場合送信先が応答せずタイムアウトになった場合
認証処理時に送信する JSON¶
Sora は、 sora.conf の auth_webhook_url に設定した URL に対して POST リクエスト で次のような JSON を送ります。
{
"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": "[email protected]",
"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": "2024.1.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 }
}
version
Sora のバージョンが
文字列で入ってきます
label
sora.confの 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 を指定します
simulcast_multicodec
simulcastがtrueの場合のみこの値が入ってきますサイマルキャストマルチコーデックを利用するかどうかの値が入ってきます
spotlight
スポットライトでの接続要求を出しているかどうかの値が入ってきます
クライアントが送ってこない場合は
falseが設定されます
spotlight_focus_rid
spotlightがtrueの場合のみこの値が入ってきますスポットライトでフォーカスされた参加者の映像を受信する rid を指定します
spotlight_unfocus_rid
spotlightがtrueの場合のみこの値が入ってきますスポットライトでフォーカスされていない参加者の映像を受信する rid を指定します
spotlight_number
この項目はオプションです
クライアントが送ってこない場合は、この値は含まれません
spotlight_numberをシグナリングの connect 時に送ってきた場合に値が入ります
whip
WHIP を利用したシグナリングを利用するかどうかの値が入ってきます
whep
WHEP を利用したシグナリングを利用するかどうかの値が入ってきます
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が使用されますコーデックの種類は
OPUSのみです
audio_bit_rate
この項目はオプションです
audioがfalseやクライアントが送ってこない場合、含まれませんこの設定は
audio_codec_typeがOPUSの時のみ有効です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の default_video_bit_rate が使用されますデフォルトは 500 です
最小が 1 で、最大が 30000 です
15000 より大きい値は現時点でサポート範囲外です
単位は
kbpsです
video_vp9_params
この項目はオプションです
video_codec_typeがVP9の場合に含まれます配信者が利用するビデオの VP9 の設定がオブジェクトとして入ってきます
詳細は ビデオの VP9 設定指定 も参考にしてください
クライアントが
profile_idの値を送ってこない場合はsora.confの default_vp9_param_profile_id の値が使用されます
video_av1_params
この項目はオプションです
video_codec_typeがAV1の場合に含まれます配信者が利用するビデオの AV1 の設定がオブジェクトとして入ってきます
詳細は ビデオの AV1 設定指定 も参考にしてください
クライアントが
profileの値を送ってこない場合はsora.confの default_av1_param_profile の値が使用されます
video_h264_params
この項目はオプションです
video_codec_typeがH264の場合に含まれます配信者が利用するビデオの H264 の設定がオブジェクトとして入ってきます
詳細は ビデオの H.264 設定指定 も参考にしてください
クライアントが
profile_level_idの値を送ってこない場合はsora.confの default_h264_param_profile_level_id の値が使用されますb_frameはsora.confの h264_b_frame がtrueのときに含まれますクライアントが
b_frameの値を送ってこない場合の値はfalseです
video_h265_params
この項目はオプションです
video_codec_typeがH265の場合に含まれます配信者が利用するビデオの H264 の設定がオブジェクトとして入ってきます
詳細は ビデオの H.264 設定指定 も参考にしてください
クライアントが
level_idの値を送ってこない場合はsora.confの default_h265_param_level_id の値が使用されますb_frameはsora.confの h265_b_frame がtrueのときに含まれますクライアントが
b_frameの値を送ってこない場合の値はfalseです
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
この項目はオプションです
クライアントから送られてきた情報が入ってきます
認証ウェブフックに含まれる同時接続数について¶
重要
認証ウェブフックで送られてくる同時接続数、そのウェブフックが送られたタイミングの値であり、 厳密にそのチャネルの同時接続数を制限する値としては利用できません。
channel_connections
channel_sendrecv_connections
channel_sendonly_connections
channel_recvonly_connections
これら認証ウェブフックに含まれる同時接続数は WebRTC が確立した後に +1 され、WebRTC が切断されたタイミングで -1 されます。 そのため認証タイミングと WebRTC 確立時の時間差が存在します。
さらに、認証ウェブフックは並列で処理されるため、アプリ側でこの同時接続数の値を利用した厳密な同時接続数の制限を行う事はできません。
もし厳密なチャネル単位での同時接続数を制限したい場合は、 イベントウェブフック connection.created を利用して、 アプリ側でデータベースでロックを取ってカウントを行い、ロックを取って数値をチェックして認証を行ってください。
sora_client¶
認証ウェブフックの sora_client にはクライアントから送られてきた情報が入ってきます。
クライアントから情報が送られてこなければ含まれません。 Sora SDK を利用している場合は必ず入ってきます。
"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 番台で返してください。
{
"allowed": true
}
Sora は "allowed" が true の場合は認証を成功と判断して処理をします。
認証成功時の払い出し項目¶
認証成功時に様々な項目を払い出すことができます。
詳細は 認証ウェブフック成功時の払い出し をご確認ください。
認証失敗時のレスポンス JSON¶
認証に失敗した場合は、以下の JSON を返してください。
{
"allowed": false,
"reason": "<String>"
}
注釈
認証失敗の場合も HTTP レスポンスのステータスコードは 200 番台である必要があります
Sora は "allowed" が false で、 "reason" が含まれている場合に認証失敗と判断して処理します。
"reason" は必須です、何かしらエラー理由を 100 バイト以内 の文字列を指定してください。
認証に失敗した場合、認証サーバーから送られてきた "reason" の内容は、
WebSocket シグナリング切断時のメッセージとしてクライアントに送られます。
例¶
認証ウェブフックの戻り値で "reason" に "REJECT" を返した場合、
WebSocket シグナリング切断時のメッセージの "reason" に "REJECT" が含まれます。
認証ウェブフックの戻り値¶
{
"allowed": false,
"reason": "REJECT"
}
WebSocket シグナリング切断時のメッセージ¶
"code"が4490"reason"が"REJECT"
認証ウェブフック成功時の払い出し¶
認証サーバーは認証成功時に様々な値を出すことができます。
{
"allowed": true,
"event_metadata": {
"pk": 1
}
}
詳細は 認証ウェブフック成功時の払い出し をご確認ください。
WebSocket シグナリング時の HTTP ヘッダーを認証ウェブフックにコピーする機能¶
sora.conf の copy_websocket_signaling_header_names を設定することで、
認証ウェブフックの HTTP ヘッダーに WebSocket シグナリング時の HTTP ヘッダーをコピーすることができます。
copy_websocket_signaling_header_names = X-Forwarded-For, X-Real-IP, Tracestate
危険
この機能は指定された WebSocket シグナリング時の HTTP ヘッダーを そのままコピー して認証ウェブフックに送信します。 そのため、指定されたヘッダー名や、実際のヘッダー値に何が含まれていても何も検証は行いません。注意して利用してください。
認証ウェブフックログ¶
sora.conf の auth_webhook_log を true にしている場合は log/auth_webhook.jsonl が出力されます。
重要
auth_webhook_log はデフォルトで true です。
このログには認証ウェブフックのリクエストとレスポンス、ウェブフック URL、タイムスタンプが含まれます。
req
認証ウェブフックの送信リクエストがそのまま入ります
res
認証ウェブフックの戻り値がそのまま入ります
url
auth_webhook_url を指定していない場合はログに含まれません
timestamp
RFC3339 フォーマットのタイムスタンプが入ります
UTC です
マイクロ秒まで含まれています
copy_headers
copy_websocket_signaling_header_names でコピーされた HTTP ヘッダーが入ります
auth_webhook_url あり / レスポンスあり¶
{
"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": "[email protected]",
"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": "2024.1.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 }
},
"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 がありません
{
"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": "[email protected]",
"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": "2024.1.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 }
},
"timestamp": "2020-12-07T06:30:56.252785Z",
"url": "http://127.0.0.1:3001/sora/authn/webhook"
}
auth_webhook_url なし¶
url がありません
{
"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": "[email protected]",
"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": "2024.1.0",
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 }
},
"res": {
"allowed": true
},
"timestamp": "2020-12-07T06:26:58.916242Z"
}
クラスターリレー機能利用時に認証が 2 回行われる場合がある¶
クラスターリレー機能を有効にしている場合、1 クライアントへの認証が 2 回 行われる場合があります。
特定のノードに同時接続素の寄せを発生させるアフィニティ機能は認証成功時の払い出しで有効か無効かを指定できるため、 リレー機能が存在する場合はアフィニティの確認をするために必ず認証を行います。
その後、アフィニティが有効だったり、ライセンス上限に達していた場合で、別ノードへのリダイレクトが行われた場合、 リダイレクト先のノードで再度認証が発生します。
アフィニティが有効で、アフィニティが発生し接続したノードにセッションが存在しない場合¶
クラスター全体のライセンスに余裕があれば、 既にセッションがある別ノードへリダイレクトを行い、再度認証を行います。
アフィニティが有効で、かつ cluster_affinity_threshold の値を超えた場合¶
クラスター全体のライセンスに余裕があれば、 別ノードへリダイレクトを行い、再度認証を行います。
アフィニティ関係なく、接続先ノードのライセンス上限の場合¶
クラスター全体でライセンスの上限に達していない場合、 別ノードへリダイレクトを行い、再度認証を行います。
エラーメッセージ¶
これらエラーメッセージは 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 と判断できない場合に出力されます。
AUTH-WEBHOOK-RESPONSE-EMPTY-BODY¶
認証サーバーがステータスコードが 200 系で空のボディを返した場合に出力されます。
シーケンス図¶
認証成功¶
sequenceDiagram
autonumber
participant C as クライアント
participant S as Sora
participant A as アプリケーションサーバー
C->>+S: "type": "connect"
S->>+A: 認証ウェブフック
A-->>-S: 200OK<br />{"allowed": true}
S-->>-C: "type": "offer"
C->>S: "type": "answer"
note over C,A: WebRTC 確立
認証拒否¶
sequenceDiagram
autonumber
participant C as クライアント
participant S as Sora
participant A as アプリケーションサーバー
C->>+S: "type": "connect"
S->>+A: 認証ウェブフック
A-->>-S: 200OK<br />{"allowed": false, "reason": "REJECT"}
S->>C: WebSocket Close<br/>"code": 4490<br/>"reason": "REJECT"