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

> Existing and properly configured ClickHouse users can be authenticated via Kerberos authentication protocol.

# Kerberos

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

Existing and properly configured ClickHouse users can be authenticated via Kerberos authentication protocol.

Currently, Kerberos can only be used as an external authenticator for existing users, which are defined in `users.xml` or in local access control paths. Those users may only use HTTP requests and must be able to authenticate using GSS-SPNEGO mechanism.

For this approach, Kerberos must be configured in the system and must be enabled in ClickHouse config.

<h2 id="enabling-kerberos-in-clickhouse">
  Enabling Kerberos in ClickHouse
</h2>

To enable Kerberos, one should include `kerberos` section in `config.xml`. This section may contain additional parameters.

<h4 id="parameters">
  Parameters
</h4>

* `principal` - canonical service principal name that will be acquired and used when accepting security contexts.
  * This parameter is optional, if omitted, the default principal will be used.

* `realm` - a realm, that will be used to restrict authentication to only those requests whose initiator's realm matches it.
  * This parameter is optional, if omitted, no additional filtering by realm will be applied.

* `keytab` - path to service keytab file.
  * This parameter is optional, if omitted, path to service keytab file must be set in `KRB5_KTNAME` environment variable.

Example (goes into `config.xml`):

```xml theme={null}
<clickhouse>
    <!- ... -->
    <kerberos />
</clickhouse>
```

With principal specification:

```xml theme={null}
<clickhouse>
    <!- ... -->
    <kerberos>
        <principal>HTTP/clickhouse.example.com@EXAMPLE.COM</principal>
    </kerberos>
</clickhouse>
```

With filtering by realm:

```xml theme={null}
<clickhouse>
    <!- ... -->
    <kerberos>
        <realm>EXAMPLE.COM</realm>
    </kerberos>
</clickhouse>
```

<Note>
  You can define only one `kerberos` section. The presence of multiple `kerberos` sections will force ClickHouse to disable Kerberos authentication.
</Note>

<Note>
  `principal` and `realm` sections cannot be specified at the same time. The presence of both `principal` and `realm` sections will force ClickHouse to disable Kerberos authentication.
</Note>

<h2 id="kerberos-as-an-external-authenticator-for-existing-users">
  Kerberos as an external authenticator for existing users
</h2>

Kerberos can be used as a method for verifying the identity of locally defined users (users defined in `users.xml` or in local access control paths). Currently, **only** requests over the HTTP interface can be *kerberized* (via GSS-SPNEGO mechanism).

Kerberos principal name format usually follows this pattern:

* *primary/instance\@REALM*

The */instance* part may occur zero or more times. **The *primary* part of the canonical principal name of the initiator is expected to match the kerberized user name for authentication to succeed**.

<h3 id="enabling-kerberos-in-users-xml">
  Enabling Kerberos in `users.xml`
</h3>

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

Parameters:

* `realm` - a realm that will be used to restrict authentication to only those requests whose initiator's realm matches it.
  * This parameter is optional, if omitted, no additional filtering by realm will be applied.

Example (goes into `users.xml`):

```xml theme={null}
<clickhouse>
    <!- ... -->
    <users>
        <!- ... -->
        <my_user>
            <!- ... -->
            <kerberos>
                <realm>EXAMPLE.COM</realm>
            </kerberos>
        </my_user>
    </users>
</clickhouse>
```

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

<Info>
  **Reminder**

  Note, that now, once user `my_user` uses `kerberos`, Kerberos must be enabled in the main `config.xml` file as described previously.
</Info>

<h3 id="enabling-kerberos-using-sql">
  Enabling Kerberos 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 Kerberos can also be created using SQL statements.

```sql theme={null}
CREATE USER my_user IDENTIFIED WITH kerberos REALM 'EXAMPLE.COM'
```

...or, without filtering by realm:

```sql theme={null}
CREATE USER my_user IDENTIFIED WITH kerberos
```