認証ウェブフック¶

概要¶

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_id": "sora",
  "channel_recvonly_connections": 0,
  "channel_sendonly_connections": 0,
  "channel_sendrecv_connections": 0,
  "connection_id": "VSMDDJG3ZH1RHB93W260APVEQW",
  "data_channel_signaling": true,
  "e2ee": false,
  "ignore_disconnect_websocket": false,
  "label": "WebRTC SFU Sora",
  "multistream": true,
  "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 で指定した値が入ってきます
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 (受信)
metadata
- この項目はオプションです
- ユーザが定義を自由にできる値です
- JSON で使用できる形式ならどんな値でも指定可能です
- "type": "connect" で metadata が送られてこない場合、アプリ側にも送られません
authn_metadata
- この項目は metadata と同じです
- metadata のシンタックスシュガーです
- "type": "connect" で metadata が送られてこない場合、アプリ側にも送られません
channel_id
- 認証対象のクライアントが接続要求を出しているチャネル ID です
client_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 の切断を無視するかどうか
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"
  - sora.conf にて av1 を true にしている必要があります
- "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 の長さの文字列

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>",
}

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 の値を上書きします。