HTTP認証
EMQXは外部HTTPサービスを利用したパスワード認証をサポートしています。クライアントが接続すると、EMQXはクライアント情報を用いてHTTPリクエストを構築し、リクエストの返却内容に基づいて認証結果を判定します。これにより、複雑な認証および認可ロジックを実現できます。
注意
HTTP認証はEMQXサーバレスのデプロイメントではサポートされていません。
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として扱われ、認証チェーンは継続されます。
レスポンス例：
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 Cloudでは、現在のクライアント情報を用いてユーザーが設定した認証クエリリクエストを作成・発行し、HTTPサーバー側でクライアントの認証データを照会します。
以下の設定を行えます：
メソッド：HTTPリクエストメソッドを選択します。選択肢は
get、postです。TIP
POSTメソッドの使用を推奨します。GETメソッドはHTTPサーバーログに平文パスワードなどの機密情報が露出する可能性があります。また、信頼できない環境ではHTTPSを使用してください。URL：HTTPサービスのURLアドレスを入力します。
TIP
- Dedicated Flexデプロイメントの場合は、VPCピアリング接続を作成し、サーバーアドレスに内部ネットワークアドレスを使用してください。
- BYOCデプロイメントの場合は、パブリッククラウドコンソールでVPCピアリング接続を作成します。詳細はCreate VPC Peering Connectionsを参照してください。サーバーアドレスには内部ネットワークアドレスを使用してください。
- 「Init resource failure!」というメッセージが表示された場合は、サーバーアドレスが正しいか、セキュリティグループがアクセスを許可しているかを確認してください。
- URLは
http://またはhttps://で始まる必要があります。 - ドメイン名にプレースホルダーを使用しないでください。
- URLパス内で以下のプレースホルダーを使用できます：
${clientid}${username}${password}${peerhost}${cert_subject}${cert_common_name}
前提条件（オプション）：1〜256文字のVariform式を入力し、EMQXがクライアントに対してこの認証器を呼び出すかどうかを制御します。式の評価結果が文字列の
'true'の場合にのみ認証器が呼び出され、それ以外はスキップされます。この項目はEMQX 6.1以降のデプロイメントで利用可能です。対応するクライアント属性や例についてはAuthenticator Preconditionsを参照してください。ヘッダー（オプション）：HTTPリクエストヘッダーの設定。複数のヘッダーを追加可能です。
OAuth2クライアント認証情報（オプション）：外部HTTP認証サービスがEMQXの認証を要求する場合に有効化します。このオプションはEMQX v6.1.4以降のデプロイメントで利用可能です。詳細はOAuth2クライアント認証情報の設定を参照してください。
接続設定：同時接続数、接続タイムアウト、最大HTTPリクエスト数、リクエストタイムアウト時間を設定します。
- TLSを有効化：TLSを有効にするかどうかを設定します。
- 接続プールサイズ（オプション）：EMQXノードから外部HTTPサーバーへの同時接続数を整数で指定します。デフォルト値は
8です。 - 接続タイムアウト（オプション）：接続のタイムアウト時間を秒単位で入力します。
- HTTPパイプライン（オプション）：レスポンスを待たずに送信可能な最大HTTPリクエスト数を正の整数で指定します。デフォルト値は
100です。 - リクエストタイムアウト（オプション）：リクエストのタイムアウト時間を指定します。単位は時間、分、秒、ミリ秒が使用可能です。
- ボディ：リクエストテンプレートです。
POSTリクエストの場合はJSON形式でリクエストボディに送信されます。GETリクエストの場合はURLのクエリパラメータとしてエンコードされます。マッピングのキーと値にはプレースホルダーを使用できます。リクエストボディで使用可能なプレースホルダーは以下の通りです：${clientid}：実行時にクライアントIDに置き換えられます。クライアントIDは通常、CONNECTパケットでクライアントが明示的に指定します。${username}：実行時にユーザー名に置き換えられます。ユーザー名はCONNECTパケットのUsernameフィールドから取得します。${password}：実行時にパスワードに置き換えられます。パスワードはCONNECTパケットのPasswordフィールドから取得します。${client_attrs.<attribute>}：クライアント属性です。<attribute>は実行時に事前設定された属性名に置き換えられます。
OAuth2クライアント認証情報の設定
EMQX v6.1.4以降のデプロイメントでは、HTTP認証でOAuth2クライアント認証情報をサポートしています。このオプションを有効にすると、EMQXは設定されたトークンエンドポイントからアクセストークンを取得、キャッシュし、自動的に更新します。EMQXが外部HTTP認証サービスにリクエストを送信する際、Authorization: Bearer <access_token>ヘッダーとしてトークンを追加します。
OAuth2クライアント認証情報を有効にし、以下の項目を設定してください：
| 項目 | 説明 |
|---|---|
| トークンエンドポイント | 必須。アクセストークンを要求するOAuth2認可サーバーのエンドポイント。URLはHTTPまたはHTTPSで、ユーザー情報を含んではいけません。 |
| クライアントID | 必須。アクセストークンを要求するためのOAuth2クライアントID。 |
| クライアントシークレット | 必須。アクセストークンを要求するためのOAuth2クライアントシークレット。 |
| スコープ | オプション。アクセストークンに要求するOAuth2スコープ。 |
| トークンリクエストタイムアウト | トークンエンドポイントへのHTTPリクエストのタイムアウト。デフォルトは5秒。 |
| トークンエンドポイントTLS | トークンエンドポイントに対するTLSを有効化します。この設定は外部HTTP認証サービスへの接続を制御するTLSを有効化とは独立しています。 |
EMQXはapplication/x-www-form-urlencodedのコンテンツタイプで、POSTリクエストをトークンエンドポイントに送信します。リクエストボディにはgrant_type、client_id、client_secret、およびオプションのscopeが含まれます。トークンエンドポイントは200レスポンスでJSONボディを返し、access_tokenを含む必要があります。token_typeとexpires_inも返すことができ、存在する場合、token_typeはBearerでなければならず、expires_inは正の整数である必要があります。
重要なお知らせ
- OAuth2を有効にしている場合、HTTP認証の
Authorizationヘッダーを設定しないでください。EMQXは自動生成されるBearer認証ヘッダーと競合するため、設定を拒否します。 - トークンエンドポイントは、クライアントIDとクライアントシークレットをリクエストボディのフォームフィールドとして受け入れる必要があります。HTTP Basic認証の
Authorizationヘッダーによる認証はサポートされていません。