REST APIベースの MQTT 5.0 SCRAM 認証

EMQX は REST API を利用した MQTT 5.0 の拡張認証をサポートしており、Salted Challenge Response Authentication Mechanism (SCRAM) を実装しています。本実装では、SCRAM 認証器が外部のウェブリソースから必要な認証データを取得します。有効化されている場合、クライアントが SCRAM で接続要求を開始すると、EMQX は提供されたユーザー名を使って外部サービスへ HTTP リクエストを構築し、認証プロセスに必要な認証データを取得します。

SCRAM はもともと軽量でシンプルな認証機構ですが、本実装では外部 REST API と連携することで機能を拡張しています。これにより、EMQX は様々な外部システムから安全かつ効率的に認証データを取得でき、より複雑な認証シナリオに対応可能です。

前提条件

• EMQX の基本的な認証概念に関する理解があること。
• SCRAM 認証器は MQTT 5.0 接続のみサポートしています。
• 本認証器は RFC 7804: Salted Challenge Response HTTP Authentication Mechanism の実装ではありません。

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

認証プロセスは HTTP API コールに似ています。EMQX はクライアントとして動作し、外部 HTTP サービスへ HTTP リクエストを構築・送信します。サービスは username に対応する認証データをレスポンスとして返します。

レスポンス形式の要件

認証を成功させるために、HTTP レスポンスは以下の条件を満たす必要があります。

• Content-Type: レスポンスは application/json でエンコードされていること。
• 認証データ: stored_key、server_key、salt を含み、すべて16進数でエンコードされていること。
• スーパーユーザー指標: is_superuser フィールドを使用し、値は true または false。
• クライアント属性: 任意で client_attrs フィールドにクライアント属性を指定可能。キーと値は文字列である必要があります。
• アクセス制御リスト (ACL): 任意で acl フィールドにクライアントの権限を定義可能です。詳細はアクセス制御リストを参照してください。
• 有効期限: 任意で expire_at フィールドを設定可能で、クライアントの認証有効期限を Unix タイムスタンプ（秒単位）で指定します。期限切れ後はクライアントは切断し、再認証が必要です。
• HTTP ステータスコード: HTTP レスポンスは 200 OK を返す必要があります。4xx または 5xx のステータスコードは ignore と解釈され、この認証器をスキップして認証チェーンが続行されます。

HTTP レスポンス例

以下は期待される HTTP レスポンスの構造と内容の例です。

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "stored_key": "008F5E0CC6316BB172F511E93E4756EEA876B5B5125F1CD2FD69A2C30F9A0D73",
    "server_key": "81466E185EC642AFAE1EFA75953735D6C0934D099149AAAB601D59F8F8162580",
    "salt": "6633653634383437393466356532333165656435346432393464366165393137"
    "is_superuser": true, // オプション: true | false、デフォルトは false
    "client_attrs": { // 任意
        "role": "admin",
        "sn": "10c61f1a1f47"
    }
    "expire_at": 1654254601, // 任意
    "acl": // 任意
    [
        {
            "permission": "allow",
            "action": "subscribe",
            "topic": "eq t/1/#",
            "qos": [1]
        },
        {
            "permission": "deny",
            "action": "all",
            "topic": "t/3"
        }
    ]
}

ダッシュボードでの認証器設定

EMQX ダッシュボードから SCRAM 認証器を設定できます。

1. EMQX ダッシュボードにログインします。

2. 左側のナビゲーションメニューで アクセス制御 -> 認証 をクリックし、認証 ページを開きます。

3. 右上の 作成 をクリックします。

4. メカニズム に SCRAM を選択し、バックエンド に HTTP Server を選択します。次へ をクリックすると、以下のような 設定 ステップのページに進みます。

   

5. バックエンドの設定を以下のように行います。

   • Method: HTTP リクエストメソッドを選択します（GET または POST）。

     TIP

     POST メソッドは、パスワードなどの機密情報がサーバーログに露出するのを避けるため推奨されます。信頼できない環境では HTTPS を使用してください。

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

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

   • Headers（任意）: 追加の HTTP リクエストヘッダーを指定します。

   • 認証設定:

     • Password Hash: パスワードハッシュアルゴリズムを選択します（sha256 または sha512）。
     • TLS を有効化: スイッチを切り替えて TLS を有効化します。TLS 有効化の詳細は外部リソースアクセスの TLSを参照してください。
     • Body: リクエストテンプレートを定義します。POST リクエストの場合は JSON 形式でリクエストボディに送信され、GET リクエストの場合は URL のクエリ文字列としてエンコードされます。プレースホルダーを使ってキーと値をマッピングしてください。

   • 詳細設定:

     • コネクションプールサイズ（任意）: EMQX ノードから HTTP サーバーへの同時接続数（整数値）を設定します。デフォルトは 8。
     • 接続タイムアウト（任意）: EMQX が接続タイムアウトと判断するまでの待機時間を指定します。サポートされる単位は milliseconds、second、minute、hour です。
     • HTTP パイプライニング（任意）: 応答を待たずに送信可能な最大 HTTP リクエスト数を正の整数で指定します。デフォルトは 100。
     • リクエストタイムアウト（任意）: EMQX がリクエストタイムアウトと判断するまでの待機時間を指定します。サポートされる単位は milliseconds、second、minute、hour です。
     • イテレーション回数（任意）: SCRAM のイテレーション回数を設定します。デフォルトは 4096。

6. 設定が完了したら、作成 をクリックして設定を確定します。