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}

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

• OAuth2クライアント認証情報（オプション）：外部HTTP認証サービスがEMQXの認証を要求する場合にOAuth2クライアント認証情報を有効にします。このオプションは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ヘッダーによる認証はサポートされていません。