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

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

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

TIP

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

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。指定しない場合はリテインメッセージを許可

例：

{
  "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} として処理されます。