External Auth/ACL モジュール状態異常アラート

External Auth/ACL モジュール状態異常アラートは、EMQX が HTTP、MySQL、Redis、PostgreSQL、JWT などの設定された外部認証または認可サービスとの通信中にエラーが発生したことを示します。

この状態はクライアントが認証または認可を完了できなくなり、接続失敗やアクセス制御エラーを引き起こす可能性があります。

ネットワーク接続障害

症状

EMQX が外部認証または認可サービスへのネットワーク接続を確立できません。

デプロイメントログ に timeout や connection refused といったエラーが表示される場合は、EMQX と外部サービス間の接続問題を示しています。

主な原因

• VPCピアリング、PrivateLink、または NAT ゲートウェイが設定されていない、もしくは誤って設定されている。
• 外部サービスの IP アドレスまたはポートが誤っている。
• ファイアウォールやセキュリティグループが必要なポートをブロックしている。

対処方法

• VPCピアリング、PrivateLink、NAT ゲートウェイが正しく設定されており、アクティブであることを確認してください。
• 外部サービスの IP アドレスとポートを確認してください。
• ファイアウォールやセキュリティグループのルールを確認し、EMQX が外部サービスにアクセスできることを確認してください。
• 外部認証サービスに対して高可用性およびロードバランシングを導入し、単一障害点を回避してください。

外部サービスの利用不可または異常状態

症状

外部認証または認可サービスが利用不可または異常状態であるため、EMQX が有効な応答を受信できません。

デプロイメントログ に unrecoverable_error や disconnected といったエラーが表示される場合は、外部サービスの問題を示しています。

主な原因

• 外部サービスが停止している、またはプロセスが予期せず終了した。
• 外部サービスが過負荷で応答できない。
• データベース接続プールが枯渇し、新しい接続を拒否している。

対処方法

• MySQL、PostgreSQL、Redis、HTTPサービスなど外部サービスの状態とログを確認してください。
• CPU、メモリ、接続使用状況を監視し、リソース枯渇をチェックしてください。
• 必要に応じてデータベースサービスの接続プール容量を増やしてください。

外部認証または認可設定の誤り

症状

外部サービスが EMQX が解析できない形式や内容のデータを返します。

デプロイメントログ に invalid_response や decode error といったエラーが表示される場合は、設定ミスや応答形式の誤りを示しています。

主な原因

• HTTP API の応答に EMQX が要求する result フィールドが欠落している。
• データベースクエリが無効、または結果が返ってこない。
• 設定された JWT キーがクライアントの使用するキーと一致しない。

対処方法

• 外部 HTTP API の応答が EMQX の認証・認可 API 要件に準拠していることを確認してください。
• データベースクエリが有効で、期待される結果を返すことを確認してください。
• テスト環境でデバッグモードを有効にし、外部サービスの応答が EMQX で正しく解析できることを確認してください。

JWT 設定の問題

症状

JWT を認証または認可に使用している場合、JWT 設定とクライアントのトークン生成方法の不一致や無効なトークンにより、このアラートが発生することがあります。

主な原因

• キー不一致：クライアントが署名に使用するキーと EMQX の検証キーが異なる。ログに通常 JWT verification failed が含まれます。
• アルゴリズム不一致：クライアントが HS256 を使用しているのに対し、EMQX は RS256 など別のアルゴリズムを設定している。ログに通常 unsupported algorithm が含まれます。
• 期限切れまたは無効なトークン：クライアントが期限切れまたは無効な JWT を使用している。ログに通常 exp claim is expired が含まれます。

対処方法

• JWT デコードツールや以下のコマンドでトークンを検証してください。

  jwt decode <token>

• JWT のヘッダー、ペイロード、署名を確認してください。

• EMQX の algorithm と public_key 設定がクライアントの JWT 設定と一致していることを確認してください。

• 適切な JWT 有効期限を設定し、クライアント側でトークンを定期的に更新してください。

トラブルシューティング

1. ネットワーク接続を確認します。EMQX テクニカルサポートと連携し、curl、ping、nc、telnet などのツールを使って EMQX ノードから外部サービスに到達できるか確認してください。
2. 外部サービスを確認します。データベースや HTTP サービスが稼働しているか、接続上限に達していないか、期待される JSON 形式と HTTP ステータスコードを返しているかを確認してください。
3. デプロイメントログ を開き、Error Type を Authentication または Authorization に設定し、エラー詳細から原因を特定してください。
4. JWT の場合、algorithm や public_key などの設定がクライアントと一致しているか確認し、テストトークンをデコードして有効期限や必要なクレームの有無をチェックしてください。