# HTTP認証

EMQXは外部HTTPサービスを介したパスワード認証をサポートしています。クライアントが接続すると、EMQXはクライアント情報を使ってHTTPリクエストを構築し、リクエストの返却内容に基づいて認証結果を判定します。これにより、複雑な認証および認可ロジックを実現できます。

::: tip 注意

HTTP認証はEMQX Serverlessのデプロイメントではサポートされていません。

:::

## HTTP認証の仕組み

認証プロセスはHTTP APIコールに似ており、EMQXはリクエストを行うクライアントとして、「API」が要求する形式でリクエストを構築し、HTTPサービスに対して発行します。HTTPサービスは「クライアント」の要求に応じて以下の結果を返す必要があります：

- レスポンスのContent-Typeは`application/json`であること。
- 認証結果はボディ内の`result`で示し、`allow`、`deny`、`ignore`のいずれかを指定します。
- スーパーユーザーの状態はボディ内の`is_superuser`フラグで示し、`true`または`false`を設定できます。**`true`に設定すると、そのユーザー名を使うクライアントは認可制約を受けません。スーパーユーザーの設定は推奨されません。**
- HTTPレスポンスのステータスコードは`200`または`204`であるべきです。`4xx/5xx`のステータスコードの場合、ボディは無視され、結果は`ignore`として扱われ、認証チェーンが継続されます。

レスポンス例：

```json
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow", // "allow" | "deny" | "ignore"
    "is_superuser": true, // オプション: true | false、デフォルト値: false
    "client_attrs": { // オプション（v5.7.0以降）
    "role": "admin",
    "sn": "10c61f1a1f47"
}
```

## HTTP認証の設定

デプロイメント画面で、**アクセス制御** -> **認証** -> **拡張認証**をクリックし、**HTTP認証**を選択してから**設定**をクリックします。

認証のために、EMQXプラットフォームは現在のクライアント情報を用いてユーザーが設定した認証クエリリクエストを構築・発行し、HTTPサーバー側でクライアントの認証データを照会します。

以下のように関連設定を行えます：

- **Method**：HTTPリクエストメソッドを選択します。選択肢は`get`、`post`です。

  ::: tip

  `POST`メソッドの使用を推奨します。`GET`メソッドはHTTPサーバーログに平文パスワードなどの機密情報が記録される可能性があります。また、信頼できない環境ではHTTPSを使用してください。

  :::

- **URL**：HTTPサービスのURLアドレスを入力します。

  ::: tip

  - Dedicatedデプロイメントの場合は[VPCピアリング接続](./vpc_peering.md)を作成し、内部ネットワークアドレスをサーバーアドレスとして使用してください。
  - BYOCデプロイメントの場合はパブリッククラウドコンソールでVPCピアリング接続を作成してください。詳細は[Create VPC Peering Connections](./byoc_vpc_peering.md)を参照し、内部ネットワークアドレスをサーバーアドレスとして使用します。
  - 「Init resource failure!」というメッセージが出た場合は、サーバーアドレスが正しいか、セキュリティグループがアクセスを許可しているかを確認してください。

  :::

  - URLアドレスは`http://`または`https://`で始まる必要があります。
  - ドメイン名にプレースホルダーは使用しないでください。
  - URLパスには以下のプレースホルダーを使用可能です：
    - `${clientid}`
    - `${username}`
    - `${password}`
    - `${peerhost}`
    - `${cert_subject}`
    - `${cert_common_name}`

- **Headers**（オプション）：HTTPリクエストヘッダーの設定。複数のヘッダーを追加可能です。

- **接続設定**：同時接続数、接続タイムアウト、最大HTTPリクエスト数、リクエストタイムアウト時間を設定します。

  - **TLSを有効化**：TLSを有効にするかどうかを設定します。
  - **コネクションプールサイズ**（オプション）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルト値は`8`です。
  - **接続タイムアウト**（オプション）：接続タイムアウト時間を秒単位で入力します。
  - **HTTPパイプライン**（オプション）：レスポンスを待たずに送信可能な最大HTTPリクエスト数を正の整数で指定します。デフォルト値は`100`です。
  - **リクエストタイムアウト**（オプション）：リクエストタイムアウト時間を入力します。単位は時間、分、秒、ミリ秒が使用可能です。
  - **Body**：リクエストテンプレート。`POST`リクエストの場合はJSON形式でリクエストボディに送信されます。`GET`リクエストの場合はURLのクエリパラメータとしてエンコードされます。マッピングのキーと値にはプレースホルダーを使用可能です。リクエストボディで使用可能なプレースホルダーは以下の通りです：
    - `${clientid}`：実行時にクライアントIDに置き換えられます。クライアントIDは通常、クライアントがCONNECTパケットで明示的に指定します。
    - `${username}`：実行時にユーザー名に置き換えられます。ユーザー名はCONNECTパケットのUsernameフィールドから取得します。
    - `${password}`：実行時にパスワードに置き換えられます。パスワードはCONNECTパケットのPasswordフィールドから取得します。
    - `${client_attrs.<attribute>}`：クライアント属性。`<attribute>`は事前定義された設定に基づき実行時に属性名に置き換えられます。