> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.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

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>
            Not supported in ClickHouse Cloud
        </div>;
};

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