> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> HTTP 相关文档

# HTTP

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud 不支持此功能
        </div>;
};

<CloudNotSupportedBadge />

<Note>
  本页不适用于 [ClickHouse Cloud](https://clickhouse.com/cloud)。本文档介绍的功能不适用于 ClickHouse Cloud 服务。
  更多信息，请参阅 ClickHouse 的 [Cloud Compatibility](/docs/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 驱动的访问控制与账户管理](/docs/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 会尝试将其中的键值对解析为字符串值，并将其设为已通过身份验证用户当前会话的会话设置。如果解析失败，则会忽略该服务器返回的响应体。