HTTP認可
EMQXはHTTPアプリケーションに基づく認可をサポートしています。このシナリオでは、ユーザーは外部のHTTPアプリケーションをデータソースとして設定し、EMQXはHTTPサービスにリクエストを送信してHTTP APIから返されるデータに基づき認可結果を判定することで、複雑な認可ロジックを実現します。
注意
HTTP認可はEMQXサーバレスのデプロイメントではサポートされていません。
HTTP認可の仕組み
認可プロセスはHTTP APIコールに似ており、EMQXはリクエストクライアントとして「API」の要件に従ってHTTPサービスへリクエストを構築・送信します。HTTPサービスは「クライアント」の要件に従って結果を返す必要があります。
- レスポンスの
content-typeはapplication/jsonでなければなりません。 - 認可結果はボディ内の
resultで示され、値はallowまたはdenyのいずれかです。 - HTTPステータスコードが
204の場合、認可結果はパブリッシュまたはサブスクライブを許可とみなされます。 - HTTPステータスコードが
200であっても、レスポンスボディが期待される形式でない場合（例えば、resultフィールドが存在しない、またはその値がallowでもdenyでもない場合）、認可結果は無視（ignore）として扱われます。ホワイトリストモードが有効でない場合、クライアントは任意のトピックへのパブリッシュおよびサブスクライブが許可され、不正アクセスやデータ漏洩のリスクがあります。 200および204以外のHTTPステータスコードはすべてignoreとみなされます。例えば、HTTPサービスが利用不可の場合や認証エンドポイントが予期しないレスポンスを返した場合などです。ホワイトリストモードが有効でない場合、クライアントは任意のトピックへのパブリッシュおよびサブスクライブが許可され、不正アクセスやデータ漏洩のリスクがあります。
レスポンス例：
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
"result": "allow" | "deny"
}HTTP認可の設定
デプロイメント画面で アクセス制御 -> 認可 -> 拡張認可 をクリックし、HTTP認可 を選択して 設定 をクリックします。
ID認可の場合、EMQX Cloudは現在のクライアント情報を用いてユーザーが設定した認可クエリリクエストを起動し、HTTPサーバー側のクライアント認可データを照会します。
以下の手順で関連設定を完了できます。
メソッド：HTTPリクエストメソッドを選択します。選択肢は
get、postです。TIP
POSTメソッドの使用を推奨します。GETメソッドを使用すると、一部の機密情報（平文パスワードなど）がHTTPサーバーログに露出する可能性があります。また、信頼できない環境ではHTTPSを使用してください。URL：HTTPサービスのURLアドレスを入力します。
- URLは
http://またはhttps://で始まる必要があります。 - ドメイン名にプレースホルダーを使用しないでください。
- URLパス内で以下のプレースホルダーを使用できます：
${clientid}${username}${password}${peerhost}${cert_subject}${cert_common_name}
- URLは
ヘッダー（任意）：HTTPリクエストヘッダーの設定。複数のヘッダーを追加可能です。接続設定では、同時接続数、接続タイムアウト待機時間、最大HTTPリクエスト数、リクエストタイムアウト時間を設定します。
TLSを有効化：TLSを有効にするかどうかを設定します。
接続プールサイズ（任意）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルト値は
8です。接続タイムアウト（任意）：接続タイムアウト時間を入力します。単位は時間、分、秒、ミリ秒が選択可能です。
HTTPパイプライニング（任意）：レスポンスを待たずに送信可能なHTTPリクエストの最大数を正の整数で指定します。デフォルト値は
100です。リクエストタイムアウト（任意）：リクエストのタイムアウト時間を入力します。単位は時間、分、秒、ミリ秒が選択可能です。
ボディ：リクエストテンプレート。
POSTリクエストはJSON形式でリクエストボディに送信されます。GETリクエストはURLのクエリパラメータとしてエンコードされます。マッピングのキーと値にはプレースホルダーを使用可能です。
TIP
- 現在のデプロイメントがDedicated Flex版の場合、VPCピアリング接続を作成する必要があり、サーバーアドレスは内部ネットワークアドレスにしてください。
- 現在のデプロイメントがBYOC版の場合、パブリッククラウドコンソールでVPCピアリング接続を作成する必要があります。詳細はBYOCデプロイメントの作成 - VPCピアリング接続設定を参照してください。サーバーアドレスは内部ネットワークアドレスにしてください。
- 「Init resource failure!」が発生した場合は、サーバーアドレスが正しいか、セキュリティグループが開放されているかを確認してください。
HTTPリクエストとレスポンス
クライアントがサブスクライブまたはパブリッシュ操作を開始すると、HTTP認可者は設定されたリクエストテンプレートに基づいてリクエストを構築・送信します。リクエストテンプレート内で認可ロジックを実装し、チェック結果が要求された形式で返されるようにしてください。
リクエスト
リクエストはJSON形式で、URLおよびリクエストボディ内に以下のプレースホルダーを使用できます。
${clientid}：クライアントID${username}：クライアントがログイン時に使用したユーザー名${peerhost}：クライアントの送信元IPアドレス${proto_name}：クライアントが使用するプロトコル名（例：MQTT、CoAP）${mountpoint}：ゲートウェイリスナーのマウントポイント（トピックプレフィックス）${action}：要求されているアクション（例：publish、subscribe）${topic}：現在のリクエストでパブリッシュまたはサブスクライブされるトピック（またはトピックフィルター）${qos}：現在のリクエストでパブリッシュまたはサブスクライブされるメッセージのQoS${retain}：現在のリクエストでパブリッシュされるメッセージがリテインメッセージかどうか
レスポンス
認可サービスは以下の形式でレスポンスを返す必要があります。
- レスポンスのcontent-typeは
application/jsonでなければなりません。 - HTTPステータスコードが
200の場合、認可結果はHTTPボディのresultフィールドの値により決まります。allow：パブリッシュまたはサブスクライブを許可deny：パブリッシュまたはサブスクライブを拒否
- HTTPステータスコードが
204の場合、当該パブリッシュまたはサブスクライブ要求は許可されたものとみなされます。 200および204以外のHTTPステータスコードはすべて「無視（ignore）」として扱われます。例えば、HTTPサービスが利用不可の場合や認証エンドポイントが予期しないレスポンスを返した場合などです。ホワイトリストモードが有効でない場合、クライアントは任意のトピックへのパブリッシュおよびサブスクライブが許可され、不正アクセスやデータ漏洩のリスクがあります。
レスポンス例：
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
"result": "allow" | "deny"
}TIP
POSTメソッドの使用を推奨します。GETメソッドを使用すると、一部の機密情報がHTTPサーバーログに露出する可能性があります。
信頼できない環境ではHTTPSを使用してください。