HTTPサービスの利用

EMQXは、パスワード認証に外部のHTTPサービスを利用することをサポートしています。有効化すると、クライアントが接続要求を開始した際に、EMQXは受け取った情報を使ってHTTPリクエストを構築し、クエリ結果に基づいて要求を受け入れるかどうかを判断し、複雑な認証ロジックを実現します。

前提条件

基本的なEMQX認証の概念の知識

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

認証プロセスはHTTP APIコールに似ており、EMQXはリクエストクライアントとして「API」が要求する形式でHTTPサービスにリクエストを構築・送信し、HTTPサービスは「クライアント」が要求する形式で結果を返します。

• レスポンスのエンコーディング形式 content-type は application/json である必要があります。
• 認証結果はボディ内の result で示し、オプション値は allow、deny、ignore です。
• スーパーユーザーはボディ内の is_superuser で示し、オプション値は true または false です。
• EMQX v5.7.0以降、オプションの client_attrs フィールドを使ってクライアント属性を設定可能です。キーと値は両方とも文字列である必要があります。
• EMQX v5.8.0以降、レスポンスボディにオプションの acl フィールドを設定してクライアントの権限を指定できます。詳細はアクセスコントロールリスト（ACL）を参照してください。
• EMQX v5.8.0以降、レスポンスボディにオプションの expire_at フィールドを設定してクライアント認証の有効期限を指定可能です。これによりクライアントは切断され、再接続時に再認証が強制されます。値は秒単位のUnixタイムスタンプです。
• HTTPレスポンスのステータスコードは 200 または 204 であるべきです。4xx/5xx のステータスコードが返された場合はボディを無視し、結果を ignore として認証チェーンを継続します。

レスポンス例:

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow", // "allow" | "deny" | "ignore"
    "is_superuser": false, // オプション値: true | false、デフォルト値: false
    "client_attrs": { // オプション（v5.7.0以降）
        "role": "admin",
        "sn": "10c61f1a1f47"
    }
    "expire_at": 1654254601, // オプション（v5.8.0以降）
    "acl": // オプション（v5.8.0以降）
    [
        {
            "permission": "allow",
            "action": "subscribe",
            "topic": "eq t/1/#",
            "qos": [1]
        },
        {
            "permission": "deny",
            "action": "all",
            "topic": "t/3"
        }
    ]
}

EMQX 4.xとの互換性について

EMQX 4.xではHTTPステータスコードのみが使用され、ボディは破棄されます。例えば、200 は allow、403 は deny を示します。表現力が不足していたため、HTTPボディを活用する形に再設計されており、EMQX 5.0とは互換性がありません。

ダッシュボードでの設定

EMQXダッシュボードから関連設定を完了できます。

1. EMQXダッシュボードの左ナビゲーションメニューで Access Control -> Authentication をクリックします。
2. Authentication ページの右上にある Create をクリックします。
3. Mechanism に Password-Based を、Backend に HTTP Server を選択し、Configuration タブに進みます。以下のように表示されます。

4. 以下の指示に従い認証バックエンドを設定します。

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

     TIP

     POST メソッドの利用を推奨します。GET メソッドを使う場合、パスワードなどの機微な情報がHTTPサーバーログに平文で記録される可能性があります。また、信頼できない環境ではHTTPSを使用してください。

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

   • Precondition: Variform式で、HTTPサーバー認証器をクライアント接続に適用するかどうかを制御します。式はクライアントの属性（username、clientid、listenerなど）に対して評価され、結果が文字列の "true" の場合のみ認証器が呼び出されます。それ以外の場合はスキップされます。詳細は認証の前提条件を参照してください。

   • Headers（オプション）: HTTPリクエストヘッダーです。複数追加可能で、キーと値にはプレースホルダーを使用できます。

   • Enable TLS: TLSを有効にする場合はトグルスイッチをオンにします。TLS有効化の詳細はネットワークとTLSを参照してください。

   • Body: リクエストテンプレートです。POST リクエストの場合はJSON形式でリクエストボディに送信され、GET リクエストの場合はURLのクエリ文字列にエンコードされます。キーと値にはプレースホルダーを使用可能です。

   • 詳細設定:

     • Pool size（オプション）: EMQXノードからHTTPサーバーへの同時接続数を整数で指定します。デフォルトは 8 です。

     • Connect Timeout（オプション）: EMQXが接続タイムアウトとみなすまでの待機時間を指定します。単位はミリ秒、秒、分、時間が利用可能です。

     • HTTP Pipelining（オプション）: 応答を待たずに送信可能な最大HTTPリクエスト数を正の整数で指定します。デフォルトは 100 です。

     • Request Timeout（オプション）: EMQXがリクエストタイムアウトとみなすまでの待機時間を指定します。単位はミリ秒、秒、分、時間が利用可能です。

5. 設定が完了したら Create をクリックします。

設定項目による設定

EMQXの設定項目でHTTP認証器を設定できます。

以下はHTTPの POST と GET リクエストの例です。

{
    mechanism = password_based
    backend = http

    method = post
    url = "http://127.0.0.1:8080/auth?clientid=${clientid}"
    body {
        username = "${username}"
        password = "${password}"
    }
    headers {
        "Content-Type" = "application/json"
        "X-Request-Source" = "EMQX"
    }
}

注：body はクエリ文字列に変換されます。

{
    mechanism = password_based
    backend = http

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