認証ウェブフック

概要

Sora 自体はクライアントの接続を認証する機能を持っていません。認証する場合は外部に認証サーバーを用意する必要があります。

Sora はシグナリング経由で送られてきた情報や、 そのチャネルに接続している情報を POST リクエストで sora.confauth_webhook_url に指定された URL へ送信します。 このとき送信する情報は JSON 形式です。

注意

シグナリング "type": "connect" 経由で送られてきた情報がそのまま認証ウェブフックのリクエストとして送信されるわけではありません。

ログの出力

sora.confauth_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.confauth_webhook_url に設定します。 認証ウェブフック機能を使用する場合は指定してください。

HTTP のレスポンスは認証の可否に関わらず、 200 OK 等 200 番台のステータスコードを返す必要があります。

auth_webhook_url = http://127.0.0.1:8080/sora/auth/webhook

認証処理時に送信する JSON

Sora は、 sora.confauth_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": "2023.2.0",
  "video": true,
  "video_bit_rate": 1000,
  "video_codec_type": "VP9"
}
  • version

    • Sora のバージョンが 文字列 で入ってきます

  • label

    • sora.conflabel で指定した値が入ってきます

  • node_name

    • Sora のノード名が入ってきます

  • timestamp

    • ウェブフックリクエスト送信時のタイムスタンプが RFC3339 フォーマットで入ってきます

    • マイクロ秒まで含まれています

  • id

    • Base32-UUIDv4 です

    • ウェブフック毎に割り当てられるユニークな値です

  • e2ee

    • クライアントが E2EE を有効にしているかどうかが入ってきます

    • true の場合は E2EE を利用する接続です

  • multistream

    • マルチストリームでの接続要求を出しているかどうかの値が入ってきます

    • クライアントが送ってこない場合は true が設定されます

    • true の場合はマルチストリームを希望している接続です

  • simulcast

    • サイマルキャストでの接続要求を出しているかどうかの値が入ってきます

    • true の場合はサイマルキャストを希望している接続です

    • クライアントが送ってこない場合は false が設定されます

  • simulcast_rid

    • simulcasttrue かつ spotlightfalse の場合のみこの値が入ってきます

    • サイマルキャストでの受け取る rid を指定します

  • spotlight

    • スポットライトでの接続要求を出しているかどうかの値が入ってきます

    • クライアントが送ってこない場合は false が設定されます

  • spotlight_focus_rid

    • spotlighttrue の場合のみこの値が入ってきます

    • スポットライトでフォーカスされた参加者の映像を受信する rid を指定します

  • spotlight_unfocus_rid

    • spotlighttrue の場合のみこの値が入ってきます

    • スポットライトでフォーカスされていない参加者の映像を受信する rid を指定します

  • 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

    • true または false が入ってきます

    • false の場合は audio を使用しません

  • audio_codec_type

    • この項目はオプションです

    • audiofalse の場合は含まれません

    • コーデックの種類は OPUS または LYRA です

  • audio_bit_rate

    • この項目はオプションです

    • audiofalse やクライアントが送ってこない場合、含まれません

    • この設定は audio_codec_typeOPUS の時のみ有効です

    • default_audio_bit_rate に値を指定していた場合はその値が利用されます

    • 最小が 6 で、最大が 510 です

    • 単位は kbps です

  • video

    • true または false が入ってきます

    • false の場合は video を使用しません

  • video_codec_type

    • この項目はオプションです

    • videofalse の場合は含まれません

    • コーデックはクライアントが送ってこない場合はデフォルトで VP9 が使用されます

    • コーデックの種類は VP8VP9AV1H264H265 です

  • video_bit_rate

    • この項目はオプションです

    • videofalse の場合は含まれません

    • ビットレートはクライアントが送ってこない場合は sora.confdefault_video_bit_rate が使用されます

    • デフォルトは 500 です

    • 最小が 1 で、最大が 30000 です

    • 15000 より大きい値は現時点でサポート範囲外です

    • 単位は kbps です

  • 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" の内容は文字列としてクライアントに送られます。

"<認証サーバーから送られてきた reason>"

認証ウェブフック成功時の払い出し

認証サーバーは認証成功時に様々な値を出すことができます。

{
    "allowed": true,
    "event_metadata": {
      "pk": 1
    }
}

詳細は 認証ウェブフック成功時の払い出し をご確認ください。

認証ウェブフックログ

sora.confauth_webhook_logtrue にしている場合は log/auth_webhook.jsonl が出力されます。

重要

auth_webhook_log はデフォルトで true です。

このログには認証ウェブフックのリクエストとレスポンス、ウェブフック URL、タイムスタンプが含まれます。

  • req

    • 認証ウェブフックの送信リクエストがそのまま入ります

  • res

    • 認証ウェブフックの戻り値がそのまま入ります

  • url

    • auth_webhook_url を指定していない場合はログに含まれません

  • timestamp

    • RFC3339 フォーマットのタイムスタンプが入ります

    • UTC です

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": "2023.2.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_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": 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": "2023.2.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_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": 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": "2023.2.0",
    "video": true,
    "video_bit_rate": 1000,
    "video_codec_type": "VP9"
  },
  "res": {
    "allowed": true
  },
  "timestamp": "2020-12-07T06:26:58.916242Z"
}

エラーメッセージ

これらエラーメッセージは 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 と判断できない場合に出力されます。

シーケンス図

認証成功

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 />{"reason": "reject"}
© Copyright 2024, Shiguredo Inc Created using Sphinx 7.2.6