EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

HTTPサービスの利用 ​

TIP

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

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

ヒント

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}：実行時のクライアントのZone。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系ではHTTP APIが返すステータスコードのみを使用し、内容は破棄していました。例えば200はallow、403はdenyを意味していました。より詳細な情報を提供するために、EMQX 5.0からはレスポンス内容の返却を追加しています。

TIP

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

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

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

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

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

    authz-http_ee

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