認証ウェブフック¶
概要¶
Sora 自体はクライアントの接続を認証する機能を持っていません。認証する場合は外部に認証サーバーを用意する必要があります。
Sora はシグナリング経由で送られてきた情報や、
そのチャネルに接続している情報を POST リクエストで sora.conf
の auth_webhook_url に指定された URL へ送信します。
このとき送信する情報は JSON 形式です。
注意¶
シグナリング "type": "connect"
経由で送られてきた情報がそのまま認証ウェブフック通知として送られるわけではありません。
ウェブフック通知先のサーバーがベーシック認証を利用している場合¶
もしウェブフック通知先のサーバーがベーシック認証を利用している場合は、
sora.conf
にて webhook_basic_authn を true
に設定することでベーシック認証を利用可能です。
webhook_basic_authn_user_id と webhook_basic_authn_password に利用するユーザー ID とパスワードを設定して下さい。
ウェブフック通知先のサーバーが自己署名証明書などを利用している場合¶
この設定はおすすめしません
デフォルトでは自己署名証明書などの正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。
もし自己署名証明書を利用したサーバーがウェブフックの通知先になる場合は、
sora.conf
にて webhook_insecure を true
に設定することで証明書のチェックを行わないようになります。
auth_webhook_url¶
- デフォルト:
未設定
クライアントの認証可否を判断するための URL を指定します。認証ウェブフック機能を使用する場合は指定してください。
この URL には HTTPS の URL を指定することも可能です。
HTTPS の URL を指定する場合は、通知先のアプリケーションには正規の認証局から発行された証明書を利用してください。
Sora は戻り値の JSON で認証可否を判断します。
HTTP のレスポンスは 200 OK 等の 2xx ステータスコードの必要があります。
設定¶
認証可否の判断に使用する HTTP リクエストの送信先を sora.conf
の auth_webhook_url に設定します。
auth_webhook_url = http://127.0.0.1:8080/sora/auth/webhook
認証処理時に送信する JSON¶
Sora は、 sora.conf
の auth_webhook_url に設定した URL に対して POST リクエスト で次のような JSON を送ります。
{
"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/91.0.4472.77 Safari/537.36",
"raw": "Sora JavaScript SDK 2021.1.0",
"type": "Sora JavaScript SDK",
"version": "2021.1.0"
},
"spotlight": false,
"timestamp": "2021-06-08T07:51:32.593704Z",
"version": "2021.1",
"video": {
"bit_rate": 1000,
"codec_type": "VP9"
}
}
version
Sora のバージョンが
文字列
で入ってきます
label
sora.conf
の label で指定した値が入ってきます
node_name
Sora のノード名が入ってきます
timestamp
ウェブフック通知時のタイムスタンプが RFC3339 フォーマットで入ってきます
マイクロ秒まで含まれています
e2ee
クライアントが E2EE を有効にしているかどうかが入ってきます
true の場合は E2EE を利用する接続です
multistream
マルチストリームでの接続要求を出しているかどうかの値が入ってきます
true の場合はマルチストリームを希望している接続です
simulcast
サイマルキャストでの接続要求を出しているかどうかの値が入ってきます
true の場合はサイマルキャストを希望している接続です
simulcast_rid
サイマルキャストでの受け取る rid を指定します
spotlight
スポットライトでの接続要求を出しているかどうかの値が入ってきます
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
false
の場合はaudio
を使用しませんコーデックやビットレートが入ってくる場合は
{"codec_type": "OPUS", "bit_rate": 32}
が入ってきますコーデックの種類は
OPUS
ですビットレートはクライアントが送ってこない場合は含まれません
もし
default_audio_bit_rate
に値を指定していた場合はその値が利用されます最小が 6 で、最大が 510 です
video
false
の場合はvideo
を使用しませんコーデックやビットレートが入ってくる場合は
{"codec_type": "VP9", "bit_rate": 500}
が入ってきますコーデックの種類は VP8、VP9、H264 の 3 種類です
ビットレートはクライアントが送ってこない場合は
sora.conf
の default_video_bit_rate が使用されますデフォルトは 500 です
最小が 1 で、最大が 30000 です
15000 より大きい値は現時点でサポート範囲外です
単位は kbps です
data_channel_signaling
シグナリングの DataChannel 切り替えをするかどうか
ignore_disconnect_websocket
シグナリングの DataChannel 切り替え時に WebSocket の切断を無視するかどうか
data_channels
DataChannel を利用したメッセージングの定義が入ってきます
sora_client
オプションです
クライアントから送られてきた情報が入ってきます
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": "2021.1.0"
},
type
オプションです
クライアントから送られてきた Sora SDK またはクライアントのタイプが入ってきます
raw
オプションです
クライアントから送られてきた sora_client の値がそのまま入ってきます
version
オプションです
クライアントから送られてきた Sora SDK またはクライアントのバージョンが入ってきます
commit_short
オプションです
クライアントから送られてきた Sora SDK のコミットハッシュが入ってきます
environment
オプションです
クライアントから送られてきた端末情報が入ってきます
libwebrtc
オプション
クライアントから送られてきた libwebrtc のバージョン情報が入ってきます
認証成功時のレスポンス JSON¶
認証に成功した場合は、以下の JSON を返してください。
{
"allowed": true
}
Sora は "allowed" が true の場合は認証を成功と判断して処理をします。
認証失敗時のレスポンス JSON¶
認証に失敗した場合は、以下の JSON を返してください。
{
"allowed": false,
"reason": "<String>"
}
Sora は "allowed" が false で、 "reason" が含まれている場合に認証失敗と判断して処理します。
"reason" は必須です、何かしらエラー理由を 100 バイト以内 の文字列にて追加してください。
認証に失敗した場合、認証サーバーから送られてきた "reason" の内容は文字列としてクライアントに送られます。
"<認証サーバーから送られてきた reason>"
audio と video パラメータの上書き¶
この機能はクライアントが指定してきたコーデックやビットレートなどのパラメータに対して、 認証サーバー側でパラメータの上書きを行える機能です。
クライアントが指定してきた値を上書きすることができるため、 サーバー側でそれぞれのクライアントに対して、コーデックやビットレートをコントロールすることができます。
この機能を使用する場合は、認証成功時のレスポンス JSON に audio や video を指定してください。
ここで使用できるのはシグナリングの "type": "connect"
時に指定可能な audio と video の値です。
{
"allowed": true,
"audio": {
"codec_type": "OPUS",
"bit_rate": 64
},
"video": {
"codec_type": "VP9",
"bit_rate": 800
}
}
{
"allowed": true,
"audio": false,
"video": true
}
指定可能な値¶
audio¶
true または false または object が指定可能です
codec_type
"OPUS"
codec_type を指定しないことも可能です
bit_rate
6 ~ 510
単位は kbps です
デフォルトで最適なビットレートが選択されるようになっているため指定する必要はありません
video¶
true または false または object が指定可能です
codec_type
文字列で指定可能です
"VP8"
"VP9"
"AV1"
"H264"
"H265"
sora.conf
にて h265 をtrue
にしている必要があります
codec_type を指定しないことも可能です
bit_rate
1 ~ 30000
単位は kbps です
bit_rate を指定しないことも可能です
client_id の払い出し¶
Sora は認証成功時の戻り値に client_id
を認証サーバーから返すことができます。
シグナリング接続時にも、 認証成功時の戻り値にも client_id
を指定しない場合は connection_id
と同じ値が client_id
に割りあてられます。
{
"allowed": true,
"client_id": "spam"
}
client_id
1 から 255 の長さの文字列
bundle_id の払い出し¶
Sora は認証成功時の戻り値に bundle_id
を認証サーバーから返すことができます。
bundle_id
を指定した場合、マルチストリーム利用時に bundle_id
の値が同じ接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。
シグナリング接続時にも、 認証成功時の戻り値にも bundle_id
を指定しない場合は connection_id
と同じ値が bundle_id
に割りあてられます。
{
"allowed": true,
"bundle_id": "spam"
}
bundle_id
1 から 255 バイトの文字列
data_channel_signaling の払い出し¶
Sora は、認証成功時のタイミングで接続単位での data_channel_signaling
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"data_channel_signaling": true
}
この値は "type": "connect"
の data_channel_signaling
や sora.conf
の default_data_channel_signaling の値を上書きします。
認証成功時にクライアントが受け取る JSON¶
{
"type": "offer",
"sdp": "<SDP>",
"data_channel_signaling": true,
"ignore_disconnect_websocket": false
}
ignore_disconnect_websocket の払い出し¶
Sora は、認証成功時のタイミングで接続単位での ignore_disconnect_websocket
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"ignore_disconnect_websocket": true
}
この値は "type": "connect"
の ignore_disconnect_websocket
や sora.conf
の default_ignore_disconnect_websocket の値を上書きします。
ただし data_channel_signaling
が true
の時のみ、この値は有効になります。
認証成功時にクライアントが受け取る JSON¶
data_channel_signaling が有効な場合、 "type": "switched"
が送られる際に ignore_disconnect_websocket
も送られます。
{
"type": "switched",
"ignore_disconnect_websocket": "<bool>",
}
data_channels の払い出し¶
Sora は、認証成功時のタイミングで接続単位での data_channels
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"data_channels": [
{
"label": "#spam",
"max_packet_life_time": 5000,
"ordered": true,
"protocol": "efg",
"compress": false,
"direction": "sendonly"
},
{
"label": "#egg",
"max_retransmits": 0,
"ordered": false,
"protocol": "abc",
"compress": false,
"direction": "recvonly"
}
]
}
data_channels
の詳細仕様は data_channels 仕様 をご確認ください。
metadata の払い出し¶
Sora は、認証成功時のタイミングで metadata
という値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"metadata": {"spam": "egg"}
}
認証サーバーが認証成功時に metadata
を含めた場合、クライアントへ metadata
をそのまま送ります。
この機能を使うことで、認証成功のタイミングでユーザー毎に任意の値を送ることができます。
認証成功時にクライアントが受け取る JSON¶
認証成功の場合は Offer 送信時の JSON に metadata が含められます。
{
"type": "offer",
"sdp": "<SDP>",
"metadata": {"spam": "egg"}
}
event_metadata の払い出し¶
event_metadata はクライアントには送られません
Sora は、認証成功時のタイミングで event_metadata
という値を認証サーバーから払い出すことが可能です。
認証サーバーが認証成功時に event_metadata
を含めた場合、
イベントウェブフック通知時に event_metadata
という項目が追加されます。
{
"allowed": true,
"metadata": {"spam": "egg"},
"event_metadata": {"pk": 1}
}
event_metadata
はクライアントに知られることのない値です。
Sora イベントウェブフック通知先のサーバーのみが知り得る値となります。
使用例¶
この event_metadata
の値は、クライアントに知られることはありません。そのためユーザー ID を直接入れておくという仕組みも使用できます。
こうすることで通知の際、サーバー側がユーザーの判定をしやすくなります。
シグナリング経由での通知機能の払い出し¶
Sora は、認証成功時のタイミングで signaling_notify
という値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"signaling_notify": true
}
signaling_notify
の値を返すことで、クライアント毎にシグナリング通知を受け取るかどうかを指定可能になります。
シグナリング経由での通知機能の詳細は "type": "notify" をご確認ください
シグナリング経由での通知機能を利用したメタデータの払い出し¶
Sora は、認証成功時のタイミングで signaling_notify_metadata
という値を認証サーバーから払い出すことが可能です。
ここに値を指定することで、参加時や離脱時に外の参加者に情報を通知することができます。
{
"allowed": true,
"signaling_notify_metadata": {
"username": "spam"
}
}
詳細は signaling_notify_metadata をご確認ください。
ipv4_address と ipv6_address の払い出し¶
Sora は、認証成功時のタイミングで ipv4_address
または ipv6_address
を認証サーバーから払い出すことが可能です。
ipv4_address
と ipv6_address
は片方だけでも、両方返しても問題ありません。
{
"allowed": true,
"ipv4_address": "192.0.2.10",
"ipv6_address": "2001:0DB8::10"
}
この値は SDP の offer 時の a=candidate と TURN-UDP と TURN-TCP の URL の払い出しに使用されます。
sora.conf
の値はこの戻り値で上書きされます。指定する IP アドレスを間違えると繋がらなくなるため、使用には注意してください。
この機能を使用することでクライアント毎に経路を指定することができます。
turn_fqdn 払い出し¶
Sora は、認証成功時のタイミングで接続単位での turn_fqdn
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"turn_fqdn": "sora-turn.example.com"
}
この値は sora.conf
の turn_fqdn の値を上書きします。
指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。
turn_tls_fqdn の 払い出し¶
Sora は、認証成功時のタイミングで接続単位での turn_tls_fqdn
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"turn_tls_fqdn": "sora-turn.example.com"
}
この値は sora.conf の turn_tls_fqdn
の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。
この機能は sora.conf
の turn_tls_fqdn の値を上書きします。
turn_tcp_only / turn_tls_only の払い出し¶
Sora は、認証成功時のタイミングで接続単位での turn_tcp_only
または turn_tls_only
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"turn_tcp_only": true
}
{
"allowed": true,
"turn_tls_only": true
}
この値は sora.conf
の turn_tcp_only や turn_tls_only の値を上書きします。
simulcast / simulcast_rid の払い出し¶
Sora は、認証成功時のタイミングで接続単位での simulcast
と simulcast_rid
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"simulcast": true
}
{
"allowed": true,
"simulcast": true,
"simulcast_rid": "r0"
}
この値は sora.conf
の default_simulcast_rid
の値を上書きします。
simulcast_encodings の払い出し¶
Sora は、認証成功時のタイミングで接続単位での simulcast_encodings
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"simulcast_encodings": [
{"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 1.0},
{"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 10.0},
{"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
]
}
詳細については サイマルキャスト の 映像のエンコーディングパラメータのカスタマイズ をご確認ください。
spotlight_encodings の払い出し¶
Sora は、認証成功時のタイミングで接続単位での spotlight_encodings
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"spotlight_encodings": [
{"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 1.0},
{"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
{"rid": "r2", "active": false}
]
}
詳細については サイマルキャスト の 映像のエンコーディングパラメータのカスタマイズ をご確認ください。
spotlight / spotlight_number の払い出し¶
Sora は、認証成功時のタイミングで接続単位での spotlight
と spotlight_number
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"spotlight": true
}
{
"allowed": true,
"spotlight": true,
"spotlight_number": 3
}
user_agent_stats の払い出し¶
Sora は、認証成功時のタイミングで接続単位での user_agent_stats
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"user_agent_stats": true
}
この値は sora.conf
の user_agent_stats の値を上書きします。
h264_profile_level_id の払い出し¶
Sora は、認証成功時のタイミングで接続単位での h264_profile_level_id
の値を認証サーバーから払い出すことが可能です。
{
"allowed": true,
"h264_profile_level_id": "42e01f"
}
この値は sora.conf
の default_h264_profile_level_id の値を上書きします。
認証ウェブフックログ¶
sora.conf
の auth_webhook_log を true
にしている場合は log/auth_webhook.log
が出力されます。
重要
auth_webhook_log
はデフォルトで true
です。
このログには認証ウェブフックのリクエストとレスポンス、ウェブフック URL、タイムスタンプが含まれます。
req
通知した認証ウェブフックがそのまま入ります
res
認証ウェブフックの戻り値がそのまま入ります
url
auth_webhook_url を指定していない場合はログに含まれません
timestamp
RFC3339 フォーマットのタイムスタンプが入ります
UTC です
auth_webhook_url あり / レスポンスあり¶
{
"req": {
"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": "2020.5.0"
},
"spotlight": false,
"timestamp": "2020-12-07T09:16:54.079650Z",
"version": "2020.3",
"video": {
"bit_rate": 1000,
"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 がありません
{
"req": {
"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": "2020.5.0"
},
"spotlight": false,
"timestamp": "2020-12-07T06:30:56.240917Z",
"version": "2020.3",
"video": {
"bit_rate": 1000,
"codec_type": "VP9"
}
},
"timestamp": "2020-12-07T06:30:56.252785Z",
"url": "http://127.0.0.1:3001/sora/authn/webhook"
}
auth_webhook_url なし¶
url がありません
{
"req": {
"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": "2020.5.0"
},
"spotlight": false,
"timestamp": "2020-12-07T06:26:58.916204Z",
"version": "2020.3",
"video": {
"bit_rate": 1000,
"codec_type": "VP9"
}
},
"res": {
"allowed": true
},
"timestamp": "2020-12-07T06:26:58.916242Z"
}