# HTTPサービスの利用

::: tip
EMQX v5.8.0以降、HTTP認証器はレスポンスボディにACLルールを含めてクライアントの権限を事前設定できるようになりました。より高いパフォーマンスのために新しいフォーマットの使用を推奨します。詳細は[HTTP認証](../authn/http.md)をご参照ください。
:::

EMQXはHTTPサービスをベースとした認可をサポートしています。ユーザーは外部のHTTPアプリケーションをデータソースとして自ら構築する必要があります。EMQXはHTTPサービスにリクエストを送り、HTTP APIから返されるデータに基づいて認可結果を判定し、複雑な認可ロジックを実現します。

::: tip Tip

- [EMQX認可の基本概念](./authz.md)の知識

:::

## HTTPリクエストとレスポンス

クライアントがサブスクライブまたはパブリッシュ操作を開始すると、HTTP認可者は設定されたリクエストテンプレートに基づいてリクエストを構築し送信します。ユーザーは認可サービス内に認可ロジックを実装し、以下の要件に従って結果を返す必要があります。

### リクエスト

リクエストはJSON形式を利用でき、URLおよびリクエストボディ内で以下のプレースホルダーが使用可能です：

- `${clientid}`：クライアントID。
- `${username}`：クライアントのログイン時に使用されたユーザー名。
- `${client_attrs.NAME}`：クライアント属性。`NAME`は実行時に事前設定された属性名に置き換えられます。クライアント属性の詳細は[MQTTクライアント属性](../../client-attributes/client-attributes.md)をご覧ください。
- `${peerhost}`：クライアントの送信元IPアドレス。
- `${proto_name}`：クライアントが使用するプロトコル名（例：`MQTT`、`CoAP`）。
- `${mountpoint}`：ゲートウェイリスナーのマウントポイント（トピックプレフィックス）。
- `${action}`：リクエストされているアクション（例：`publish`、`subscribe`）。
- `${topic}`：現在のリクエストでパブリッシュまたはサブスクライブされるトピック（またはトピックフィルター）。
- `${qos}`：現在のリクエストでパブリッシュまたはサブスクライブされるメッセージのQoS。
- `${retain}`：現在のリクエストでパブリッシュされるメッセージがリテインドかどうか。
- `${zone}`：実行時のクライアントのゾーン。ゾーンはクライアントの論理的分類（例：地域や環境）であり、クライアント設定に基づいて動的に適用されます。

### レスポンス

認可サービスはチェック後、以下の形式でレスポンスを返す必要があります：

- レスポンスの`content-type`は`application/json`であること。
- HTTPステータスコードが`200`の場合、認可結果はHTTPボディの`result`フィールドの値により判定されます：
  - `allow`：パブリッシュまたはサブスクライブを許可。
  - `deny`：パブリッシュまたはサブスクライブを拒否。
  - `ignore`：このリクエストを無視し、次の認可者に処理を委ねる。
- HTTPステータスコードが`204`の場合、このパブリッシュまたはサブスクライブリクエストは許可されたことを意味します。
- `200`および`204`以外のHTTPステータスコードは「無視」とみなされます。例えば、HTTPサービスが利用不可の場合などです。

<!--- 注意：コードは`application/x-www-form-urlencoded`もサポートしていますが、将来的な拡張が難しいためドキュメントには記載していません -->

レスポンス例：

```json
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" | "ignore" // デフォルトは "ignore"
}
```

::: tip EMQX 4.x互換性について

4.xバージョンでは、EMQXはHTTP APIのステータスコードのみを使用し、コンテンツは破棄していました。例えば、`200`は`allow`、`403`は`deny`を意味していました。より多くの情報をユーザーに提供するため、EMQX 5.0でリクエストコンテンツの返却を追加しました。

:::

::: tip

`POST`メソッドの使用を推奨します。`GET`メソッド使用時は、HTTPサーバーログにより一部の機密情報が露出する可能性があります。

信頼できない環境ではHTTPSの利用を推奨します。

:::

## ダッシュボードでの設定

1. [EMQXダッシュボード](http://127.0.0.1:18083/#/authentication)の左ナビゲーションツリーで**アクセス制御** -> **認可**をクリックし、**認可**ページに入ります。

2. 右上の**作成**をクリックし、**バックエンド**として**HTTPサーバー**を選択し、**次へ**をクリックします。以下のように**設定**タブが表示されます。

   <img src="./assets/authz-http_ee.png" alt="HTTP認可設定画面" style="zoom:67%;" />

3. 以下の指示に従い設定を行います。

   **HTTP**：HTTPリクエストメソッド、IPアドレス、リクエストヘッダーを設定します。

   - **リクエストメソッド**：HTTPリクエストメソッドを選択します。選択肢は`GET`、`POST`。
   - **URL**：HTTPアプリケーションのIPアドレスを入力します。
   - **ヘッダー**（任意）：HTTPリクエストヘッダーを設定します。キーと値は[プレースホルダー](./authz.md#authorization-placeholders)の使用が可能です。

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

   - **プールサイズ**（任意）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルトは`8`。
   - **接続タイムアウト**（任意）：接続タイムアウトまでの待機時間を入力します。単位は**時間**、**分**、**秒**、**ミリ秒**が指定可能です。
   - **HTTPパイプライニング**（任意）：正の整数で、レスポンスを待たずに送信可能な最大HTTPリクエスト数を指定します。デフォルトは`100`。
   - **リクエストタイムアウト**（任意）：リクエストタイムアウトまでの待機時間を入力します。単位は**時間**、**分**、**秒**、**ミリ秒**が指定可能です。
   - **TLS設定**：TLSを有効にするかどうかを設定します。

   **認可設定**：HTTPリクエストボディの設定を完了します。<!--関連情報を追加予定-->

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

## 設定項目による設定

HTTP認可は`type=http`で設定します。

HTTPの`POST`および`GET`リクエストがサポートされており、それぞれ固有のオプションがあります。<!--詳細は[authz:http_post](../../configuration/configuration-manual.html#authz:http_post)および[authz:http_get](../../configuration/configuration-manual.html#authz:http_get)を参照してください。-->

`POST`リクエストで設定したHTTP認可者の例：

```bash
{
    type = http

    method = post
    url = "http://127.0.0.1:32333/authz/${peercert}?clientid=${clientid}"
    body {
        username = "${username}"
        topic = "${topic}"
        action = "${action}"
    }
    headers {
        "Content-Type" = "application/json"
        "X-Request-Source" = "EMQX"
    }
}
```

`GET`リクエストで設定したHTTP認可者の例：

```bash
{
    type = http

    method = get
    url = "http://127.0.0.1:32333/authz"
    body {
        username = "${username}"
        topic = "${topic}"
        action = "${action}"
    }
    headers {
        "X-Request-Source" = "EMQX"
    }
}
```