EMQX 4.4 と EMQX 5.1 間の認証／認可の非互換性

本ページでは、EMQX 4.4 と EMQX 5.1 間の認証および認可設定の互換性情報を紹介します。

共通の非互換変更点

SSL オプション

EMQX 5.1 では、MySQL、PostgreSQL、MongoDB、Redis などの外部リソースにアクセスする際や、HTTPS 経由でのパスワード認証を利用する場合に TLS を有効化するオプションが提供されています。詳細は 外部リソースアクセスのための TLS を参照してください。

プレースホルダー

MySQL、PostgreSQL、MongoDB、Redis、外部リクエストの HTTP、JWT のデータ補間をサポートするバックエンドは、従来の %X プレースホルダーから ${variable} 形式のプレースホルダーに変更されました。

認証

共通の変更点（すべての認証ソース）

パスワードハッシュ

組み込みデータベース、MySQL、PostgreSQL、MongoDB、Redis のすべてのパスワードベースのプロバイダーは、同一の password_hash オプションを持ち、同様の設定方法となりました。詳細は パスワードハッシュ を参照してください。

リスナーごとの認証

EMQX 5.1 では、4.4 とは異なり、各 MQTT リスナーごとに独自の認証設定が可能です。さらに、enable_authn リスナーオプションが追加されました：

• enable_authn=true（デフォルト）は認証チェーンに認証を委譲します。
• enable_authn=false はリスナーの認証を完全に無効化します。
• enable_authn=quick_deny_anonymous は true と同様ですが、資格情報なしの接続クライアントを即座に拒否します。

匿名アクセス機構の廃止

EMQX 5.1 では明示的な allow_anonymous 設定がなくなりました。すべてのクライアントはデフォルトで接続が許可されます。認証器を追加・有効化すると、EMQX はクライアントの認証を試みます。匿名アクセスを許可するには、グローバルまたはリスナー固有の認証チェーンからすべての認証器を削除または無効化してください。

認証チェーンを通過しても、いずれの認証器も接続許可を判断できない場合は接続が拒否されます。

bypass_auth_plugins 設定も削除されました。認証なしで全クライアントの接続を許可したい場合は、listeners.{type}.{name}.enable_authn = false を設定してください。

組み込みデータベース（Mnesia）

• Mnesia は「組み込み」データベースと呼称され、設定にユーザーレコードはありません。
• password_hash は password_hash_algorithm に変更され、{name = Algo, salt_position = prefix} の形式となりました。詳細は パスワードハッシュ を参照してください。
• user_id_type は MQTT ユーザー識別子として clientid または username のどちらを使うかを指定します。混在は許可されません。
• 認証データレコード管理用の REST API が変更されました。詳細は POST /authentication/{id}/users の API ドキュメントを参照してください。
• 旧バージョンからのデータインポートは POST /authentication/{id}/import_users API を利用してください。

例

EMQX 4.4

auth.mnesia.password_hash = sha256

EMQX 5.1

authentication {
   backend = built_in_database
   mechanism = password_based
   password_hash_algorithm {
      name = sha256
      salt_position = prefix
   }
   user_id_type = username
   enable = true
}

組み込みデータベース（強化認証）

• EMQX 4.4 で使用されていた SHA1 ハッシュは廃止されました。algorithm パラメータで sha512 または sha256 を選択してください。
• iteration_count でハッシュ関数の計算回数を指定可能です（4.4 では暗黙的に 4096 回）。

例

EMQX 4.4

# 設定なし

EMQX 5.1

{
    mechanism = scram
    backend = built_in_database
    enable = true

    algorithm = sha512
    iteration_count = 4096
}

Redis

  mechanism = password_based
  backend = redis

• type は redis_type に変更されました。

  • single タイプの場合、server は servers に変更。
  • sentinel タイプの場合も同様に server → servers。
  • cluster タイプでは database オプションは廃止。

• database は cluster タイプ以外で引き続き使用可能。

• pool は pool_size に変更。

• password は引き続き password。

• query_timeout は廃止。

• ssl.* オプションは共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

• auth_cmd は cmd に変更。Redis ハッシュデータ構造のみサポートし、HGET と HMGET コマンドを使用可能。コマンド内で ${var} 形式のプレースホルダーを使用してください。コマンドは最低でも password（4.x 互換）または password_hash フィールドを取得し、任意で salt と is_superuser フィールドも取得してください。

• super_cmd は廃止。スーパーユーザー権限を付与する場合は、cmd のクエリに is_superuser フィールドを含めてください。

  Details

  # NG例
  GET emqx_user:${username}
  # NG例
  HMGET emqx_user:${username} passwd
  
  # 良い例
  HMGET emqx_user:${username} password_hash
  
  # 良い例
  HMGET emqx_user:${username} password_hash is_superuser

• password_hash は共通の password_hash_algorithm パラメータを使用。

障害時に Redis へ自動再接続するために auto_reconnect を利用可能です。

例

EMQX 4.4

auth.redis.type = single
auth.redis.server = 127.0.0.1:6379
auth.redis.pool = 8
auth.redis.database = 0
auth.redis.password = pass
password salt
auth.redis.auth_cmd = HMGET mqtt_user:%u password salt

auth.redis.password_hash = salt,sha256

auth.redis.ssl = on
auth.redis.ssl.cacertfile = path/to/your/cafile.pem
auth.redis.ssl.certfile = path/to/your/certfile
auth.redis.ssl.keyfile = path/to/your/keyfile
auth.redis.ssl.verify = true
auth.redis.ssl.server_name_indication = myredis

EMQX 5.1

authentication {
  mechanism = password_based
  backend = redis
  enable = true

  redis_type = single
  server = "127.0.0.1:6379"

  password_hash_algorithm {
      name = sha256
      salt_position = prefix
  }

  cmd = "HMGET mqtt_user:${username} password salt"
  database = 0
  password = "pass"
  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = myredis
  }
}

MySQL

  backend = mysql
  mechanism = password_based

• server、username、password、database、query_timeout は継続使用可能。

• pool は pool_size に変更。

• ssl.* オプションは共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

• password_hash は共通の password_hash_algorithm パラメータに変更。

• auth_query は query に変更。${var} 形式のプレースホルダーを使用してください。クエリは最低でも password または password_hash カラムを取得し、任意で salt と is_superuser カラムも取得してください。

• super_query は廃止。スーパーユーザー権限を付与する場合は、認証 SQL 結果に is_superuser フィールドを含めてください。

  SELECT
    password as password_hash,
    salt,
    is_superuser
  FROM mqtt_user
    where username = ${username} LIMIT 1

障害時に MySQL へ自動再接続するために auto_reconnect を利用可能です。

例

EMQX 4.4

auth.mysql.server = 127.0.0.1:3306
auth.mysql.pool = 8
auth.mysql.username = dbuser
auth.mysql.database = mqtt

auth.mysql.query_timeout = 5s

auth.mysql.auth_query = select password_hash as password from mqtt where username = '%u' limit 1
auth.mysql.super_query = select is_superuser from mqtt where username = '%u' limit 1

auth.mysql.ssl = on
auth.mysql.ssl.cacertfile = path/to/your/cafile.pem
auth.mysql.ssl.certfile = path/to/your/certfile
auth.mysql.ssl.keyfile = path/to/your/keyfile
auth.mysql.ssl.verify = true
auth.mysql.ssl.server_name_indication = mymysql

EMQX 5.1

authentication {
  backend = mysql
  mechanism = password_based

  enable = true

  server = "127.0.0.1:3306"
  username = "dbuser"
  database = "mqtt"
  password = "dbpass"
  pool_size = 8

  password_hash_algorithm {
      name = sha256
      salt_position = prefix
  }

  query = "SELECT password_hash, salt, is_superuser FROM mqtt where username = ${username} LIMIT 1"
  query_timeout = "5s"

  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mymysql
  }
}

PostgreSQL

  mechanism = password_based
  backend = postgresql

• server、username、password、database は継続使用可能。

• query_timeout、encoding は廃止。

• pool は pool_size に変更。

• ssl.* オプションは共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

• password_hash は共通の password_hash_algorithm パラメータに変更。

• auth_query は query に変更。${var} 形式のプレースホルダーを使用してください。クエリは最低でも password または password_hash カラムを取得し、任意で salt と is_superuser カラムも取得してください。

• super_query は廃止。スーパーユーザー権限を付与する場合は、認証 SQL 結果に is_superuser フィールドを含めてください。

  SELECT
    password as password_hash,
    salt,
    is_superuser
  FROM mqtt_user
    where username = ${username} LIMIT 1

例

EMQX 4.4

auth.pgsql.server = 127.0.0.1:5432
auth.pgsql.pool = 8
auth.pgsql.username = root
auth.pgsql.password = dbpass

auth.pgsql.database = mqtt
auth.pgsql.encoding = utf8

auth.pgsql.auth_query = select password, salt from mqtt_user where username = '%u' limit 1
auth.pgsql.password_hash = salt,sha256
auth.pgsql.super_query = select is_superuser from mqtt_user where username = '%u' limit 1

auth.pgsql.ssl = on
auth.pgsql.ssl.cacertfile = path/to/your/cafile.pem
auth.pgsql.ssl.certfile = path/to/your/certfile
auth.pgsql.ssl.keyfile = path/to/your/keyfile
auth.pgsql.ssl.verify = true
auth.pgsql.ssl.server_name_indication = mypgsql

EMQX 5.1

authentication {
  backend = postgresql
  mechanism = password_based

  enable = true

  server = "127.0.0.1:5432"
  username = "root"
  database = "mqtt"
  password = "dbpass"
  pool_size = 8

  password_hash_algorithm {
      name = sha256
      salt_position = prefix
  }

  query = "SELECT password_hash, salt, is_superuser FROM mqtt_user where username = ${username} LIMIT 1"

  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mypgsql
  }
}

MongoDB

mechanism = password_based
backend = mongodb

• type は mongo_type に変更。値は single、rs、sharded のいずれか。未定義値は廃止。

• server

  • rs、sharded タイプは servers
  • single タイプは server

• srv_record、username、password、auth_source、database、w_mode、topology、collection は継続使用可能。

• r_mode は rs タイプのみ有効。

• pool は pool_size に変更。

• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

• auth_query.selector は filter に変更。文字列ではなく、セレクター全体のデータ構造を指定します。${var} 形式のプレースホルダーはセレクター値に使用可能。

• auth_query.salt_field は salt_field に変更。

• auth_query.super_field は is_superuser_field に変更。

• super_query は廃止。filter で取得するドキュメントに is_superuser_field を含めてください。

  Details

  authentication = [
    {
      ...
      mechanism = "password_based"
      backend = "mongodb"
      # is_superuser_field = "is_superuser"
    }
  ]

• password_hash は共通の password_hash_algorithm パラメータに変更。

• query_timeout は廃止。

例

EMQX 4.4

auth.mongo.type = single
auth.mongo.srv_record = false
auth.mongo.server = 127.0.0.1:27017
auth.mongo.pool = 8
auth.mongo.username = user
auth.mongo.password = pass
auth.mongo.auth_source = admin
auth.mongo.database = mqtt
auth.mongo.query_timeout = 5s

auth.mongo.ssl = on
auth.mongo.ssl.cacertfile = path/to/your/cafile.pem
auth.mongo.ssl.certfile = path/to/your/certfile
auth.mongo.ssl.keyfile = path/to/your/keyfile
auth.mongo.ssl.verify = true
auth.mongo.ssl.server_name_indication = mymongo

auth.mongo.w_mode = unsafe

auth.mongo.topology.pool_size = 1
auth.mongo.topology.max_overflow = 0

## auth.mongo.auth_query.password_hash = salt,sha256

auth.mongo.auth_query.collection = mqtt_user
auth.mongo.auth_query.password_field = password_hash

auth.mongo.auth_query.selector = username=%u, clientid=%c

auth.mongo.super_query.collection = mqtt_user
auth.mongo.super_query.super_field = is_superuser
auth.mongo.super_query.selector = username=%u, clientid=%c

EMQX 5.1

authentication {
  mechanism = password_based
  backend = mongodb
  enable = true

  password_hash_algorithm {
    name = sha256
    salt_position = prefix
  }

  collection = "mqtt_user"
  filter { username = "${username}", clientid = "${clientid}" }

  password_hash_field = "password_hash"
  salt_field = "salt"
  is_superuser_field = "is_superuser"

  mongo_type = single
  server = "127.0.0.1:27017"

  database = "mqtt"
  username = "emqx"
  password = "pass"

  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mymongo
  }

  topology {
    pool_size = 1
    max_overflow = 0
  }
}

JWT

mechanism = jwt

• secret、from、verify_claims、acl_claim_name、refresh_interval は継続使用可能。
• pubkey は public_key に変更。
• jwks は endpoint に変更。
• signature_format は廃止。

verify_claims 内のセレクター値には %X ではなく ${var} 形式のプレースホルダー（${username} や ${clientid}）を使用してください。

追加パラメータ：

• use_jwks: JWKS からキーを取得するかどうか
• algorithm: 署名検証に使うアルゴリズムタイプ（public-key または hmac-based）
• secret_base64_encoded: シークレットのフォーマット指定
• pool_size: JWKS サーバーへの接続数
• ssl: JWKS サーバー接続用の SSL オプション

すべてのパラメータ組み合わせが許可されているわけではありません。

EMQX 4.x は public key、hmac secret、jwks を同時にサポートしていましたが、EMQX 5.1 では一度に一つのアルゴリズムのみをグローバル設定で指定します。use_jwks と algorithm によって利用可能なパラメータセットが決まります：

• use_jwks=true かつ algorithm=public-key：endpoint、pool_size、refresh_interval、ssl
• use_jwks=false かつ algorithm=public-key：public_key
• use_jwks=false かつ algorithm=hmac-based：secret、secret_base64_encoded

use_jwks=true かつ algorithm=hmac-based は無効です。

例

EMQX 4.4

auth.jwt.jwks = https://127.0.0.1:8080/jwks
auth.jwt.jwks.refresh_interval = 5m
auth.jwt.from = password

auth.jwt.verify_claims = on

auth.jwt.verify_claims.username = %u

auth.jwt.acl_claim_name = acl

EMQX 5.1

{
  mechanism = jwt
  from = password,
  acl_claim_name = acl
  use_jwks = true
  algorithm = "public-key"
  verify_claims = {
    username = "${username}
  }

  ssl {
    enable = true
  }

  endpoint = "https://127.0.0.1:8080/jwks"
}

HTTP

mechanism = password_based
backend = http

• method、pool_size、connect_timeout、enable_pipelining は継続使用可能。
• auth_req.url は url に変更。
• auth_req.headers は headers に変更。
• auth_req.params は body に変更。
• timeout は request_timeout に変更。
• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。
• super_req は廃止。スーパーユーザー権限はサービスレスポンス内の is_superuser フィールドで提供してください。

4.4 とは異なり、url、headers、body パラメータでプレースホルダーが使用可能です。

5.1 では body は文字列ではなくマップであり、POST リクエストでは JSON または X-WWW-Form-Urlencoded 形式でシリアライズされ、GET リクエストではクエリパラメータとして送信されます。

4.4 とは異なり、HTTP 認証は成功した HTTP ステータスコード（2XX）のレスポンスのみを尊重し、認証結果は HTTP ステータスコードではなくレスポンスボディ内の JSON フィールド（result）から判定されます。

Details

成功レスポンスステータスコード:

200 または 204

リクエスト失敗や他のステータスコードの場合は認証器は無視されます。

成功レスポンスボディ（JSON）:

名前	型	必須	説明
result	Enum	必須	`allow
is_superuser	Boolean	任意

{
  "result": "allow",
  "is_superuser": true
}

例

EMQX 4.4

auth.http.auth_req.url = http://127.0.0.1:80/mqtt/auth
auth.http.auth_req.method = post
auth.http.auth_req.headers.content_type = application/x-www-form-urlencoded

auth.http.auth_req.params = clientid=%c,username=%u,password=%P

auth.http.timeout = 5s

auth.http.connect_timeout = 5s
auth.http.pool_size = 32

auth.http.enable_pipelining = 100

auth.http.ssl = on
auth.http.ssl.cacertfile = path/to/your/cafile.pem
auth.http.ssl.certfile = path/to/your/certfile
auth.http.ssl.keyfile = path/to/your/keyfile
auth.http.ssl.verify = true
auth.http.ssl.server_name_indication = myhttp

EMQX 5.1

{
    mechanism = password_based
    backend = http
    enable = true

    method = post
    url = "http://127.0.0.1:80/mqtt/auth"
    body {
        username = "${username}"
        clientid = "${clientid}"
        password = "${password}"
    }
    headers {
        "Content-Type" = "application/x-www-form-urlencoded"
    }
    request_timeout = "5s"
    connect_timeout = "5s"
    pool_size = 32

    enable_pipelining = 100

    ssl {
      enable = true
      verify = verify_peer

      keyfile = path/to/your/keyfile
      certfile = path/to/your/certfile
      cacertfile = path/to/your/cafile.pem

      server_name_indication = myhttp
    }
}

認可

ACL ファイル

1. acl_file 設定は廃止されました。ファイルベースの ACL（acl.conf）は認可ソースの一つとしてデフォルトで EMQX に組み込まれています。
2. acl.conf のデータファイル構文が変更されました。
3. DSL では pubsub が all に名称変更されました。

4.x	5.1	互換性
user	username	あり
client	clientid	あり
pubsub	all	なし

例

EMQX 4.3

{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.

{allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.

{deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.

{allow, all}.

EMQX 5.1

{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.

{allow, {ipaddr, "127.0.0.1"}, all, ["$SYS/#", "#"]}.

{deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.

{allow, all}.

組み込みデータベース

• Mnesia は組み込みデータベースに名称変更。
• データフォーマットと REST API が変更されました。4.x の ACL データは ./bin/emqx_ctl data export コマンドでエクスポート可能。ユーザーは 5.x フォーマットに変換し、対応する REST API /authorization/sources/built_in_database/rules/{clients,users} でインポートしてください。

例

EMQX 4.4

# 設定なし

EMQX 5.1

{
  type = built_in_database
  enable = true
}

JWT

JWT 認証時に取得したクレームに基づく暗黙の ACL です。ACL クレーム内では %X ではなく ${variable} プレースホルダーを使用してください。

HTTP

type = http

• method、pool_size、connect_timeout、enable_pipelining は継続使用可能。
• acl_req.url は url に変更。
• acl_req.headers は headers に変更。
• acl_req.params は body に変更。
• timeout は request_timeout に変更。
• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

4.4 とは異なり、url、headers、body パラメータでプレースホルダーが使用可能です。

5.1 では body は文字列ではなくマップであり、POST リクエストでは JSON または X-WWW-Form-Urlencoded 形式でシリアライズされ、GET リクエストではクエリパラメータとして送信されます。

4.4 とは異なり、認可結果は HTTP ステータスコードではなくレスポンスボディ内の JSON フィールド（result）で判定されます。HTTP 認可は成功した HTTP ステータスコード（2XX）のレスポンスのみを尊重します。

Details

成功レスポンスステータスコード:

200 または 204

その他のステータスコードやリクエスト失敗は ignore として扱われます。

成功レスポンスボディ（JSON）:

名前	型	必須	説明
result	Enum	必須	`allow

{
  "result": "deny"
}

例

EMQX 4.4

auth.http.acl_req.url = http://127.0.0.1:80/mqtt/acl
auth.http.acl_req.method = post
auth.http.acl_req.headers.content_type = application/x-www-form-urlencoded

auth.http.acl_req.params = clientid=%c,username=%u,password=%P

auth.http.timeout = 5s

auth.http.connect_timeout = 5s
auth.http.pool_size = 32

auth.http.enable_pipelining = 100

auth.http.ssl = on
auth.http.ssl.cacertfile = path/to/your/cafile.pem
auth.http.ssl.certfile = path/to/your/certfile
auth.http.ssl.keyfile = path/to/your/keyfile
auth.http.ssl.verify = true
auth.http.ssl.server_name_indication = myhttp

EMQX 5.1

{
    type = http

    method = post
    url = "http://127.0.0.1:80/mqtt/acl"
    body {
        username = "${username}"
        clientid = "${clientid}"
        password = "${password}"
    }
    headers {
        "Content-Type" = "application/x-www-form-urlencoded"
    }
    request_timeout = "5s"
    connect_timeout = "5s"
    pool_size = 32

    enable_pipelining = 100

    ssl {
      enable = true
      verify = verify_peer

      keyfile = path/to/your/keyfile
      certfile = path/to/your/certfile
      cacertfile = path/to/your/cafile.pem

      server_name_indication = myhttp
    }
}

Redis

  type = redis

障害時に Redis へ自動再接続するために auto_reconnect を利用可能です。

• type は redis_type に変更。
  • single タイプの場合、server は servers に変更。
  • sentinel タイプの場合も同様に server → servers。
  • cluster タイプでは database オプションは廃止。
• database は cluster タイプ以外で引き続き使用可能。
• pool は pool_size に変更。
• password は継続使用可能。
• query_timeout は廃止。
• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。
• auth_cmd は cmd に変更。${var} 形式のプレースホルダーをコマンド内で使用してください。
• Redis データソースは引き続きホワイトリストモードのみをサポートし、acl_nomatch = deny の設定が必要です。
• access フィールド名は action に変更され、値は数値からアクション文字列に変更されました。

4.x のデータを継続利用する場合は手動での移行が必要です。

4.x と 5.x の対応表

4.x	5.x	action
1	subscribe	subscribe
2	publish	publish
3	all	subscribe & publish

5.x のデータ例

HSET mqtt_acl:emqx_u t/# subscribe
HSET mqtt_acl:emqx_u # all
HSET mqtt_acl:emqx_u a/1 publish

例

EMQX 4.4

auth.redis.type = single
auth.redis.server = 127.0.0.1:6379
auth.redis.pool = 8
auth.redis.database = 0
auth.redis.password = pass
assword salt
auth.redis.acl_cmd = HGETALL mqtt_user:%u

auth.redis.password_hash = salt,sha256

auth.redis.ssl = on
auth.redis.ssl.cacertfile = path/to/your/cafile.pem
auth.redis.ssl.certfile = path/to/your/certfile
auth.redis.ssl.keyfile = path/to/your/keyfile
auth.redis.ssl.verify = true
auth.redis.ssl.server_name_indication = myredis

EMQX 5.1

{
  type = redis
  enable = true

  redis_type = single
  server = "127.0.0.1:6379"

  cmd = "HMGET mqtt_user:${username}"
  database = 0
  password = "pass"
  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = myredis
  }
}

MySQL

  type = mysql

• クエリ結果に ipaddr、username、clientid フィールドは不要になりました。

• access フィールドは action に名称変更され、型は整数から文字列または列挙型に変更されました。

• allow フィールドは permission に名称変更され、型は整数から文字列または列挙型に変更されました。

  4.x の整数値と 5.x の文字列／列挙型の対応

  Access/action フィールド対応

  4.x (int)	5.x (varchar/enum)	action
  1	subscribe	subscribe
  2	publish	publish
  3	all	subscribe & publish

  Allow/permission フィールド対応

  4.x (int)	5.x (varchar/enum)	permission
  0	deny	deny
  1	allow	allow

• server、username、password、database、query_timeout は継続使用可能。

• pool は pool_size に変更。

• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。

• acl_query は query に変更。${var} 形式のプレースホルダーを使用してください。

障害時に MySQL へ自動再接続するために auto_reconnect を利用可能です。

ストレージスキーマが変更されました。

EMQX 4.4 ではクエリは [Allow, IpAddr, Username, ClientId, Access, Topic] の順でカラムを取得する必要がありました。

EMQX 5.1 ではクエリは permission, action, topic のカラムを任意の順序で取得すればよいですが、名前は厳密に一致させる必要があります。IpAddr, Username, ClientId の「誰が」部分はクエリ内に含めることが推奨されます。

例

EMQX 4.4

auth.mysql.server = 127.0.0.1:3306
auth.mysql.pool = 8
auth.mysql.username = dbuser
auth.mysql.database = mqtt

auth.mysql.query_timeout = 5s

auth.mysql.acl_query = select allow, ipaddr, username, clientid, access, topic from mqtt_acl where username = '%u'

auth.mysql.ssl = on
auth.mysql.ssl.cacertfile = path/to/your/cafile.pem
auth.mysql.ssl.certfile = path/to/your/certfile
auth.mysql.ssl.keyfile = path/to/your/keyfile
auth.mysql.ssl.verify = true
auth.mysql.ssl.server_name_indication = mymysql

EMQX 5.1

{
  type = mysql
  enable = true

  server = "127.0.0.1:3306"
  username = "dbuser"
  database = "mqtt"
  password = "dbpass"
  pool_size = 8


  query = "select allow as permission, access as action, topic from mqtt_acl where username = ${username} and ipaddr = ${peerhost} and clientid = ${clientid}"
  query_timeout = "5s"

  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mymysql
  }
}

PostgreSQL

type = postgresql

• クエリ結果に ipaddr、username、clientid フィールドは不要になりました。
• access フィールドは action に名称変更され、型は整数から文字列または列挙型に変更されました。
• allow フィールドは permission に名称変更され、型は整数から文字列または列挙型に変更されました。

4.x の整数値と 5.x の文字列／列挙型の対応

Access/action フィールド対応

4.x (int)	5.x (varchar/enum)	action
1	subscribe	subscribe
2	publish	publish
3	all	subscribe & publish

Allow/permission フィールド対応

4.x (int)	5.x (varchar/enum)	permission
0	deny	deny
1	allow	allow

• server、username、password、database は継続使用可能。
• query_timeout、encoding は廃止。
• pool は pool_size に変更。
• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。
• acl_query は query に変更。${var} 形式のプレースホルダーを使用してください。

ストレージスキーマが変更されました。

EMQX 4.4 ではクエリは [Allow, IpAddr, Username, ClientId, Access, Topic] の順でカラムを取得する必要がありました。

EMQX 5.1 ではクエリは permission, action, topic のカラムを任意の順序で取得すればよいですが、名前は厳密に一致させる必要があります。IpAddr, Username, ClientId の「誰が」部分はクエリ内に含めることが推奨されます。

例

EMQX 4.4

auth.pgsql.server = 127.0.0.1:5432
auth.pgsql.pool = 8
auth.pgsql.username = root
auth.pgsql.password = dbpass

auth.pgsql.database = mqtt
auth.pgsql.encoding = utf8

auth.pgsql.acl_query = select allow, ipaddr, username, clientid, access, topic from mqtt_acl where username = '%u'

auth.pgsql.ssl = on
auth.pgsql.ssl.cacertfile = path/to/your/cafile.pem
auth.pgsql.ssl.certfile = path/to/your/certfile
auth.pgsql.ssl.keyfile = path/to/your/keyfile
auth.pgsql.ssl.verify = true
auth.pgsql.ssl.server_name_indication = mypgsql

EMQX 5.1

{
  type = postgresql

  enable = true

  server = "127.0.0.1:5432"
  username = "root"
  database = "mqtt"
  password = "dbpass"
  pool_size = 8

  query = "select allow as permission, access as action, topic from mqtt_acl where username = ${username} and ipaddr = ${peerhost} and clientid = ${clientid}"

  auto_reconnect = true
  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mypgsql
  }
}

MongoDB

type = mongodb

• type は mongo_type に変更。値は single、rs、sharded のいずれか。未定義値は廃止。
• server
  • rs、sharded タイプは servers
  • single タイプは server
• srv_record、username、password、auth_source、database、w_mode、topology、collection は継続使用可能。
• r_mode は rs タイプのみ有効。
• pool は pool_size に変更。
• ssl.* は共通の SSL オプションに変更。詳細は 外部リソースアクセスのための TLS を参照。
• auth_query.selector は filter に変更。文字列ではなく、セレクター全体のデータ構造を指定します。${var} 形式のプレースホルダーはセレクター値に使用可能。
• query_timeout は廃止。

ストレージスキーマが変更されました。

EMQX 4.4 では結果ドキュメントは Redis や JWT と同様にアクションキーごとのトピックリストを含む形式でした：

{
  "publish": ["t1", "t2"],
  "subscribe": ["t3", "t4"],
  "pubsub": ["t5", "t6"]
}

EMQX 5.1 では MongoDB データソースは許可ルールと拒否ルールの両方に対応可能です。以前はホワイトリストモードのみで acl_nomatch = deny 設定が必須でした。ドキュメントは permission、action、topics フィールドを持つ個別ルールの配列である必要があります。topics はトピックの配列です。詳細は AuthZ-MongoDB を参照してください。

4.x のデータを継続利用する場合は手動での移行が必要です。

5.x のデータ例

[
  {
      "username": "emqx_u",
      "clientid": "emqx_c",
      "ipaddress": "127.0.0.1",
      "permission": "allow",
      "action": "all",
      "topics": ["#"]
  }
]

例

EMQX 4.4

auth.mongo.type = single
auth.mongo.srv_record = false
auth.mongo.server = 127.0.0.1:27017
auth.mongo.pool = 8
auth.mongo.username = user
auth.mongo.password = pass
auth.mongo.auth_source = admin
auth.mongo.database = mqtt
auth.mongo.query_timeout = 5s

auth.mongo.ssl = on
auth.mongo.ssl.cacertfile = path/to/your/cafile.pem
auth.mongo.ssl.certfile = path/to/your/certfile
auth.mongo.ssl.keyfile = path/to/your/keyfile
auth.mongo.ssl.verify = true
auth.mongo.ssl.server_name_indication = mymongo

auth.mongo.w_mode = unsafe

auth.mongo.topology.pool_size = 1
auth.mongo.topology.max_overflow = 0


auth.mongo.acl_query.collection = mqtt_user
auth.mongo.acl_query.selector = username=%u, clientid=%c

EMQX 5.1

{
  type = mongodb
  enable = true

  collection = "mqtt_user"
  filter { username = "${username}", clientid = "${clientid}" }

  mongo_type = single
  server = "127.0.0.1:27017"

  database = "mqtt"
  username = "emqx"
  password = "pass"

  ssl {
    enable = true
    verify = verify_peer

    keyfile = path/to/your/keyfile
    certfile = path/to/your/certfile
    cacertfile = path/to/your/cafile.pem

    server_name_indication = mymongo
  }

  topology {
    pool_size = 1
    max_overflow = 0
  }
}