デフォルト認可
デフォルト認可は組み込みデータベースに基づいており、ユーザーに低コストでプラグアンドプレイの認可方法を提供します。本ドキュメントでは、クライアントID、ユーザー名、クォータ制限の設定方法や、より高度な権限管理のためのホワイトリストやプレースホルダーの使用方法について詳しく解説します。
認可情報の追加
注意
組み込み認可の最大エントリー数は、デプロイ接続数の2倍で、上限は100,000です。この制限を超える場合は、外部ACLの使用を推奨します。
認可は以下の3つのレベルで制御可能です。
- クライアントID：特定のクライアントIDに対する認可検証。
- ユーザー名：特定のユーザー名に対する認可検証。
- 全ユーザー：すべてのユーザーに対するトピックベースの認可検証。
クライアント認可ページで**+ 追加**を選択し、現在のカテゴリに基づいた新しい認可情報を追加します。
クライアントID認可の追加
クライアントIDタブでは、特定のクライアントIDに対する認可ルールを作成します。
- クライアントID：この認可ルールが適用されるクライアントID。
- トピック：このルールに対応するトピックを設定します。
- 操作：このルールに対応する操作を設定します。選択肢：
Publish、Subscribe、Publish and Subscribe。 - 許可：現在のクライアントに対して該当操作を許可するかどうか。選択肢：
Allow、Deny。
ユーザー名認可の追加
ユーザー名タブでは、特定のユーザー名に対する認可ルールを作成します。
- ユーザー名：このルールが適用されるユーザー名。
- トピック：このルールに対応するトピックを設定します。
- 操作：このルールに対応する操作を設定します。選択肢：
Publish、Subscribe、Publish and Subscribe。 - 許可：現在のユーザーに対して該当操作を許可するかどうか。選択肢：
Allow、Deny。
トピック認可の追加
全ユーザータブでは、特定のトピックに対する認可ルールを作成します。
- トピック：このルールに対応するトピックを設定します。
- 操作：このルールに対応する操作を設定します。選択肢：
Publish、Subscribe、Publish and Subscribe。 - 許可：現在のトピックに対して該当操作を許可するかどうか。選択肢：
Allow、Deny。
プレースホルダーの使用
トピックでプレースホルダーを使用すると、トピックマッチングルール内で現在のクライアント情報を動的に置換できます。サポートされているプレースホルダーは以下の通りです。
${clientid}${username}
すべてのユーザーに対して特定トピックのみのサブスクライブやパブリッシュを制限したい場合、以下のように設定できます。
- ユーザー名
${username}、トピックxx/${username}/report - クライアントID
${clientid}、トピックxx/${clientid}/report
プレースホルダーはトピックのフィールド全体を置換する場合にのみ使用可能です。例えば、a/b/${username}/c/dは有効ですが、a/b${username}c/dのようにフィールドの一部を置換することはできません。
セキュリティ推奨
トピック認可ルールで ${clientid} または ${username} を使用する場合、クライアントIDやユーザー名に MQTT ワイルドカード文字を使用しないようにしてください。
+ と # は MQTT のワイルドカード文字であり、プレースホルダーを用いた認可ルールで使用するとトピックマッチングの挙動に影響を与える可能性があります。例えば、クライアントIDが + の場合、ルール device/${clientid}/# は device/+/# に解決され、意図よりも広範囲のトピックマッチングとなります。
このリスクを軽減するため、以下の値をブラックリストにクライアントIDおよびユーザー名として追加することを推奨します。
+#+/#
より厳格なアクセス制御が必要な環境では、クライアントIDやユーザー名に MQTT ワイルドカード文字を禁止する命名規則の適用を検討してください。
認可情報のインポート
提供されているCSVテンプレートを使用して認可情報を一括インポートできます（「全ユーザー」には対応していません）。インポート可能なフィールドは以下の通りです。
clientid：クライアントIDusername：ユーザー名topic：認可トピックaction：操作（sub/pub/pubsub）access：許可かどうか（allow/deny）
以下の手順で認可情報を一括インポートできます。
インポートボタンをクリックします。
テンプレートをダウンロードします。クライアントIDテンプレートの例は以下の通りです。
認可情報を入力し、ファイルをアップロードします。
インポートをクリックします。
認可情報の閲覧
認可情報を追加後、認可ページで閲覧可能です。認可エントリーの詳細は、クライアントID、ユーザー名、全ユーザー（トピック）の3つの軸で確認できます。
認可情報の編集
認可情報の横にある編集アイコンをクリックすると、現在の認可情報を修正できます。
認可情報の削除
認可情報の横にある削除アイコンをクリックすると、該当情報を削除できます。
認可モード
EMQXは2つの認可戦略をサポートしています：ブラックリストモードとホワイトリストモードです。
| モード | 挙動 |
|---|---|
| ブラックリストモード（デフォルト） | 明示的に拒否されていないすべてのパブリッシュおよびサブスクライブ操作を許可します。 |
| ホワイトリストモード | すべてのパブリッシュおよびサブスクライブ操作をデフォルトで拒否し、明示的に許可された操作のみを許可します。 |
認可ルールは以下の順序で評価されます。まずユーザー名 / クライアントIDルール、次に全ユーザールールです。システムは最初にマッチしたルールを適用します。ルールがマッチしない場合、アクティブなモードに応じて結果が変わります。ブラックリストモードでは許可、ホワイトリストモードでは拒否されます。
TIP
- 「全ユーザー」認可内で複数ルールが存在する場合、作成順に評価されます（先に作成されたルールが優先）。意図しないアクセス遮断を防ぐため、より具体的な許可ルール（例：
emqx/#）を一般的な拒否ルール（例：deny #）の前に配置してください。 - クライアントID / ユーザー名とトピックの組み合わせは一意です。同じ組み合わせの複数レコードがある場合、最新のレコードのみが有効です。
- 拡張認可データソースを追加している場合は、拡張認可ページで「デフォルト認可」が認可順序の最後に配置されていることを確認してください。
::: caution 注意
セキュリティ上の理由から、クライアントのサブスクライブトピックフィルターにおいて、生のワイルドカード # は許可されていません。例えば、# は有効なクライアントサブスクライブトピックではありませんが、t/# は許可されます。この制限はクライアントのサブスクライブ操作にのみ適用され、認可ルールのトピックパターンには影響しません。認可ルールでは # を使用可能です（例：ホワイトリストモードを有効にするため、「デフォルト認可」下にすべてのユーザーの # へのパブリッシュとサブスクライブを拒否するルールを追加するなど、拒否のフォールバックルールとして利用できます）。
:::
認可モードの切り替え（推奨）
バージョン注意
ワンクリックでの認可モード切り替えは、EMQX DedicatedおよびDedicated FlexのEMQXバージョン5.10以降で利用可能です。Serverlessデプロイメントではサポートされていません。
対応するデプロイメントでは、コンソールから直接認可モードを切り替えられ、トピックルールの設定は不要です。
- クライアント認可ページに移動します。
- ページ右上のブラックリストモードボタンをクリックし、ホワイトリストモードを選択して切り替えます。
ホワイトリストモードに切り替えると、すべてのパブリッシュおよびサブスクライブ操作がデフォルトで拒否されます。クライアントが特定トピックにアクセスするには、許可ルールの設定が必要です。
ルールによるホワイトリストモードの設定
認可モード切り替えに対応していないデプロイメント（EMQXバージョン5.10未満やServerless）では、拒否の全件ルールを追加することでホワイトリスト動作を実現できます。
クライアント認可ページの全ユーザータブで認可エントリーを追加し、トピックに # を入力、操作に Publish & Subscribe を選択、許可に Deny を選択して確定します。
このルールは最終的なフォールバック拒否ルールとして機能し、他のルールで明示的に許可されていないトピック操作をすべて拒否します。これによりホワイトリスト動作が実現されます。
ベストプラクティス
対応しているデプロイメントでは、コンソールの認可モード切り替え機能を使ってホワイトリストモードを有効化することを推奨します。手動で「deny #」ルールを追加するよりも設定が簡潔になります。
認可統計の閲覧
画面右上の認可統計アイコンをクリックすると、認可のメトリクスやレート指標を確認できます。
