# ファイルからシークレットを読み込む

多くの EMQX 設定項目には機密性の高い値が含まれます。例として、SSLリスナーのキーのパスフレーズ、ブリッジやコネクターのパスワード、OIDCクライアントシークレット、S3のシークレットアクセスキー、APIキーなどがあります。これらの値を `emqx.conf` に直接埋め込んだり、APIリクエストに含めたりすることを避けるために、EMQX はシークレット型フィールドに対して `file://` URL プレフィックスをサポートしています。EMQX は起動時および設定のリロード時に参照されたファイルからシークレットを読み込みます。

## 構文

シークレットとしてドキュメント化されているフィールド（またはダッシュボードのツールチップに `file://` オプションが記載されているフィールド）には、以下の形式を使用してください。

```text
file://<ファイルへのパス>
```

パスは絶対パスでも、EMQX の作業ディレクトリからの相対パスでもかまいません。ファイルの内容全体がシークレット値として使用されますが、1つの変換が行われます。

- 末尾の空白文字は削除されます。末尾の改行、復帰、スペース、タブ文字はすべて取り除かれます。先頭および内部の内容はそのまま使用されます。

例：

```hocon
# ファイルから読み込むSSLリスナーのキーのパスフレーズ
listeners.ssl.default.ssl_options.password = "file://etc/certs/key-passphrase"

# ファイルから読み込むMQTTブリッジのパスワード
bridges.mqtt.upstream.password = "file:///run/secrets/upstream-mqtt-password"
```

## クラスターでの考慮事項

EMQXをクラスターで運用する場合、設定を読み込むすべてのノードがファイルパスを解決できる必要があります。

- 設定を読み込むすべての EMQX ノードにファイルが存在している必要があります。同じパスはノードごとに異なるファイルを指し示します。EMQX はノード間でファイルをコピーしません。
- ファイルの内容はノード間で一致しているべきです。そうでないと、同じ設定項目に対してノードごとに異なるシークレット値が使用されてしまいます。
- ダッシュボードや REST API 経由で設定された場合、変更は `file://...` 文字列としてすべてのノードに伝播され、各ノードが自身のファイルを開きます。

一般的なパターンとしては、EMQX 起動前にデプロイメントツール（Kubernetes Secrets、Ansible、構成管理ツールなど）を使ってシークレットファイルをプロビジョニングし、すべてのノードで同じパスに配置します。

## 適用される箇所

`file://` の形式は、設定スキーマがシークレット型を使用している箇所で利用可能です。主な例は以下の通りです。

- **SSL/TLSリスナー**：`listeners.<type>.<name>.ssl_options.password`（キーのパスフレーズ）。詳細は [Enable SSL/TLS](../network/emqx-mqtt-tls.md) を参照してください。
- **ブリッジおよびコネクター**：パスワード、APIキー、シークレットアクセスキー、JWTトークン、`service_account_json` のようなサービスアカウントJSON認証情報。
- **クラスターリンク**：`cluster.links[].password`。
- **ダッシュボードSSO（OIDC）**：`dashboard.sso.oidc.secret`。
- **ライセンス**：`license.key`（ライセンス文字列自体）。詳細は [License Configuration](../configuration/license.md) を参照してください。
- **AI補完**：`ai.completion_profile.api_key`。

特定のフィールドが `file://` を受け入れる場合、そのフィールドのダッシュボードのツールチップに明示的に記載されています。

## ロギングとマスキング

EMQX はログやHTTP APIレスポンスからシークレット値をマスキングします。シークレットが `file://...` URL として設定されている場合、EMQX はファイルの内容ではなくパス自体をログに記録します。これにより、運用者はどのファイルをノードが読み込んでいるかを確認できます。ファイルから抽出されたシークレット値がログに出力されることはありません。

## `file://` を使わない方がよい場合

設定フィールドが通常の `string` 型（シークレット型でない）である場合、値の先頭に `file://` を付けてもファイル参照としては扱われず、そのままの文字列として解釈されます。`file://` がサポートされているかどうかは、各フィールドのスキーマタイプを確認してください。