> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> HTTP 相关文档

# HTTP

<CloudNotSupportedBadge />

<Note>
  本页不适用于 [ClickHouse Cloud](https://clickhouse.com/cloud)。本文档介绍的功能不适用于 ClickHouse Cloud 服务。
  更多信息，请参阅 ClickHouse 的 [Cloud Compatibility](/zh/products/cloud/guides/cloud-compatibility) 指南。
</Note>

HTTP 服务器可用于验证 ClickHouse 用户身份。HTTP 身份验证目前只能作为现有用户的外部验证器使用，这些用户需在 `users.xml` 或本地访问控制配置中定义。目前支持使用 GET 方法的 [基础版](https://datatracker.ietf.org/doc/html/rfc7617) 身份验证方案。

<div id="http-auth-server-definition">
  ## HTTP 身份验证服务器定义
</div>

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

**示例**

```xml theme={null}
<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 身份验证器。请注意，请求头会以不区分大小写的方式与配置中的请求头进行匹配，但转发时会保持原样，即不会被修改。

<div id="enabling-http-auth-in-users-xml">
  ### 在 `users.xml` 中启用 HTTP 身份验证
</div>

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

参数：

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

示例 (写入 `users.xml`) ：

```xml theme={null}
<clickhouse>
    <!- ... -->
    <my_user>
        <!- ... -->
        <http_authentication>
            <server>basic_server</server>
            <scheme>basic</scheme>
        </http_authentication>
    </test_user_2>
</clickhouse>
```

<Note>
  请注意，HTTP 身份验证不能与任何其他身份验证机制同时使用。如果除了 `http_authentication` 之外还存在 `password` 等其他配置段，ClickHouse 将会关闭。
</Note>

<div id="enabling-http-auth-using-sql">
  ### 使用 SQL 启用 HTTP 身份验证
</div>

当 ClickHouse 启用[由 SQL 驱动的访问控制与账户管理](/zh/concepts/features/security/access-rights#access-control-usage)后，也可以使用 SQL 语句创建通过 HTTP 身份验证的用户。

```sql theme={null}
CREATE USER my_user IDENTIFIED WITH HTTP SERVER 'basic_server' SCHEME 'Basic'
```

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

```sql theme={null}
CREATE USER my_user IDENTIFIED WITH HTTP SERVER 'basic_server'
```

<div id="passing-session-settings">
  ### 传递会话设置
</div>

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