デフォルト認可

デフォルト認可は組み込みデータベースに基づいており、ユーザーに低コストでプラグアンドプレイの認可方法を提供します。本ドキュメントでは、クライアントID、ユーザー名、クォータ制限の設定方法や、より高度な権限制御のためのホワイトリストやプレースホルダーの使用方法について詳しく解説します。

認可情報の追加

注意

組み込み認可の最大エントリー数は、デプロイ接続数の2倍で、上限は100,000件です。この制限を超える場合は、外部ACLの利用を推奨します。

認可は以下の3つのレベルで制御できます。

1. クライアントID：特定のクライアントIDに対する認可検証。
2. ユーザー名：特定のユーザー名に対する認可検証。
3. 全ユーザー：すべてのユーザーに対するトピックベースの認可検証。

クライアント認可ページで**+ 追加**を選択し、現在のカテゴリに基づいて新しい認可情報を追加します。

クライアント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。

プレースホルダーの使用

認可トピックの設定時にプレースホルダーを使用できます。認可マッチング時にEMQXは現在のクライアント情報に基づいてプレースホルダーを動的に実際の値に置き換えます。サポートされているトピックプレースホルダーは以下の通りです。

• ${clientid}：クライアントID。
• ${username}：ユーザー名。
• ${client_attrs.NAME}：クライアント属性。NAMEはクライアント属性名で、例として ${client_attrs.productId} や ${client_attrs.deviceId} などがあります。

クライアントが自身の情報に関連するトピックのみパブリッシュまたはサブスクライブできるように制限したい場合、以下のようにトピックを設定できます。

• ユーザー名を使う場合：トピック xx/${username}/report
• クライアントIDを使う場合：トピック xx/${clientid}/report
• クライアント属性を使う場合：トピック up/${client_attrs.productId}/${client_attrs.deviceId}

プレースホルダーはトピックレベル全体を置き換えることができます。例えば、a/b/${username}/c/d は有効ですが、トピックレベルの一部だけを置き換える a/b${username}c/d は無効です。

参照されたクライアント属性が存在しない場合、プレースホルダーは空文字列としてレンダリングされず、通常はルールが期待通りにマッチしません。関連するクライアント属性がクライアント認証時に返されるか、クライアント属性設定で生成されていることを確認してください。

セキュリティ推奨

トピック認可ルールで ${clientid} や ${username} を使用する場合、クライアントIDやユーザー名にMQTTのワイルドカード文字を使用しないでください。

+ と # はMQTTのワイルドカード文字であり、プレースホルダーを用いた認可ルールで使用するとトピックマッチングの挙動に影響を与える可能性があります。例えば、クライアントIDが + の場合、ルール device/${clientid}/# は device/+/# と解釈され、本来意図したより広範囲のトピックマッチングが発生します。

このリスクを軽減するため、以下の値をクライアントIDおよびユーザー名の両方としてブラックリストに追加することを推奨します。

• +
• #
• +/#

より厳格なアクセス制御が必要な環境では、クライアントIDおよびユーザー名にMQTTワイルドカード文字を禁止する命名規則の適用を検討してください。

認可情報のインポート

提供されているCSVテンプレートを使用して認可情報を一括インポートできます（「全ユーザー」カテゴリは非対応）。インポート用のフィールドは以下の通りです。

• clientid：クライアントID
• username：ユーザー名
• topic：認可トピック
• action：アクション（sub/pub/pubsub）
• access：許可の有無（allow/deny）

以下の手順で認可情報を一括インポートできます。

1. インポートボタンをクリックします。

2. テンプレートをダウンロードします。以下はクライアントIDテンプレートの例です。

   

3. 認可情報を入力し、ファイルをアップロードします。

4. インポートをクリックします。

認可情報の表示

認可情報を追加後、認可ページで確認できます。認可エントリーの詳細は、クライアントID、ユーザー名、全ユーザー（トピック）の3つの軸で表示可能です。

認可情報の編集

認可情報の横にある編集アイコンをクリックすると、現在の認可情報を修正できます。

認可情報の削除

認可情報の横にある削除アイコンをクリックすると、該当の認可情報を削除できます。

認可モード

EMQXは2つの認可戦略をサポートしています：ブラックリストモードとホワイトリストモードです。

モード	動作
ブラックリストモード（デフォルト）	明示的に拒否されていないすべてのパブリッシュおよびサブスクライブ操作を許可します。
ホワイトリストモード	すべてのパブリッシュおよびサブスクライブ操作をデフォルトで拒否し、明示的に許可された操作のみを許可します。

認可ルールは以下の順序で評価されます：まずユーザー名 / クライアントIDルール、次に全ユーザールールです。システムは最初にマッチしたルールを適用します。ルールにマッチしない場合の結果は、アクティブなモードによって異なります。ブラックリストモードでは許可、ホワイトリストモードでは拒否されます。

TIP

• 「全ユーザー」認可内で複数のルールが存在する場合、作成順に評価されます（先に作成されたルールが優先）。より具体的な許可ルール（例：emqx/#）を一般的な拒否ルール（例：deny #）の前に配置し、正当なアクセスが誤ってブロックされないようにしてください。
• クライアントID / ユーザー名とトピックの組み合わせは一意です。同じクライアントID / ユーザー名とトピックの複数レコードがある場合、最新のレコードのみが有効です。
• 拡張認可データソースを追加している場合は、拡張認可ページで「デフォルト認可」が認可順序の最後に配置されていることを確認してください。

::: caution 注意

セキュリティ上の理由から、クライアントのサブスクライブトピックフィルターにおいて、単独のワイルドカード # は許可されていません。例えば、# は有効なクライアントサブスクライブトピックではありませんが、t/# は許可されます。この制限はクライアントのサブスクライブ操作にのみ適用され、認可ルールのトピックパターンには影響しません。認可ルールのトピックパターンでは # を使用可能です（例：ホワイトリストモードを有効にするために、「デフォルト認可」で全ユーザーのパブリッシュおよびサブスクライブを # に対して拒否するルールを追加するなど）。

:::

認可モードの切り替え（推奨）

バージョン注意

ワンクリックでの認可モード切り替えは、EMQX DedicatedおよびDedicated FlexのEMQXバージョン5.10以降で利用可能です。Serverless環境ではサポートされていません。

対応するデプロイメントでは、コンソールからトピックルールを設定せずに認可モードを切り替えられます。

1. クライアント認可ページに移動します。
2. ページ右上のブラックリストモードボタンをクリックし、ホワイトリストモードを選択して切り替えます。

ホワイトリストモードに切り替えると、すべてのパブリッシュおよびサブスクライブ操作はデフォルトで拒否されます。クライアントが特定のトピックにアクセスできるように、許可ルールを設定する必要があります。

ルールによるホワイトリストモードの設定

認可モード切り替えがサポートされていないデプロイメント（EMQXバージョン5.10未満やServerless環境）では、全拒否ルールを追加することでホワイトリスト動作を実現できます。

クライアント認可ページの全ユーザータブで認可エントリーを追加します。トピック欄に # を入力し、アクションに Publish & Subscribe を選択、許可に Deny を選択して、確定をクリックします。

このルールは最終的なフォールバック拒否ルールとして機能します。明示的に許可されていないトピック操作はすべて拒否され、ホワイトリスト動作を実現します。

ベストプラクティス

対応するデプロイメントでは、コンソールの認可モード切り替え機能を使ってホワイトリストモードを有効にすることを推奨します。手動で「deny #」ルールを追加するよりも設定が簡潔になります。

認可統計の表示

右上の認可統計アイコンをクリックすると、認可のメトリクスやレート指標を確認できます。