認証ウェブフック¶
概要¶
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 リクエストの送信先を 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_downstream_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"channel_upstream_connections": 0,
"client_id": "WW6K6A9QYS1FV32N27SX6RRNY4",
"connection_id": "WW6K6A9QYS1FV32N27SX6RRNY4",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"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.67 Safari/537.36",
"raw": "Sora JavaScript SDK 2020.5.0",
"type": "Sora JavaScript SDK",
"version": "2020.5.0"
},
"spotlight": false,
"timestamp": "2020-12-02T04:49:29.949313Z",
"version": "2020.3",
"video": {
"bit_rate": 1000,
"codec_type": "VP9"
}
}
version
Sora のバージョンが
文字列
で入ってきます
label
sora.conf
のlabel
で指定した値が入ってきます
timestamp
ウェブフック通知時のタイムスタンプが RFC3339 フォーマットで入ってきます
マイクロ秒まで含まれています
e2ee
クライアントが E2EE を有効にしているかどうかが入ってきます
true の場合は E2EE を利用する接続です
multistream
マルチストリームでの接続要求を出しているかどうかの値が入ってきます
true の場合はマルチストリームを希望している接続です
simulcast
サイマルキャストでの接続要求を出しているかどうかの値が入ってきます
true の場合はサイマルキャストを希望している接続です
spotlight
スポットライトでの接続要求を出しているかどうかの値が入ってきます
sora.conf
でspotlight_legacy = false
に設定していた場合に値が入ってきます
spotlight_number
sora.conf
でspotlight_legacy = false
に設定しており、さらにspotlight_number
をシグナリングの connect 時に送ってきた場合に値が入ります
spotlight_legacy
スポットライトレガシーでの接続要求を出しているかどうかの値が入ってきます
sora.conf
でspotlight_legacy = true
に設定していた場合に値が入ってきます
spotlight_legacy_number
sora.conf
でspotlight_legacy = true
に設定しており、さらに{"spotlight": 3}
をシグナリングの connect 時に送ってきた場合に値が入ります
role
以下が入ってきます
sendrecv
(送受信)sendonly
(送信)recvonly
(受信)upstream
(配信)2021 年 6 月リリース予定の Sora で廃止予定です
downstream
(視聴)2021 年 6 月リリース予定の Sora で廃止予定です
metadata
この項目はオプションです
ユーザが定義を自由にできる値です
JSON で使用できる形式ならどんな値でも指定可能です
type: connect
でmetadata
が送られてこない場合、アプリ側にも送られません
authn_metadata
この項目は metadata と同じです
metadata のシンタックスシュガーです
type: connect
でmetadata
が送られてこない場合、アプリ側にも送られません
channel_id
認証対象のクライアントが接続要求を出しているチャネル ID です
client_id
認証対象のクライアントに割り当てられた ID です
sora.conf
でallow_client_id_assignment
をtrue
にした場合に、type: connect
でclient_id
が送られてこない場合、アプリ側にも送られません
connection_id
Base32-UUIDv4 です
認証対象のコネクションに割り当てられたユニークな ID です
channel_connections
現在そのチャネルの接続数です
自分は含まれません
channel_sendrecv_connections
現在そのチャネルで送受信をしている配信者の接続数です
自分は含まれません
channel_sendonly_connections
現在そのチャネルで送信のみをしている配信者の接続数です
自分は含まれません
channel_recvonly_connections
現在そのチャネルの配信を受信のみしている視聴者の接続数です
自分は含まれません
channel_upstream_connections
現在そのチャネルで配信をしている配信者の接続数です
自分は含まれません
2021 年 6 月リリースの Sora にて廃止されます
channel_downstream_connections
現在そのチャネルを視聴している視聴者の接続数です
自分は含まれません
2021 年 6 月リリースの Sora にて廃止されます
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 です
認証成功時のレスポンス 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"
sora.conf
にてav1 = true
にしている必要があります
"H264"
"H265"
sora.conf
にてh265 = true
にしている必要があります
codec_type を指定しないことも可能です
bit_rate
1 ~ 30000
単位は kbps です
bit_rate を指定しないことも可能です
client_id の払い出し¶
sora.conf
の allow_client_id_assignment
を true
にすることで、
Sora は認証成功時の戻り値に client_id
を認証サーバから返すことができます。
allow_client_id_assignment
を true
した状態で、
シグナリング接続時にも、 認証成功時の戻り値にも client_id
を指定しない場合は connection_id
と同じ値が client_id
に割りあてられます。
{
"allowed": true,
"client_id": "spam"
}
client_id
1 から 255 の長さの文字列
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.example.com"
}
この値は sora.conf
の turn_fqdn
の値を上書きします。
指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。
turn_tls_fqdn の 払い出し¶
Sora は、認証成功時のタイミングで接続単位での turn_tls_fqdn
の値を認証サーバから払い出すことが可能です。
{
"allowed": true,
"turn_tls_fqdn": "sora-turns.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
}
スポットライトレガシー¶
スポットライトレガシーの場合も、認証成功時のタイミングで接続単位での spotlight
と spotlight_number
の値を認証サーバから払い出すことが可能です。
{
"allowed": true,
"spotlight": true
}
{
"allowed": true,
"spotlight": true,
"spotlight_number": 3
}
remote_stats の払い出し¶
Sora は、認証成功時のタイミングで接続単位での remote_stats
の値を認証サーバから払い出すことが可能です。
{
"allowed": true,
"remote_stats": true
}
この値は sora.conf の remote_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_downstream_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"channel_upstream_connections": 0,
"connection_id": "F2SMT1W59S5ADDZ84CMQ8CDBX4",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"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_downstream_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"channel_upstream_connections": 0,
"connection_id": "0FBC8HF84544ZDHYYN9BCRNZG8",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"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_downstream_connections": 0,
"channel_id": "sora",
"channel_recvonly_connections": 0,
"channel_sendonly_connections": 0,
"channel_sendrecv_connections": 0,
"channel_upstream_connections": 0,
"client_id": "K8PCW533MN1WK24YNZ83HDP74C",
"connection_id": "K8PCW533MN1WK24YNZ83HDP74C",
"e2ee": false,
"label": "WebRTC SFU Sora",
"multistream": true,
"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"
}