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

> Documentation for Http

# HTTP

<CloudNotSupportedBadge />

<Note>
  This page isn't applicable to [ClickHouse Cloud](https://clickhouse.com/cloud). The feature documented here isn't available in ClickHouse Cloud services.
  See the ClickHouse [Cloud Compatibility](/products/cloud/guides/cloud-compatibility) guide for more information.
</Note>

HTTP server can be used to authenticate ClickHouse users. HTTP authentication can only be used as an external authenticator for existing users, which are defined in `users.xml` or in local access control paths. Currently, [Basic](https://datatracker.ietf.org/doc/html/rfc7617) authentication scheme using GET method is supported.

<h2 id="http-auth-server-definition">
  HTTP authentication server definition
</h2>

To define HTTP authentication server you must add `http_authentication_servers` section to the `config.xml`.

**Example**

```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>

```

Note, that you can define multiple HTTP servers inside the `http_authentication_servers` section using distinct names.

**Parameters**

* `uri` - URI for making authentication request

Timeouts in milliseconds on the socket used for communicating with the server:

* `connection_timeout_ms` - Default: 1000 ms.
* `receive_timeout_ms` - Default: 1000 ms.
* `send_timeout_ms` - Default: 1000 ms.

Retry parameters:

* `max_tries` - The maximum number of attempts to make an authentication request. Default: 3
* `retry_initial_backoff_ms` - The backoff initial interval on retry. Default: 50 ms
* `retry_max_backoff_ms` - The maximum backoff interval. Default: 1000 ms

Forward headers:

The part defines which headers will be forwarded from client request headers to external HTTP authenticator. Note that headers will be matched against config ones in case-insensitive way, but forwarded as-is i.e. unmodified.

<h3 id="enabling-http-auth-in-users-xml">
  Enabling HTTP authentication in `users.xml`
</h3>

In order to enable HTTP authentication for the user, specify `http_authentication` section instead of `password` or similar sections in the user definition.

Parameters:

* `server` - Name of the HTTP authentication server configured in the main `config.xml` file as described previously.
* `scheme` - HTTP authentication scheme. `Basic` is only supported now. Default: Basic

Example (goes into `users.xml`):

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

<Note>
  Note that HTTP authentication cannot be used alongside with any other authentication mechanism. The presence of any other sections like `password` alongside `http_authentication` will force ClickHouse to shutdown.
</Note>

<h3 id="enabling-http-auth-using-sql">
  Enabling HTTP authentication using SQL
</h3>

When [SQL-driven Access Control and Account Management](/concepts/features/security/access-rights#access-control-usage) is enabled in ClickHouse, users identified by HTTP authentication can also be created using SQL statements.

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

...or, `Basic` is default without explicit scheme definition

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

<h3 id="passing-session-settings">
  Passing session settings
</h3>

If a response body from HTTP authentication server has JSON format and contains `settings` sub-object, ClickHouse will try parse its key: value pairs as string values and set them as session settings for authenticated user's current session. If parsing is failed, a response body from server will be ignored.