EMQX

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ

HTTPサービスの利用 ​

TIP

EMQX v5.8.0以降、HTTP認証器はレスポンスボディにACLルールを含めてクライアントの権限を事前設定できるようになりました。より高いパフォーマンスのために新しいフォーマットの使用を推奨します。詳細はHTTP認証をご参照ください。

EMQXはHTTPサービスをベースとした認可をサポートしています。ユーザーは外部のHTTPアプリケーションをデータソースとして自ら構築する必要があります。EMQXはHTTPサービスにリクエストを送り、HTTP APIから返されるデータに基づいて認可結果を判定し、複雑な認可ロジックを実現します。

Tip

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

クライアントがサブスクライブまたはパブリッシュ操作を開始すると、HTTP認可者は設定されたリクエストテンプレートに基づいてリクエストを構築し送信します。ユーザーは認可サービス内に認可ロジックを実装し、以下の要件に従って結果を返す必要があります。

リクエスト ​

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

  • ${clientid}：クライアントID。
  • ${username}：クライアントのログイン時に使用されたユーザー名。
  • ${client_attrs.NAME}：クライアント属性。NAMEは実行時に事前設定された属性名に置き換えられます。クライアント属性の詳細はMQTTクライアント属性をご覧ください。
  • ${peerhost}：クライアントの送信元IPアドレス。
  • ${proto_name}：クライアントが使用するプロトコル名（例：MQTT、CoAP）。
  • ${mountpoint}：ゲートウェイリスナーのマウントポイント（トピックプレフィックス）。
  • ${action}：リクエストされているアクション（例：publish、subscribe）。
  • ${topic}：現在のリクエストでパブリッシュまたはサブスクライブされるトピック（またはトピックフィルター）。
  • ${qos}：現在のリクエストでパブリッシュまたはサブスクライブされるメッセージのQoS。
  • ${retain}：現在のリクエストでパブリッシュされるメッセージがリテインドかどうか。
  • ${zone}：実行時のクライアントのゾーン。ゾーンはクライアントの論理的分類（例：地域や環境）であり、クライアント設定に基づいて動的に適用されます。

レスポンス ​

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

  • レスポンスのcontent-typeはapplication/jsonであること。
  • HTTPステータスコードが200の場合、認可結果はHTTPボディのresultフィールドの値により判定されます：
    • allow：パブリッシュまたはサブスクライブを許可。
    • deny：パブリッシュまたはサブスクライブを拒否。
    • ignore：このリクエストを無視し、次の認可者に処理を委ねる。
  • HTTPステータスコードが204の場合、このパブリッシュまたはサブスクライブリクエストは許可されたことを意味します。
  • 200および204以外のHTTPステータスコードは「無視」とみなされます。例えば、HTTPサービスが利用不可の場合などです。

レスポンス例：

json
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" | "ignore" // デフォルトは "ignore"
}

EMQX 4.x互換性について

4.xバージョンでは、EMQXはHTTP APIのステータスコードのみを使用し、コンテンツは破棄していました。例えば、200はallow、403はdenyを意味していました。より多くの情報をユーザーに提供するため、EMQX 5.0でリクエストコンテンツの返却を追加しました。

TIP

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

信頼できない環境ではHTTPSの利用を推奨します。

ダッシュボードでの設定 ​

  1. EMQXダッシュボードの左ナビゲーションツリーでアクセス制御 -> 認可をクリックし、認可ページに入ります。

  2. 右上の作成をクリックし、バックエンドとしてHTTPサーバーを選択し、次へをクリックします。以下のように設定タブが表示されます。

    HTTP認可設定画面

  3. 以下の指示に従い設定を行います。

    HTTP：HTTPリクエストメソッド、IPアドレス、リクエストヘッダーを設定します。

    • リクエストメソッド：HTTPリクエストメソッドを選択します。選択肢はGET、POST。
    • URL：HTTPアプリケーションのIPアドレスを入力します。
    • ヘッダー（任意）：HTTPリクエストヘッダーを設定します。キーと値はプレースホルダーの使用が可能です。

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

    • プールサイズ（任意）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルトは8。
    • 接続タイムアウト（任意）：接続タイムアウトまでの待機時間を入力します。単位は時間、分、秒、ミリ秒が指定可能です。
    • HTTPパイプライニング（任意）：正の整数で、レスポンスを待たずに送信可能な最大HTTPリクエスト数を指定します。デフォルトは100。
    • リクエストタイムアウト（任意）：リクエストタイムアウトまでの待機時間を入力します。単位は時間、分、秒、ミリ秒が指定可能です。
    • TLS設定：TLSを有効にするかどうかを設定します。

    認可設定：HTTPリクエストボディの設定を完了します。

  4. 作成をクリックして設定を完了します。

設定項目による設定 ​

HTTP認可はtype=httpで設定します。

HTTPのPOSTおよびGETリクエストがサポートされており、それぞれ固有のオプションがあります。

POSTリクエストで設定したHTTP認可者の例：

bash
{
    type = http

    method = post
    url = "http://127.0.0.1:32333/authz/${peercert}?clientid=${clientid}"
    body {
        username = "${username}"
        topic = "${topic}"
        action = "${action}"
    }
    headers {
        "Content-Type" = "application/json"
        "X-Request-Source" = "EMQX"
    }
}

GETリクエストで設定したHTTP認可者の例：

bash
{
    type = http

    method = get
    url = "http://127.0.0.1:32333/authz"
    body {
        username = "${username}"
        topic = "${topic}"
        action = "${action}"
    }
    headers {
        "X-Request-Source" = "EMQX"
    }
}