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

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

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

::: tip

認証によって返されるACLルールは、すべてのAuthorizerよりも先にチェックされます。詳細は [Authorization Check Priority](../authz/authz.md#authorization-check-priority) を参照してください。
:::

## ACLフォーマット

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

### 新フォーマット

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

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

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

| フィールド     | 必須    | 説明                                                                                   |
| -------------- | ------- | -------------------------------------------------------------------------------------- |
| permission     | はい    | 現在のクライアントの操作リクエストを許可するか拒否するかを指定。`allow` または `deny`  |
| action         | はい    | ルールに関連する操作。`publish`、`subscribe`、`all` のいずれか                         |
| topic          | はい    | ルールに関連するトピック。 [トピックプレースホルダー](../authz/authz.md#topic-placeholders)をサポート |
| qos            | いいえ  | ルールに適用されるQoSレベルの配列。例：`[0, 1]`、`[1, 2]`。指定しない場合はすべてのQoSレベルが対象 |
| retain         | いいえ  | ブール値。パブリッシュ操作のみ使用。現在のルールがリテインメッセージを許可するかどうか。`true` または `false`。指定しない場合はリテインメッセージを許可 |

例：

```json
{
  "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` 構文が用意されており、プレースホルダーの展開をスキップします。

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