認証
認証はクライアントの身元を検証するプロセスです。ほとんどのアプリケーションにおいて不可欠なものであり、不正なクライアント接続からサービスを保護するのに役立ちます。
EMQXは複数の認証機構をサポートしており、TLS X.509証明書認証やTLS-PSK認証もサポートしています。これによりクライアントとサーバー間の認証要求に対する選択肢が提供されます。
本節では、身元認証の基本概念と設定について説明します。
TIP
デフォルトでは、EMQXは認証機能を有効にしておらず、すべてのクライアントの接続を許可します。運用環境で使用する場合は、少なくとも1つの認証方式を事前に設定してください。
認証機構
EMQXがサポートする認証機構は以下の通りです。
- X.509証明書認証
- JWT認証
- ユーザー名/パスワード認証
- MQTT 5.0の拡張認証
- PSK認証
X.509証明書認証
EMQXはクライアント認証のためにX.509証明書認証をサポートしています。EMQXでX.509証明書認証を使用すると、クライアントとサーバーはTLS/SSLを介して信頼できる接続を確立し、通信当事者の真正性と送信データの整合性を保証します。EMQXは片方向認証(クライアントがサーバーのみを認証)と相互認証(クライアントとサーバーがお互いの証明書を検証)を両方サポートしており、さまざまなセキュリティ要件や展開シナリオに対応可能です。
JWT認証
JSON Web Token (JWT)は、サーバーがクライアントの認証情報やセッション情報を保持しないトークンベースの認証機構です。
クライアントは接続要求にJWTを含め、EMQXは事前に設定されたシークレットまたは公開鍵を用いてJWT署名を検証します。ユーザーがJWKSエンドポイントを設定している場合、JWT認証器はJWKSエンドポイントから取得した公開鍵リストを用いてJWT署名を検証します。
パスワード認証
EMQXは最もシンプルで一般的なパスワード認証をサポートしています。これはクライアントがユーザー名、クライアントID、対応するパスワードなどの認証情報を提供する方式です。場合によっては、TLS証明書の一部フィールド(例えば証明書のCommon Name)をクライアントの身元情報として使用することもあります。いずれの場合も、これらの認証情報は事前にデータベースに保存されており、パスワードは通常ソルト付きハッシュ形式で格納されます。
EMQXのパスワード認証の仕組みは以下の通りです。クライアントは接続要求時に認証情報を持ち、EMQXはクライアントが提供した認証情報に対応するハッシュ化されたパスワードをデータベースから照会し、一致した場合のみ接続を許可します。 
組み込みデータベースのほか、EMQXはMySQL、PostgreSQL、MongoDB、Redisなどの各種バックエンドデータベースとの連携もサポートしています。
また、HTTPサーバーなどユーザーが開発した外部サービスに認証処理を委譲する設定も可能です。
MQTT 5.0 拡張認証
MQTT 5.0の拡張認証は、基本認証にチャレンジ/レスポンス方式の認証を追加したものです。これにより、SCRAM認証(Salted Challenge Response Authentication Mechanism)やKerberos認証など、より安全な認証機構の利用が可能になります。EMQXの実装では、組み込みデータベースおよび外部HTTPサービスを用いたSCRAMユーザー管理をサポートしています。
PSK認証
EMQXのPSK認証は、証明書ベースのTLSに代わるよりシンプルで安全な認証方法です。クライアントとサーバーが共有する秘密鍵を用いるため、デジタル証明書を必要としません。この機構は、証明書処理のオーバーヘッドが大きいリソース制約のある環境で特に有用です。
EMQX認証器
EMQXは認証機構やバックエンドデータベースに基づき、以下の認証方式(以下「認証器」と呼びます)をサポートしています。
| 機構 | データベース | 説明 |
|---|---|---|
| パスワード認証 | 組み込みデータベース | Mnesiaデータベースを資格情報ストレージとした認証 |
| パスワード認証 | MySQL | MySQLデータベースを資格情報ストレージとした認証 |
| パスワード認証 | PostgreSQL | PostgreSQLデータベースを資格情報ストレージとした認証 |
| パスワード認証 | MongoDB | MongoDBデータベースを資格情報ストレージとした認証 |
| パスワード認証 | Redis | Redisデータベースを資格情報ストレージとした認証 |
| パスワード認証 | LDAP | LDAPサーバーを資格情報ストレージとした認証 |
| パスワード認証 | HTTPサーバー | 外部HTTP APIを用いた資格情報検証認証 |
| JWT | JWTを用いた認証 | |
| SCRAM | 組み込みデータベース | SCRAMを用いた認証 |
| SCRAM | HTTPサーバー | RESP APIベースのSCRAM認証 |
| GSSAPI | Kerberos | Kerberosを用いたGSSAPI認証 |
| ルールベース | Client-infoを用いた認証 |
認証チェーン
EMQXは認証チェーンの作成をサポートしており、複数の認証器を定義された順序で評価できます。チェーン内の各認証器は異なるタイプ(例:1つはHTTP、1つはLDAP、1つは組み込みデータベース)である必要があります。
TIP
現時点でEMQXはMQTTクライアントに対してのみ認証チェーンの作成をサポートしています。ゲートウェイは認証チェーンをサポートせず、単一の認証器を使用してください。
X.509証明書ベースの認証が適用されている場合、認証チェーンの実行前に必ず実行されます。
認証チェーンの動作
認証チェーンが設定されている場合、EMQXはまず最初の認証器から認証情報の取得を試み、失敗した場合は次の認証器に切り替えて処理を続行します。
パスワード認証を例に動作を説明します。
前提条件の評価(設定されている場合)
認証器に前提条件がある場合、EMQXはクライアント属性情報(例:listener、clientid、username)に基づいて式を評価します。- 式が
trueの場合、認証器が呼び出されます。 - そうでない場合、認証器はスキップされます。
- 式が
認証器の実行
- 認証情報が見つかり有効(例:パスワードが正しい)なら、クライアントは認証成功となり接続が許可されます。
- 認証情報が見つかったが無効なら、クライアントはアクセス拒否されます。
- 認証情報が見つからなければ、EMQXは次の認証器に進みます。
無効化された認証器とバックエンド障害の処理
無効化された認証器はスキップされます。認証器のバックエンドが障害(例:データベースが利用不可)を起こした場合、EMQXは設定されたバックエンド障害処理に従い、次の認証器に進むかクライアントを拒否します。フォールバック動作
すべての認証器がスキップされるか認証に失敗した場合、EMQXはデフォルトで接続を拒否します。

認証器の前提条件
EMQX 5.9以降、各認証器に前提条件を割り当てて、特定のクライアントに対して認証器を呼び出すかどうかを制御できます。前提条件はVariform式で、クライアント属性(listener、username、clientidなど)を評価します。式がtrueでなければ認証器はスキップされます。
この機能により認証チェーンに条件分岐ロジックを組み込めます。例えば、異なるリスナー経由で接続するクライアントに異なる認証器を適用するなど、細かな認証制御が可能です。EMQXは適切な場合にのみ認証器を呼び出し、外部システムへの不要なリクエストを回避します。
前提条件でサポートされるクライアント属性
username: クライアントのユーザー名password: クライアントのパスワードclientid: クライアントIDclient_attrs.*: クライアント属性cert_common_name: クライアントTLS証明書のSubjectフィールドcert_subject: クライアントTLS証明書のCommon Name(CN)peersni: TLSクライアントが送信したSNI(Server Name Indication)listener: リスナーID(例:tcp:default)zone: 関連付けられたコンフィグゾーン
前提条件の例
異なるリスナー経由のクライアントを異なる認証器で認証する例:
tcp:defaultのクライアントにHTTP認証器を適用:str_eq(listener, 'tcp:default')ssl:defaultのクライアントにPostgreSQL認証器を適用:str_eq(listener, 'ssl:default')
JWT認証器とパスワード認証器を1つの認証チェーンに組み合わせる場合、JWT認証器に以下の前提条件を設定します。
is_jwt(password)EMQX 6.2.3以降、この前提条件はパスワードが構造的にJWTである場合にのみtrueを返します。JWT認証器はJWTパスワードに対して呼び出され、JWTでないか存在しない場合はスキップされ、次の認証器に処理が移ります。
認証バックエンド障害処理の設定 6.3.3+
authentication_settings.ignore_backend_failures設定は、EMQXが認証バックエンド障害をどのように扱うかを決定します。障害にはバックエンドエラー、不正なレスポンス、前提条件評価エラー、JWT検証キーの未取得、データベースの接続不可、リクエストタイムアウトなどが含まれます。この設定は両方のセキュリティプロファイルに適用されます。
| 値 | legacy | hardened |
|---|---|---|
per_security_profile (デフォルト) | 障害を無視して次の認証器に進む | クライアントを拒否 |
true | 障害を無視して次の認証器に進む | 障害を無視して次の認証器に進む |
false | クライアントを拒否 | クライアントを拒否 |
例えば、上位の設定ソースでこの設定が上書きされていない場合、base.hoconに以下を追加してアクティブなセキュリティプロファイルの動作を維持します。
authentication_settings.ignore_backend_failures = per_security_profileGET /api/v5/authentication/settingsはignore_backend_failuresをJSON文字列"per_security_profile"またはJSONブール値true、falseで返します。PUT /api/v5/authentication/settingsは同じ値を受け付けます。設定がない場合、GETは"per_security_profile"を返します。EMQX 6.3.3以前はブール値でデフォルトはfalseでした。
アップグレード後の保存値の確認
EMQX 6.3.3以前はGET /api/v5/authentication/settingsがデフォルトでignore_backend_failuresをfalseで返していました。APIクライアントが完全なレスポンスをPUTリクエストのボディとして送信した場合、ユーザーが明示的に設定していなくてもfalseが永続化されている可能性があります。EMQX 6.3.3にアップグレード後、保存値がfalseだとlegacyプロファイルで認証バックエンド障害時にクライアント拒否となります。以前のlegacy動作を維持するには、すべてのノードのアップグレード後に値をper_security_profileに設定してください。
ローリングアップグレード時はローリングアップグレードの注意点に従ってください。
外部リソースキャッシュ
EMQXはMySQL、MongoDB、Redisなどの外部バックエンドから取得した認証結果をノードレベルでキャッシュする仕組みを提供しています。このキャッシュは認証結果の検索性能を向上させ、特に高スループット環境で外部リソースへの繰り返しアクセスを削減します。
注意
外部リソースキャッシュは外部データソースにのみ適用されます。組み込みデータベース認証器などローカルソースには適用されません。
外部リソースキャッシュの動作
外部リソースキャッシュはノードレベルで認証結果を保存し、同一ノード上のすべてのクライアントセッションで共有され、外部認証バックエンドへの冗長な問い合わせを回避します。
- クライアントが接続し認証をトリガーする。
- EMQXはキャッシュに以前の結果があるか確認する。
- 有効な結果があればキャッシュヒットとなり、外部バックエンドへの呼び出しは行われない。
- 結果がなければキャッシュミスとなり、EMQXは外部バックエンドに問い合わせる。
- バックエンドから返された結果は将来の利用のためキャッシュに保存され、キャッシュ挿入メトリクスが増加する。
この仕組みはレイテンシ削減、バックエンド負荷軽減、負荷時のシステム応答性維持に寄与します。
外部リソースキャッシュの有効化と設定
EMQXダッシュボードから外部リソースキャッシュを有効化・設定できます。
アクセス制御 -> 認証 に移動します。
右上の 外部リソースキャッシュ設定 ボタンをクリックすると、右側からパネルが表示されます。
パネル内の 外部リソースキャッシュを有効化 ボタンでキャッシュ機能をオン/オフできます。有効化後、以下のキャッシュ設定を行います。
項目名 説明 最大キャッシュアイテム数 ノードあたりのキャッシュエントリ最大数。デフォルト: 1,000,000。最大メモリ使用量 キャッシュのメモリ使用上限。デフォルト: 100 MB。キャッシュTTL キャッシュエントリの有効期間。デフォルト: 1分。更新 をクリックして設定を適用します。
これらの設定はクラスター全体に適用され、すべてのノードで一貫した動作を保証します。
外部リソースキャッシュの状態監視
キャッシュメトリクスを表示し、リアルタイムで使用状況を監視するには:
- External Resource Cache Settings の横にある矢印をクリックし、External Resource Cache Status を選択します。サイドパネルが表示され、キャッシュメトリクスが確認できます。
- ドロップダウンメニューを使用して、ノード単位またはクラスター全体のメトリクスを表示します。
メトリクスには以下が含まれます:
- Memory Usage:キャッシュが現在使用している合計メモリ量。
- Cache Entries:保存されているキャッシュ結果の総数。
- Cache Hits:EMQXがキャッシュ内で有効な結果を見つけ、外部バックエンドへの呼び出しを回避した回数。
- 表示されるメトリクス:現在のレート、5分間の平均、最大レート
- Cache Misses:EMQXがキャッシュ内で結果を探したが見つからず、バックエンドクエリが発生した回数。
- 表示されるメトリクス:現在のレート、5分間の平均、最大レート
- Cache Inserts:ミス後にキャッシュに新たに追加された結果の数。
- 表示されるメトリクス:現在のレート、5分間の平均、最大レート
パネル下部のノードリストでは、クラスター内の各ノードの Memory Usage、Cache Entries、および Cache Hits の概要を確認できます。
パネル右上のボタンで統計情報の更新やリセットが可能です。
スーパーユーザー
通常、認証はクライアントの身元情報の検証のみを行い、特定トピックへのパブリッシュ/サブスクライブ権限は認可システムで判断されます。しかしEMQXはスーパーユーザーロールと権限プリセット機能を提供し、後続のパブリッシュ/サブスクライブ認可処理を支援します。
TIP
権限プリセットはJWT認証およびHTTP認証でサポートされます。現在のクライアントが所有するパブリッシュ/サブスクライブ権限のアクセス制御リスト(ACL)はJWTペイロードやHTTPレスポンスボディに含まれます。認証通過後にクライアントへ権限がプリセットされます。
データベースクエリ、HTTPレスポンス、JWTクレームのis_superuserフィールドでユーザーがスーパーユーザーかどうかを確認できます。
認証結果によるクライアントIDの上書き
MQTTクライアントの場合、認証バックエンドは認証成功結果にclientid_overrideを返すことができます。値は空でない文字列で完全な置換用クライアントIDを含みます。EMQXは認証後、クライアントセッション開始前にこれを適用します。フィールドが存在しないか空の場合は、従来のクライアントIDを保持します。
この仕組みは、認証バックエンドから返されるテナント識別子など、認証後にのみ利用可能な信頼情報に基づいてクライアントIDを置換する際に使用します。マルチテナント環境では、EMQXがテナントIDを有効なクライアントIDに含め、異なるテナントのクライアントが同一の元クライアントIDを使ってもセッション競合を回避できます。認証前に接続情報から置換クライアントIDを構築できる場合は、代わりにmqtt.clientid_overrideを使用してください。仕組みの選択、実行順序、マルチテナント環境での失敗時挙動の詳細はクライアントID分離を参照してください。
MQTT接続ではクライアントIDの上書き機構は1つだけ使用してください。両方設定されている場合、認証結果の上書きが後に実行され、mqtt.clientid_overrideで生成されたクライアントIDを置換します。
WARNING
EMQX 6.3.1以降、ゲートウェイプロトコルは認証結果によるクライアントIDの上書きをサポートしません。ゲートウェイ経由のクライアントではclientid_overrideを無視し、ゲートウェイプロトコルで決定されたクライアントIDを保持し、gateway_authn_clientid_override_not_supportedの警告をログに出力します。
認証バックエンドの設定
clientid_overrideは認証結果のフィールドであり、すべての認証器共通のダッシュボード設定ではありません。各認証バックエンドで以下のように設定します。
| 認証バックエンド | clientid_overrideの提供方法 |
|---|---|
| HTTP | 成功したJSONレスポンスのトップレベル文字列フィールドとして返す。 |
| JWT | JWTペイロードのトップレベル文字列クレームとして追加する。 |
| LDAP | LDAP属性に値を格納し、Client ID Override Attributeに属性名を設定。デフォルトはclientIdOverride。 |
| MongoDB | ドキュメントフィールドに値を格納し、Client ID Override Fieldにフィールド名を設定。デフォルトはclientid_override。 |
| MySQL | クエリ結果のカラム名clientid_overrideで返す。 |
| PostgreSQL | クエリ結果のカラム名clientid_overrideで返す。 |
| Redis | clientid_overrideフィールドに値を格納し、クエリコマンドに含める。 |
置換クライアントIDをクライアントID分離に使用する場合は、グローバルに一意であることを保証してください。
パスワードハッシュ化
パスワードを平文で保存すると、データベースを覗いた誰もがパスワードを読めてしまいます。したがってパスワードはハッシュ化アルゴリズムを用いて生成したハッシュ値として保存することが推奨されます。EMQXは様々なセキュリティ要件に対応する複数のパスワードハッシュ化アルゴリズムをサポートしています。
また、EMQXはソルトの追加もサポートしており、ソルトを加えたユニークなハッシュ(password_hash)は多様な攻撃から保護します。
ワークフロー
パスワードハッシュ化のワークフローは以下の通りです。
- EMQX認証器は設定されたクエリ文を用いて、データベースからハッシュ化パスワードやソルト値を含む認証情報を取得する。
- クライアントが接続を試みると、EMQX認証器はクライアントが提供したパスワードを設定されたハッシュアルゴリズムと取得したソルト値でハッシュ化する。
- EMQX認証器は1で取得したハッシュパスワードと2で計算したハッシュ値を比較し、一致すれば認証を許可する。
EMQXがサポートするハッシュアルゴリズムは以下の通りです。
# シンプルなアルゴリズム
password_hash_algorithm {
name = sha256 # plain, md5, sha, sha512
salt_position = suffix # prefix, disable
}
# bcrypt
password_hash_algorithm {
name = bcrypt
}
# pbkdf2
password_hash_algorithm {
name = pbkdf2
mac_fun = sha256 # md4, md5, ripemd160, sha, sha224, sha384, sha512
iterations = 4096
dk_length = 32 # 任意、単位: バイト
}アルゴリズムによって性能差が大きいため、用途に応じて選択してください。参考として、4コア8GBマシンで各アルゴリズムを100回実行した平均実行時間の比較を以下に示します。

認証プレースホルダー
EMQXはクエリ文やHTTPリクエスト内でプレースホルダーを使用できます。認証時にこれらは実際のクライアント情報に置換され、現在のクライアントに合致したクエリやリクエストが構築されます。
有効なプレースホルダーは${PATH.TO.VALUE}の形式で、PATH.TO.VALUEはオブジェクト内の値へのドット区切りパスです。使用可能な文字は英数字、ドット(.)、アンダースコア(_)です。サポート外の文字を含むプレースホルダーは単なるテキストとして扱われます。
例えば、EMQX MySQL認証器のデフォルトクエリSQLは${username}プレースホルダーを使用しています。
SELECT password_hash, salt FROM mqtt_user where username = ${username} LIMIT 1クライアント(名前:emqx_u)が接続要求を送ると、構築されるクエリ文は以下のようになります。
SELECT password_hash, salt FROM mqtt_user where username = 'emqx_u' LIMIT 1EMQXがサポートするプレースホルダーは以下の通りです。
${clientid}: 実行時にクライアントIDに置換されます。通常はCONNECTパケットでクライアントが明示的に指定します。use_username_as_clientidやpeer_cert_as_clientidが有効な場合は、ユーザー名や証明書のフィールド、証明書内容で上書きされます。${username}: 実行時にユーザー名に置換されます。CONNECTパケットのUsernameフィールドから取得します。peer_cert_as_usernameが有効な場合は証明書のフィールドや内容で上書きされます。${password}: 実行時にパスワードに置換されます。CONNECTパケットのPasswordフィールドから取得します。${peerhost}: 実行時にクライアントの送信元IPアドレスに置換されます。Proxy Protocolが有効な場合はプロキシが報告する送信元IPを使用します。${peerport}: EMQX 6.3.0以降、実行時にクライアントの送信元ポート番号(例:51544)に置換されます。Proxy Protocolが有効な場合はプロキシが報告する送信元ポートを使用します。${peername}: EMQX 6.3.0以降、実行時にクライアントの送信元IPアドレスとポート番号に置換されます。IPv4の場合はIP:port形式(例:192.168.0.1:51544)、IPv6の場合は角括弧なし(例:2001:db8::1:51544)です。Proxy Protocolが有効な場合はプロキシが報告するIPとポートを使用します。${cert_subject}: 実行時にクライアントTLS証明書のSubjectに置換されます。ロードバランサーがTCPリスナーにクライアント証明書情報を送信する場合はProxy Protocol v2を使用してください。${cert_common_name}: 実行時にクライアントTLS証明書のCommon Nameに置換されます。ロードバランサーがTCPリスナーにクライアント証明書情報を送信する場合はProxy Protocol v2を使用してください。${client_attrs.NAME}: クライアント属性。NAMEは事前定義された設定に基づく属性名に置換されます。詳細はMQTTクライアント属性を参照してください。${zone}: 実行時にクライアントのゾーンに置換されます。${zone}プレースホルダーは認証テンプレートで直接使用可能です。ゾーン設定の詳細はゾーンオーバーライドを参照してください。例えば、以下のACLルールは
${zone}を用いてクライアントの割り当てゾーンに基づき動的に権限を適用します。{allow, all, all, ["${zone}/${username}/#"]}
TIP
${peerhost}および${peerport}プレースホルダーは非推奨です。後方互換性のためサポートは継続しています。新規テンプレートでは対応する箇所で${peername}を使用してください。
認証の設定
EMQXは認証の設定方法として、ダッシュボード、設定ファイル、HTTP APIの3種類を提供しています。
ダッシュボードによる認証設定
EMQXダッシュボードは認証器の設定や状態確認を直感的に行える方法です。例えば以下のスクリーンショットのように、組み込みデータベースベースのパスワード認証とJWT認証の2つの認証器を設定しています。

設定ファイルによる認証設定
設定ファイルでもEMQX認証器を設定可能です。
例えば以下のauthenticationフィールドのように複数の認証器からなる認証チェーンを作成し、設定ファイル内の順序で認証器が実行されます。
# base.hocon
# すべてのMQTTリスナーに対するグローバル認証チェーン
authentication = [
...
]
listeners.tcp.default {
...
# 指定したMQTTリスナーに対する認証チェーン
authentication = [
...
]
}
gateway.stomp {
...
# すべてのSTOMPリスナーに対するグローバル認証器
authentication = {
...
}
}認証器の種類によって設定項目は異なります。詳細は設定章を参照してください。
HTTP APIによる認証設定
設定ファイルに比べ、HTTP APIはより便利でランタイム更新に対応しており、設定変更をクラスター全体に自動同期できます。
EMQX認証APIを使い、グローバル認証器の作成や特定認証器の設定更新が可能です。
/api/v5/authentication: グローバルMQTT認証管理用APIエンドポイント/api/v5/gateway/{protocol}/authentication: 他アクセスプロトコルのグローバル認証管理用APIエンドポイント/api/v5/gateway/{protocol}/listeners/{listener_id}/authentication: 他アクセスプロトコルのリスナー認証管理用APIエンドポイント
認証器ID
特定の認証器を操作するには、上記エンドポイントに認証器IDを付加します(例:/api/v5/authentication/{id})。メンテナンスを容易にするため、IDはEMQXが自動生成してAPIで返すのではなく、以下の仕様に従います。
<mechanism>:<backend>または
<mechanism>例:
password_based:built_in_databasejwtscram:built_in_database
リスナーIDにも同様の規則があります。
<transport_protocol>:<name>ゲートウェイリスナーIDはプロトコル名を前に付けます。
<protocol>:<transport_protocol>:<name>認証器IDおよびリスナーIDはURLで使用する際、URLエンコード規則に従う必要があります。例えば、:は%3Aに置換します。
PUT /api/v5/authentication/password_based%3Abuilt_in_databaseデータ操作API
組み込みデータベースおよびMQTT 5.0拡張認証を用いた認証では、認証データの作成、更新、削除、一覧取得などを管理するHTTP APIを提供しています。詳細はHTTP APIで認証データを管理するを参照してください。
詳細なAPIリクエストやパラメータはHTTP APIを参照してください。