# Redisとの連携 この認可機能は、Redisデータベースに格納されたルールリストとパブリッシュ／サブスクリプションのリクエストを照合することで認可チェックを実装しています。 ::: tip 前提条件 [EMQX認可の基本概念](./authz.md)の知識が必要です。 ::: ## データスキーマとクエリ文 ユーザーは以下のデータを返すクエリテンプレートを提供する必要があります。 - `topic`：ルールが適用されるトピックを指定します。トピックフィルターや[トピックプレースホルダー](./authz.md#topic-placeholders)を使用可能です。 - `action`：ルールが適用されるアクションを指定します。利用可能な値は `publish`、`subscribe`、および `all` です。 - `qos`（オプション）：現在のルールが適用されるQoSレベルを指定します。値は `0`、`1`、`2` のいずれか、または複数のQoSレベルを指定する数値配列です。デフォルトはすべてのQoSレベルです。 - `retain`（オプション）：ルールが保持メッセージをサポートするかどうかを指定します。値は `true` または `false` です。デフォルトは保持メッセージを許可します。 例えば、ルールは[Redisハッシュ](https://redis.io/docs/latest/develop/data-types/hashes/)として保存できます。 ユーザー `emqx_u` にトピック `t/1` のサブスクライブ権限を追加する例： ```bash HSET mqtt_acl:emqx_u t/1 subscribe ``` Redisの構造上の制約により、`qos` と `retain` フィールドを使用する場合、トピック以外のフィールドはJSON文字列で格納する必要があります。例： - ユーザー `emqx_u` にトピック `t/2` をQoS 1とQoS 2でサブスクライブする権限を追加する場合： ```bash HSET mqtt_acl:emqx_u t/2 '{ "action": "subscribe", "qos": [1, 2] }' ``` - ユーザー `emqx_u` にトピック `t/3` への保持メッセージのパブリッシュを拒否する権限を追加する場合： ```bash HSET mqtt_acl:emqx_u t/3 '{ "action": "publish", "retain": false }' ``` 対応する設定パラメータは以下の通りです： ```bash cmd = "HGETALL mqtt_acl:${username}" ``` 取得したルールは許可ルールとして扱われます。つまり、トピックフィルターとアクションが一致すればリクエストは許可されます。 :::tip Redis認可機能に追加されたすべてのルールは**許可ルール**であるため、Redis認可機能はホワイトリストモードで使用する必要があります。 ::: ## ダッシュボードでの設定 EMQXダッシュボードを使ってRedisをユーザー認可に利用する設定が可能です。 1. EMQXダッシュボードの左ナビゲーションツリーで **アクセス制御** -> **認可** をクリックし、**認可** ページに入ります。 2. 右上の **作成** をクリックし、**バックエンド**で **Redis** を選択してから **次へ** をクリックします。以下のように **設定** タブが表示されます。 authz-Redis_ee 3. 以下の指示に従って設定を行います。 - **Redisモード**：Redisの展開方式を選択します。`Single`、`Sentinel`、`Cluster` のいずれかです。 - **サーバー**：EMQXが接続するサーバーのアドレスを指定します（`host:port`）。 - **データベース**：Redisのデータベース名を指定します。 - **ユーザー名**：Redisの認証に[Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command)（Redis 6.0以降）を使用している場合に指定します。Redisサーバーがデフォルトユーザー（ACLが無効または強制されていない）を使用している場合は空欄のままで構いません。 ::: tip `username` フィールドはEMQX 5.2.0以降でサポートされています。Redis ACLを利用する場合はこのバージョン以降であることを確認してください。 ::: - **パスワード**：Redisユーザーのパスワードを指定します。認証が有効なRedisインスタンスに接続する場合は必須です。 - ユーザー名を入力した場合、このパスワードはRedis ACL設定の認証情報と一致している必要があります。 - ユーザー名が指定されていない場合は、このパスワードが `default` ユーザーとしての認証に使用されます（有効な場合）。 - **前提条件**：任意のVariform式を入力します。EMQXはこの式が `true` と評価された場合のみこの認可機能を呼び出します。詳細は[認可機能の前提条件](./authz.md#authorizer-preconditions)を参照してください。 - **互換モード**：EMQX 4.xのRedis ACLデータ形式との互換性を有効にするかどうかを制御します。 - `Disabled (Default)`：現在のルール形式を使用します。 - `v4`：旧EMQX 4.xのRedis ACLデータとの互換性を有効にし、アップグレード時に既存データを変更せずに再利用可能にします。 ::: tip このオプションはEMQX 4.xからのアップグレード時に既存のRedis ACLデータを変更せずに再利用するためのものです。新規導入の場合は無効のままにして現在のルール形式を使用することを推奨します。 ::: - **TLSを有効化**：TLSを有効にする場合はトグルスイッチをオンにします。 - **CMD**：データスキーマに従ったクエリコマンドを入力します。 - **詳細設定**：同時接続数や接続タイムアウトまでの待機時間を設定します。 - **プールサイズ**（任意）：EMQXノードからRedisへの同時接続数を整数値で指定します。デフォルトは `8` です。 4. **作成** をクリックして設定を完了します。 ## 設定項目による設定 EMQXの設定項目を使ってRedis認可機能を設定することも可能です。 Redis認可機能はタイプ `redis` で識別されます。Redisは3種類の展開モードに対応しています。 任意の `precondition` 設定項目はVariform式を受け付けます。EMQXはこの式が `true` と評価された場合のみこの認可機能を呼び出します。`precondition` が省略または空の場合は前提条件は適用されません。詳細は[認可機能の前提条件](./authz.md#authorizer-preconditions)を参照してください。 設定例： :::: tabs type: card ::: tab Single ```hocon { type = redis redis_type = single server = "127.0.0.1:6379" cmd = "HGETALL mqtt_user:${username}" database = 1 password = public compatibility_mode = disabled } ``` ::: ::: tab Sentinel ```hocon { type = redis redis_type = sentinel servers = "10.123.13.11:6379,10.123.13.12:6379" sentinel = "mymaster" cmd = "HGETALL mqtt_user:${username}" database = 1 password = public compatibility_mode = disabled } ``` ::: ::: tab Cluster ```hocon { type = redis redis_type = cluster servers = "10.123.13.11:6379,10.123.13.12:6379" cmd = "HGETALL mqtt_user:${username}" password = public compatibility_mode = disabled } ``` ::: :::: > `compatibility_mode` はEMQX 4.xからのアップグレード時に旧Redis ACLデータを再利用する場合に `v4` に設定できます。