認証ウェブフック

概要

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

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

auth_webhook_url

デフォルト:未設定

クライアントの認証可否を判断するための URL を指定します。認証ウェブフック機能を使用する場合は指定してください。

この URL には HTTPS の URL を指定することも可能です。

HTTPS の URL を指定する場合は、通知先のアプリケーションには正規の認証局から発行された証明書を使用してください。

自己署名証明書等の正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。

Sora は戻り値の JSON で認証可否を判断します。

設定

認証可否の判断に使用する HTTP リクエストの送信先を sys.config の auth_webhook_url に設定します。

{sora, [
        ...

        {auth_webhook_url, "http://127.0.0.1:8080/sora/auth/webhook"},

        ...
       ]},

認証処理時に送信する JSON

Sora は、sys.config の auth_webhook_url に設定した URL に対して POST リクエストで次のような JSON を送ります。

{
    "multistream": false,
    "version": "17.04.0",
    "label": "sora-stand-alone",
    "role": "upstream",
    "channel_id": "spam",
    "client_id": "<UUID>",
    "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
    • sys.config の label で指定した値が入ってきます
  • multistream
    • マルチストリームでの接続要求を出しているかどうかの値が入ってきます
    • true の場合はマルチストリームを希望している接続です
  • audio
    • false の場合は audio を使用しません
    • コーデックやビットレートが入ってくる場合は {"codec_type": "OPUS", "bit_rate": 32} が入ってきます
    • コーデックの種類は OPUS または PCMU です
    • ビットレートはクライアントが送ってこない場合は含まれません
      • もし default_audio_bit_rate に値を指定していた場合はその値が利用されます
      • 最小が 6 で、最大が 510 です
  • video
    • false の場合は video を使用しません
    • コーデックやビットレートが入ってくる場合は {"codec_type": "VP9", "bit_rate": 100} が入ってきます
    • コーデックの種類は VP8、VP9、H264 の 3 種類です
    • ビットレートはクライアントが送ってこない場合は sys.config の default_video_bit_rate が使用されます
      • デフォルトは 500 です
      • 最小が 1 で、最大が 5000 です
  • channel_connections
    • 現在そのチャネルに接続しているクライアントの接続数です
    • 自分は含まれません
  • channel_upstream_connections
    • 現在そのチャネルで配信をしている配信者の接続数です
    • 自分は含まれません
  • channel_downstream_connections
    • 現在そのチャネルを視聴している視聴者の接続数です
    • 自分は含まれません
  • role
    • upstream (配信) か downstream (視聴) です
  • metadata
    • この項目はオプションです
    • ユーザが定義を自由にできる値です
    • JSON で使用できる形式ならどんな値でも指定可能です
    • type: connect で metadata が送られてこない場合、アプリ側にも送られません
  • channel_id
    • 認証対象のクライアントが接続要求を出しているチャネル ID です
  • client_id
    • 認証対象のクライアントに割り当てられたユニークな 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
    }
}

指定可能な値

  • audio
    • codec_type
      • "OPUS"
      • "PCMU"
      • codec_type を指定しないことも可能です
    • bit_rate
      • 6 ~ 510
      • bit_rate を指定しないことも可能です
  • video
    • codec_type
      • "VP8"
      • "VP9"
      • "H264"
      • codec_type を指定しないことも可能です
    • bit_rate
      • 1 ~ 5000
      • bit_rate を指定しないことも可能です

metadata の払い出し

Sora は、認証成功時のタイミングで metadata という値を認証サーバから返すことができます。

{
    "allowed": true,
    "metadata": {"spam": "egg"}
}

認証サーバが認証成功時に metadata を含めた場合、クライアントへ metadata をそのまま送ります。

この機能を使うことで、認証成功のタイミングでユーザ毎に任意の値を送ることができます。

認証成功時にクライアントが受け取る JSON

認証成功の場合は Offer 送信時の JSON に metadata が含められます。

{
    "type": "offer",
    "sdp": "<SDP>",
    "metadata": {"spam": "egg"}
}

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" をご確認ください

ipv4_address と ipv6_address の払い出し

Sora は、認証成功時のタイミングで ipv4_address または ipv6_address を認証サーバから返すことができます。 ipv4_addressipv6_address は片方だけでも、両方返しても問題ありません。

{
    "allowed": true,
    "ipv4_address": "192.0.2.10",
    "ipv6_address": "2001:0DB8::10"
}

この値は SDP の offer 時の a=candidate と TURN-UDP と TURN-TCP の URL の払い出しに使用されます。

sys.config の値はこの戻り値で上書きされます。指定する IP アドレスを間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでクライアント毎に経路を指定することができます。

turn_fqdn 払い出し

Sora は、認証成功時のタイミングで turn_fqdn を認証サーバから返すことができます。

{
    "allowed": true,
    "turn_fqdn": "sora.example.com"
}

この値は sys.config の turn_fqdn の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでクライアント毎に使用する TURN の URL を指定することができるようになります。

turn_tls_fqdn 払い出し

Sora は、認証成功時のタイミングで turn_tls_fqdn を認証サーバから返すことができます。

{
    "allowed": true,
    "turn_tls_fqdn": "sora-turns.example.com"
}

この値は sys.config の turn_tls_fqdn の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでクライアント毎に使用する TURN の URL を指定することができるようになります。