JWT認証

JSON Web Token (JWT) はトークンベースの認証機構です。サーバーがクライアントの認証情報やセッション情報を保持する必要がありません。EMQXはユーザー認証にJWTを使用することをサポートしています。

前提条件

EMQX認証の基本概念の知識

認証の原理

クライアントは接続要求にJWTを含め、EMQXは事前に設定されたシークレットまたは公開鍵を使ってJWTの署名を検証します。ユーザーがJWKSエンドポイントを設定している場合、JWT認証機構はJWKSエンドポイントから取得した公開鍵リストを用いてJWTの署名を検証します。

署名検証が成功すると、JWT認証機構はクレームの検証に進みます。JWT認証機構はiat（発行時刻）、nbf（有効開始時刻）、exp（有効期限）などのクレームに基づいてJWTの有効性を積極的にチェックします。追加のカスタムクレームも検証対象として指定可能です。署名とクレームの両方の検証が成功した場合にのみ、クライアントにアクセスが許可されます。

EMQXバージョン5.7.0以降では、JWT認証にJWTの有効期限切れ後にクライアントを切断するオプションが追加されました。設定パラメータdisconnect_after_expireはデフォルトでtrueに設定されています。JWTの有効期限切れ後もクライアントを接続状態に保つ場合は、このパラメータをfalseに設定してください。

ベストプラクティス

JWT認証機構は基本的にJWTの署名のみを検証するため、クライアントの正当性を保証するものではありません。

ベストプラクティスとしては、独立した認証サーバーをデプロイし、クライアントはまず認証サーバーにアクセスして認証サーバーがクライアントの正当性を検証し、正当なクライアントに対してJWTを発行し、そのJWTを用いてEMQXに接続する方法が推奨されます。

TIP

JWTのペイロードはBase64エンコードされているだけなので、JWTを入手した誰でもBase64デコードにより元の情報を取得できます。したがって、JWTのペイロードに機密データを保存することは推奨されません。

JWTの漏洩や盗難の可能性を減らすために、適切な有効期限を設定し、TLSを有効化してクライアント接続を暗号化することを推奨します。

アクセス制御リスト（オプション）

アクセス制御リスト（ACL）は認証結果の拡張機能で、ログイン後のクライアントの権限を制御します。JWTにはaclフィールドを含めてクライアントの権限を指定できます。

詳細はアクセス制御リスト（ACL）をご参照ください。

クライアント属性

EMQX v5.7.0以降では、JWTペイロードのオプションフィールドclient_attrsを使用してクライアント属性を設定できます。キーと値はどちらも文字列型である必要があります。

例：

{
  "exp": 1654254601,
  "username": "emqx_u",
  "client_attrs": {
      "role": "admin",
      "sn": "10c61f1a1f47"
  }
}

ダッシュボードでのJWT認証設定

1. 左側のナビゲーションメニューから Access Control -> Authentication を選択します。

2. Authentication ページの右上にある Create をクリックし、Mechanism で JWT を選択して Next をクリックします。バックエンドの選択はスキップし、Configuration タブに進みます。

   

3. 以下のオプションを設定します：

   • JWT From：クライアント接続要求のどこにJWTがあるかを指定します。選択肢はpasswordとusernameで、MQTTクライアントのCONNECTパケットのPasswordまたはUsernameフィールドに対応します。

   • Algorithm：JWTの暗号化アルゴリズムを指定します。選択肢はhmac-basedとpublic-keyで、それぞれ異なる設定が必要です。

     • hmac-based：JWTの署名生成と検証に対称鍵を使用します。HS256、HS384、HS512がサポートされています。設定項目は以下の通りです：

       • Secret：署名検証に使用する鍵で、署名生成時と同じものを指定します。
       • Secret Base64 Encode：SecretがBase64エンコードされているかどうかを設定し、EMQXが署名検証時にデコードするかを決定します。

     • public-key：JWTの署名生成に秘密鍵を使い、検証に公開鍵を使います。RS256、RS384、RS512、ES256、ES384、ES512がサポートされています。設定項目は以下の通りです：

       • Public Key：署名検証に使用するPEM形式の公開鍵を指定します。

   • Precondition：Variform式で、このJWT認証機構をクライアント接続に適用するかどうかを制御します。クライアントの属性（username、clientid、listenerなど）に対して式が評価され、結果が文字列の"true"の場合のみ認証機構が呼び出されます。詳しくは認証の前提条件をご覧ください。

   • Disconnect After Expiration：JWTの有効期限切れ後にクライアントを切断するかどうかを設定します。デフォルトで有効です。

   • Payload：ユーザーが追加で検証したいクレームを指定します。複数のキーと値のペアをClaimとExpected Valueフィールドで定義できます。キーはJWT内のクレーム名と一致させる必要があり、値は実際のクレーム値と比較されます。現在サポートされているプレースホルダーは${clientid}と${username}です。

4. Create をクリックして設定を完了します。

EMQXはJWKSエンドポイントから最新のJWKSを定期的に取得することもサポートしています。JWKSは認可サーバーが発行しRSAまたはECDSAアルゴリズムで署名されたJWTを検証するための公開鍵の集合です。この機能を利用する場合は、JWKS設定ページに切り替えてください。

JWKS固有の設定項目は以下の通りです：

• JWKS Server：EMQXがJWKSを問い合わせるサーバーのエンドポイントアドレスを指定します。エンドポイントはGETリクエストに対応し、仕様に準拠したJWKSを返す必要があります。
• JWKS Refresh Interval：JWKSの更新間隔、すなわちEMQXがJWKSを問い合わせる周期を指定します。
• Headers：JWKSサーバーへのリクエストに含める追加のHTTPヘッダーを指定します。これにより、サーバーの要件に応じてリクエストを適切にフォーマットできます。キーと値のペアを追加可能です。例：
  • Key：Accept
  • Value：application/json

Create をクリックして設定を完了します。