Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

HTTP

View as MarkdownEdit this pageReport an issueSet up docs MCP
ClickHouse Cloud 不支持此功能

HTTP 服务器可用于验证 ClickHouse 用户身份。HTTP 身份验证目前只能作为现有用户的外部验证器使用，这些用户需在 users.xml 或本地访问控制配置中定义。目前支持使用 GET 方法的 基础版 身份验证方案。

HTTP 身份验证服务器定义

要定义 HTTP 身份验证服务器，必须在 config.xml 中添加 http_authentication_servers 部分。

示例

<clickhouse>
    <!- ... -->
    <http_authentication_servers>
        <basic_auth_server>
          <uri>http://localhost:8000/auth</uri>
          <connection_timeout_ms>1000</connection_timeout_ms>
          <receive_timeout_ms>1000</receive_timeout_ms>
          <send_timeout_ms>1000</send_timeout_ms>
          <max_tries>3</max_tries>
          <retry_initial_backoff_ms>50</retry_initial_backoff_ms>
          <retry_max_backoff_ms>1000</retry_max_backoff_ms>
          <forward_headers>
            <name>Custom-Auth-Header-1</name>
            <name>Custom-Auth-Header-2</name>
          </forward_headers>

        </basic_auth_server>
    </http_authentication_servers>
</clickhouse>

请注意，你可以在 http_authentication_servers 部分中使用不同的名称定义多个 HTTP 服务器。

参数

  • uri - 用于发起身份验证请求的 URI

用于与服务器通信的套接字超时 (以毫秒为单位) ：

  • connection_timeout_ms - 默认值：1000 毫秒。
  • receive_timeout_ms - 默认值：1000 毫秒。
  • send_timeout_ms - 默认值：1000 毫秒。

重试参数：

  • max_tries - 发起身份验证请求的最大尝试次数。默认值：3
  • retry_initial_backoff_ms - 重试时 backoff 的初始间隔。默认值：50 毫秒
  • retry_max_backoff_ms - 最大 backoff 间隔。默认值：1000 毫秒

转发请求头：

本部分定义了哪些请求头会从客户端请求头转发到外部 HTTP 身份验证器。请注意，请求头会以不区分大小写的方式与配置中的请求头进行匹配，但转发时会保持原样，即不会被修改。

在 users.xml 中启用 HTTP 身份验证

要为用户启用 HTTP 身份验证，请在用户定义中指定 http_authentication 部分，而不是 password 或其他类似部分。

参数：

  • server - 如前文所述，在主 config.xml 文件中配置的 HTTP 身份验证服务器名称。
  • scheme - HTTP 身份验证方案。目前仅支持 基础版。默认值：基础版

示例 (写入 users.xml) ：

<clickhouse>
    <!- ... -->
    <my_user>
        <!- ... -->
        <http_authentication>
            <server>basic_server</server>
            <scheme>basic</scheme>
        </http_authentication>
    </test_user_2>
</clickhouse>

使用 SQL 启用 HTTP 身份验证

当 ClickHouse 启用由 SQL 驱动的访问控制与账户管理后，也可以使用 SQL 语句创建通过 HTTP 身份验证的用户。

CREATE USER my_user IDENTIFIED WITH HTTP SERVER 'basic_server' SCHEME 'Basic'

…或者，未显式定义认证方案时，默认采用 Basic

CREATE USER my_user IDENTIFIED WITH HTTP SERVER 'basic_server'

传递会话设置

如果来自 HTTP 身份验证服务器的响应体采用 JSON 格式，并且包含 settings 子对象，ClickHouse 会尝试将其中的键值对解析为字符串值，并将其设为已通过身份验证用户当前会话的会话设置。如果解析失败，则会忽略该服务器返回的响应体。

Navigation