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

このページでは、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} として処理されます。