EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

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 を発行します。その後、クライアントは取得した JWT を用いて EMQX に接続します。

TIP

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

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

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

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

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

クライアント属性 ​

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

例：

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

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

  1. 左側ナビゲーションメニューから アクセス制御 -> 認証 を選択します。

  2. 認証 ページの右上にある 作成 をクリックし、メカニズム に JWT を選択して 次へ をクリックします。バックエンド選択はスキップして、設定 タブに進みます。

    JWT

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

    • JWT From：クライアント接続リクエストのどこに JWT があるかを指定します。選択肢は password と username で、MQTT クライアントの 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、password、clientid、listener など）に対して評価され、結果が文字列の "true" の場合のみ認証器が呼び出されます。そうでなければスキップされます。詳細は 認証器の前提条件 を参照してください。

      例：JWT クライアントとパスワード認証クライアントの両方を同じ認証チェーンで処理する場合、is_jwt(password) を使用します。

      EMQX 6.2.3 以降、is_jwt(password) はパスワードが構造的に JWT の場合のみ true を返します。通常のパスワード、パスワード未設定、形式不正な値は false を返し、EMQX は JWT 認証器をスキップして次の認証器に処理を委ねます。構造的に有効な JWT でも署名またはクレーム検証に失敗した場合は JWT 認証器で処理され拒否されます。

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

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

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

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

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