アクセスコントロールリスト

このページでは、JWT および HTTP 認証レスポンスに埋め込まれたアクセスコントロールリスト（ACL）ルールについて紹介します。現在、JWT 認証および HTTP 認証は、認証結果のオプション拡張として ACL を使用した権限プリセットをサポートしています。例えば、JWT 内に定義されたプライベートクレーム acl や、HTTP 認証レスポンスの一部として返される acl JSON プロパティが該当します。クライアントが接続した後、そのパブリッシュおよびサブスクライブの操作はこれらの ACL ルールによって制限されます。

一般的な ACL ルールは acl.conf に保存されています。詳細は acl.conf をご参照ください。より包括的な認可方法については、認可 をご覧ください。

TIP

認証によって返される ACL ルールは、すべての Authorizer よりも先にチェックされます。詳細は 認可チェックの優先順位 をご参照ください。

ACL フォーマット

このセクションでは、EMQX がサポートする 2 つの ACL フォーマットを紹介します。

新フォーマット

新フォーマットは v5.5.0 以降でサポートされており、ACL を用いて複数の権限を指定でき、ACL ルールの意味に近く、より柔軟性があります。

旧フォーマットと異なり、新フォーマットではクライアントの操作がいずれのルールにもマッチしない場合、他の認可チェックへ継続します。旧フォーマットは互換性のため残っていますが、新フォーマットの使用が推奨されます。

ACL は以下のフィールドを含みます。

フィールド	必須	説明
permission	はい	現在のクライアントの操作リクエストを許可するか拒否するかを指定。allow または deny のいずれか。
action	はい	ルールに関連する操作。publish、subscribe、all のいずれか。
topic	はい	ルールに関連するトピック。 トピックプレースホルダー をサポート。
qos	いいえ	ルールに適用される QoS レベルの配列。例：[0, 1]、[1, 2]。指定しない場合はすべての QoS レベルが対象。
retain	いいえ	ブローカーのパブリッシュ操作にのみ使用するブール値。現在のルールが保持メッセージに適用されるかどうかを指定。true または false。指定しない場合は保持メッセージに適用。
clientid_re (e5.9.0+)	いいえ	クライアントIDにマッチする正規表現。例：^client-[0-9]+$
username_re (e5.9.0+)	いいえ	ユーザー名にマッチする正規表現。例：^user-[0-9]+$
ipaddr (e5.9.0+)	いいえ	IPアドレスまたはサブネット。例：192.168.5.0/24
zone (e5.9.0+)	いいえ	ゾーン名。例：zone1
zone_re (e5.9.0+)	いいえ	ゾーン名にマッチする正規表現。例：^zone-[0-9]+$
listener (e5.9.0+)	いいえ	リスナー名。例：tcp:default
listener_re (e5.9.0+)	いいえ	リスナー名にマッチする正規表現。例：^tcp:.*$

ルールを適用するには、指定されたすべてのフィールドがマッチする必要があります。

例：

{
  "exp": 1706844358,
  "username": "emqx_u",
  "acl": [
    {
      // クライアントがトピック t/${clientid}（例: t/emqx_c）にメッセージをパブリッシュすることを許可
      "permission": "allow",
      "action": "publish",
      "topic": "t/${clientid}"
    },
    {
      "permission": "allow",
      "action": "subscribe",
      // 'eq' プレフィックスはルールが 't/1/#' にマッチするが、't/1/x' や 't/1/y' にはマッチしないことを意味
      "topic": "eq t/1/#",
      // QoS 1 にマッチし、QoS 0 または 2 にはマッチしない
      "qos": [1]
    },
    {
      // クライアントがトピック t/2 に保持メッセージをパブリッシュすることを拒否。非保持メッセージは許可
      "permission": "deny",
      "action": "publish",
      "topic": "t/2",
      "retain": true
    },
    {
      // クライアントがトピック t/3 に対してパブリッシュおよびサブスクライブすることを拒否。すべての QoS レベルおよび保持メッセージを含む
      "permission": "deny",
      "action": "all",
      "topic": "t/3"
    }
  ]
}

旧フォーマット

以下の JWT ACL の例では、権限リストが pub、sub、all の 3 つのオプションフィールドとして定義されており、それぞれパブリッシュ、サブスクライブ、または両方のトピックのホワイトリストを指定します。トピックはトピックワイルドカードおよびプレースホルダー（現在は ${clientid} と ${username} をサポート）を含むことができます。トピックの内容とプレースホルダー構文の競合を回避するために、eq 構文が用意されており、プレースホルダーの展開をバイパスします。

{
  "exp": 1654254601,
  "username": "emqx_u",
  "acl": {
    "pub": [
      "testpub1/${username}",
      "eq testpub2/${username}"
    ],
    "sub": [
      "testsub1/${username}",
      "testsub2/${clientid}",
      "testsub2/#"
    ],
    "all": [
      "testall1/${username}",
      "testall2/${clientid}",
      "testall3/#"
    ]
  }
}

この例では、testpub1/${username} は実行時に testpub1/emqx_u に置き換えられますが、eq testpub2/${username} は実行時に testpub2/${username} として処理されます。