HTTP認可

EMQXはHTTPアプリケーションに基づく認可をサポートしています。このシナリオでは、ユーザーは外部のHTTPアプリケーションをデータソースとして設定し、EMQXはHTTPサービスにリクエストを送信し、HTTP APIから返されたデータに基づいて認可結果を判定することで、複雑な認可ロジックを実現します。

注意

HTTP認可はEMQXサーバレスのデプロイメントではサポートされていません。

HTTP認可の仕組み

認可プロセスはHTTP APIコールに似ており、EMQXはリクエストクライアントとして「API」の要件に従ってHTTPサービスへリクエストを構築・送信します。HTTPサービスは「クライアント」の要件に従って結果を返す必要があります：

• レスポンスのcontent-typeはapplication/jsonである必要があります。
• 認可結果はボディ内のresultで示され、値はallowまたはdenyのいずれかです。
• HTTPステータスコードが204の場合、認可結果はパブリッシュまたはサブスクライブを許可とみなされます。
• HTTPステータスコードが200であっても、レスポンスボディが期待された形式でない場合（例えば、resultフィールドが存在しない、または値がallowでもdenyでもない場合）、認可結果は無視（ignore）として扱われます。ホワイトリストモードが有効でない場合、クライアントは任意のトピックに対してパブリッシュおよびサブスクライブが許可され、不正アクセスやデータ漏洩のリスクがあります。
• 200および204以外のHTTPステータスコードはすべてignoreとみなされます。例えば、HTTPサービスが利用不可の場合や認証エンドポイントが予期しないレスポンスを返した場合、ホワイトリストモードが有効でなければクライアントは任意のトピックにパブリッシュ・サブスクライブ可能となり、不正アクセスやデータ漏洩の可能性があります。

レスポンス例：

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" 
}

HTTP認可の設定

デプロイメント画面で アクセス制御 -> 認可 -> 拡張認可 をクリックし、HTTP認可 を選択して 設定 をクリックします。

ID認可の場合、EMQX Cloudは現在のクライアント情報を用いてユーザーが設定した認可クエリリクエストを発行し、HTTPサーバー側でクライアントの認可データを照会します。

以下の手順に従って関連設定を完了してください：

• メソッド：HTTPリクエストメソッドを選択します。選択肢はget、postです。

  TIP

  POSTメソッドの使用を推奨します。GETメソッドを使用すると、一部の機密情報（平文パスワードなど）がHTTPサーバーログに露出する可能性があります。また、信頼できない環境ではHTTPSを利用してください。

• URL：HTTPサービスのURLアドレスを入力します。

  • URLはhttp://またはhttps://で始まる必要があります。
  • ドメイン名にプレースホルダーを使用しないでください。
  • URLパス内で以下のプレースホルダーを使用できます：
    • ${clientid}
    • ${username}
    • ${password}
    • ${peerhost}
    • ${cert_subject}
    • ${cert_common_name}

• ヘッダー（任意）：HTTPリクエストヘッダーの設定。複数のヘッダーを追加可能です。

• OAuth2クライアント認証（任意）：外部HTTP認可サービスがEMQXの認証を要求する場合に有効化します。このオプションはEMQX v6.1.4以降のデプロイメントで利用可能です。詳細はOAuth2クライアント認証の設定をご参照ください。

• 接続設定：同時接続数、接続タイムアウト待機時間、最大HTTPリクエスト数、リクエストタイムアウト時間を設定します。

• TLSの有効化：TLSを有効にするかどうかを設定します。

• 接続プールサイズ（任意）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルト値は8です。

• 接続タイムアウト（任意）：接続タイムアウト時間を設定します。単位は時間、分、秒、ミリ秒から選択可能です。

• HTTPパイプライニング（任意）：レスポンスを待たずに送信可能なHTTPリクエストの最大数を正の整数で指定します。デフォルト値は100です。

• リクエストタイムアウト（任意）：リクエストのタイムアウト時間を設定します。単位は時間、分、秒、ミリ秒から選択可能です。

• ボディ：リクエストテンプレートです。POSTリクエストはJSON形式でリクエストボディに送信されます。GETリクエストはURLのクエリパラメータとしてエンコードされます。マッピングのキーと値にはプレースホルダーを使用可能です。

TIP

• 現在のデプロイメントがDedicated Flexエディションの場合、VPCピアリング接続を作成し、サーバーアドレスは内部ネットワークアドレスを指定してください。
• 現在のデプロイメントがBYOCエディションの場合、パブリッククラウドコンソールでVPCピアリング接続を作成してください。詳細はBYOCデプロイメントの作成 - VPCピアリング接続設定をご参照ください。サーバーアドレスは内部ネットワークアドレスを指定してください。
• 「Init resource failure!」が発生した場合は、サーバーアドレスの正確性とセキュリティグループの開放状況を確認してください。

HTTPリクエストとレスポンス

クライアントがサブスクライブまたはパブリッシュ操作を開始すると、HTTP認可者は設定されたリクエストテンプレートに基づいてリクエストを構築・送信します。リクエストテンプレート内で認可ロジックを実装し、チェック結果が所定の形式で返されるようにしてください。

リクエスト

リクエストはJSON形式で、URLおよびリクエストボディ内に以下のプレースホルダーを使用できます：

• ${clientid}：クライアントID
• ${username}：クライアントがログイン時に使用したユーザー名
• ${peerhost}：クライアントの送信元IPアドレス
• ${proto_name}：クライアントが使用するプロトコル名（例：MQTT、CoAP）
• ${mountpoint}：ゲートウェイリスナーのマウントポイント（トピックプレフィックス）
• ${action}：要求されているアクション（例：publish、subscribe）
• ${topic}：現在のリクエストでパブリッシュまたはサブスクライブされるトピック（またはトピックフィルター）
• ${qos}：現在のリクエストでパブリッシュまたはサブスクライブされるメッセージのQoS
• ${retain}：現在のリクエストでパブリッシュされるメッセージがリテインメッセージかどうか

レスポンス

認可サービスは以下の形式でレスポンスを返す必要があります：

• レスポンスのcontent-typeはapplication/jsonであること。
• HTTPステータスコードが200の場合、認可結果はHTTPボディのresultフィールドの値により決定されます：
  • allow：パブリッシュまたはサブスクライブを許可
  • deny：パブリッシュまたはサブスクライブを拒否
• HTTPステータスコードが204の場合、このパブリッシュまたはサブスクライブ要求は許可されたものとみなされます。
• 200および204以外のHTTPステータスコードはすべて「無視（ignore）」として扱われます。例えば、HTTPサービスが利用不可の場合や認証エンドポイントが予期しないレスポンスを返した場合、ホワイトリストモードが有効でなければクライアントは任意のトピックにパブリッシュ・サブスクライブ可能となり、不正アクセスやデータ漏洩のリスクがあります。

レスポンス例：

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" 
}

TIP

POSTメソッドの使用を推奨します。GETメソッドを使用すると、一部の機密情報がHTTPサーバーログに露出する可能性があります。

信頼できない環境ではHTTPSを利用してください。

OAuth2クライアント認証の設定

EMQX v6.1.4以降のデプロイメントでは、HTTP認可でOAuth2クライアント認証をサポートしています。このオプションを有効にすると、EMQXは設定されたトークンエンドポイントからアクセストークンを取得・キャッシュし、自動的に更新します。EMQXが外部HTTP認可サービスにリクエストを送信する際、Authorization: Bearer <access_token>ヘッダーを追加します。

OAuth2クライアント認証を有効にし、以下の項目を設定してください：

項目	説明
トークンエンドポイント	必須。アクセストークンを要求するOAuth2認可サーバーのエンドポイント。URLはHTTPまたはHTTPSで、ユーザー情報を含んではいけません。
クライアントID	必須。アクセストークンを要求するためのOAuth2クライアントID。
クライアントシークレット	必須。アクセストークンを要求するためのOAuth2クライアントシークレット。
スコープ	任意。アクセストークンに要求するOAuth2スコープ。
トークンリクエストタイムアウト	トークンエンドポイントへのHTTPリクエストのタイムアウト。デフォルトは5秒。
トークンエンドポイントTLS	トークンエンドポイントへのTLSを有効化します。この設定は外部HTTP認可サービスへの接続を制御するTLSの有効化とは独立しています。

EMQXはapplication/x-www-form-urlencodedのコンテンツタイプでPOSTリクエストをトークンエンドポイントに送信します。リクエストボディにはgrant_type、client_id、client_secret、および任意のscopeが含まれます。トークンエンドポイントは200レスポンスでJSONボディにaccess_tokenを返す必要があります。token_typeとexpires_inも返すことができ、存在する場合はtoken_typeはBearer、expires_inは正の整数でなければなりません。

重要なお知らせ

• OAuth2を有効にした場合、HTTP認可設定でAuthorizationヘッダーを設定しないでください。EMQXは自動生成されるBearer認証ヘッダーと競合するため設定を拒否します。
• トークンエンドポイントはクライアントIDとクライアントシークレットをリクエストボディのフォームフィールドとして受け入れる必要があります。HTTP Basic認証のAuthorizationヘッダーによる認証はサポートされていません。