Kerberos

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.

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

Parameters:

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

Example (goes into config.xml):

  1.     <!- ... -->
  2.     <kerberos>
  3.         <principal>HTTP/[email protected]</principal>
  4.     </kerberos>
  5. </yandex>

With filtering by realm:

Note

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

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.

Kerberos as an external authenticator for existing users

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/

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

  1. <yandex>
  2.     <users>
  4.         <my_user>
  5.             <!- ... -->
  6.             <kerberos>
  7.                 <realm>EXAMPLE.COM</realm>
  8.             </kerberos>
  9.         </my_user>
  10.     </users>

Warning

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.

Reminder

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

Enabling Kerberos using SQL

…or, without filtering by realm: