認証ウェブフック¶
概要¶
Sora 自体はクライアント接続の認証機能を保持しておりません。認証する場合は外部に認証サーバを用意する必要があります。
Sora はシグナリング経由で送られてきた情報や、 そのチャネルに接続している情報を POST リクエストで auth_webhook_url に指定された URL へ送信します。 このとき送信する情報は JSON 形式で送信します。
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 を送ります。
{
"multistream": false,
"version": "2020.1",
"label": "sora-stand-alone",
"role": "sendonly",
"channel_id": "spam",
"client_id": "<Base32-UUIDv4> or <String> or null",
"connection_id": "<Base32-UUIDv4>",
"metadata": {
"access_token": "0AC29F4C526B4074A06AEC7C87EACF32",
"group": "egg",
},
"channel_connections": 6,
"channel_upstream_connections": 1,
"channel_downstream_connections": 5,
"audio": false,
"video": {
"bit_rate": 2000,
"codec_type": "VP8"
}
}
version
Sora のバージョンが
文字列で入ってきます
label
sora.confのlabelで指定した値が入ってきます
multistream
マルチストリームでの接続要求を出しているかどうかの値が入ってきます
true の場合はマルチストリームを希望している接続です
simulcast
サイマルキャストでの接続要求を出しているかどうかの値が入ってきます
true の場合はサイマルキャストを希望している接続です
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 より大きい値は現時点でサポート外です
channel_connections
現在そのチャネルの接続数です
自分は含まれません
channel_upstream_connections
現在そのチャネルで配信をしている配信者の接続数です
自分は含まれません
channel_downstream_connections
現在そのチャネルを視聴している視聴者の接続数です
自分は含まれません
role
以下が入ってきます
sendrecv(送受信)sendonly(送信)recvonly(受信)upstream(配信)今後廃止予定です
downstream(視聴)今後廃止予定です
metadata
この項目はオプションです
ユーザが定義を自由にできる値です
JSON で使用できる形式ならどんな値でも指定可能です
type: connect で metadata が送られてこない場合、アプリ側にも送られません
channel_id
認証対象のクライアントが接続要求を出しているチャネル ID です
client_id
認証対象のクライアントに割り当てられた ID です
sora.confでallow_client_id_assignmentをtrueにした場合に、 シグナリング接続時にクライアントがclient_idを送らない場合、nullが入ってきます
connection_id
Base32-UUIDv4 です
認証対象のコネクションに割り当てられたユニークな ID です
認証成功時のレスポンス 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
bit_rate を指定しないことも可能です
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
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 という値を認証サーバから返すことができます。
{
"allowed": true,
"metadata": {"spam": "egg"},
"event_metadata": {"pk": 1}
}
認証サーバが認証成功時に event_metadata を含めた場合、イベントウェブフック通知時に event_metadata という項目が追加されます。
この機能を使用することで、イベント通知時に送られてくる event_metadata の値を認証サーバが自由に指定できます。
使用例¶
この 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 の URL を指定することができるようになります。
turn_tls_fqdn の 指定¶
Sora は、認証成功時のタイミングで接続単位での turn_tls_fqdn の値を認証サーバから指定することが可能です。
{
"allowed": true,
"turn_tls_fqdn": "sora-turns.example.com"
}
この値は sora.conf の turn_tls_fqdn の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。
この機能を使用することでクライアント毎に使用する TURN の URL を指定することができるようになります。
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 の値を上書きします。
この機能を使用することでクライアント毎に、 turn_tcp_only や turn_tls_only の設定を指定可能です。
simulcast / simulcast_quality の指定¶
Sora は、認証成功時のタイミングで接続単位での simulcast と simulcast_quality の値を認証サーバから指定することが可能です。
{
"allowed": true,
"simulcast": true
}
{
"allowed": true,
"simulcast": true,
"simulcast_quality": "low"
}
remote_stats の指定¶
Sora は、認証成功時のタイミングで接続単位での remote_stats の値を認証サーバから指定することが可能です。
{
"allowed": true,
"remote_stats": true
}
この値は sora.conf の remote_stats の値を上書きします。