ClickHouse/docs/en/operations/external-authenticators/kerberos.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

127 lines
4.4 KiB
Markdown
Raw Normal View History

2022-08-28 13:53:52 +00:00
---
2022-08-28 13:58:27 +00:00
slug: /en/operations/external-authenticators/kerberos
2022-08-28 13:53:52 +00:00
---
2022-06-02 10:55:18 +00:00
# Kerberos
import SelfManaged from '@site/docs/en/_snippets/_self_managed_only_no_roadmap.md';
<SelfManaged />
2021-02-22 16:18:59 +00:00
2021-02-24 10:10:37 +00:00
Existing and properly configured ClickHouse users can be authenticated via Kerberos authentication protocol.
2021-02-22 16:18:59 +00:00
2021-02-28 19:11:29 +00:00
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.
2021-02-22 16:18:59 +00:00
2021-02-24 10:10:37 +00:00
For this approach, Kerberos must be configured in the system and must be enabled in ClickHouse config.
## Enabling Kerberos in ClickHouse {#enabling-kerberos-in-clickhouse}
2021-02-28 19:11:29 +00:00
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.
2021-12-21 15:36:44 +00:00
- This parameter is optional, if omitted, the default principal will be used.
2021-02-28 19:11:29 +00:00
- `realm` - a realm, that will be used to restrict authentication to only those requests whose initiator's realm matches it.
2021-12-21 15:36:44 +00:00
- This parameter is optional, if omitted, no additional filtering by realm will be applied.
2021-02-24 10:10:37 +00:00
2022-12-26 12:22:29 +00:00
- `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.
2021-02-24 10:10:37 +00:00
Example (goes into `config.xml`):
2021-02-22 16:18:59 +00:00
```xml
2021-10-26 05:50:15 +00:00
<clickhouse>
2021-02-22 16:18:59 +00:00
<!- ... -->
2021-02-24 10:10:37 +00:00
<kerberos />
2021-10-26 05:50:15 +00:00
</clickhouse>
2021-02-22 16:18:59 +00:00
```
2021-02-28 19:11:29 +00:00
With principal specification:
2021-02-22 16:18:59 +00:00
2021-02-24 10:10:37 +00:00
```xml
2021-10-26 05:50:15 +00:00
<clickhouse>
2021-02-24 10:10:37 +00:00
<!- ... -->
<kerberos>
<principal>HTTP/clickhouse.example.com@EXAMPLE.COM</principal>
</kerberos>
2021-10-26 05:50:15 +00:00
</clickhouse>
2021-02-24 10:10:37 +00:00
```
2021-02-22 16:18:59 +00:00
2021-02-28 19:11:29 +00:00
With filtering by realm:
2021-02-22 16:18:59 +00:00
```xml
2021-10-26 05:50:15 +00:00
<clickhouse>
2021-02-22 16:18:59 +00:00
<!- ... -->
2021-02-24 10:10:37 +00:00
<kerberos>
<realm>EXAMPLE.COM</realm>
</kerberos>
2021-10-26 05:50:15 +00:00
</clickhouse>
2021-02-22 16:18:59 +00:00
```
2023-03-27 18:54:05 +00:00
:::note
You can define only one `kerberos` section. The presence of multiple `kerberos` sections will force ClickHouse to disable Kerberos authentication.
:::
2021-02-22 16:18:59 +00:00
2023-03-27 18:54:05 +00:00
:::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.
:::
2021-02-22 16:18:59 +00:00
2021-02-24 10:10:37 +00:00
## Kerberos as an external authenticator for existing users {#kerberos-as-an-external-authenticator-for-existing-users}
2021-02-28 19:11:29 +00:00
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).
2021-02-24 10:10:37 +00:00
2021-02-28 19:11:29 +00:00
Kerberos principal name format usually follows this pattern:
2021-02-24 10:10:37 +00:00
- *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**.
### Enabling Kerberos in `users.xml` {#enabling-kerberos-in-users-xml}
2021-02-28 19:11:29 +00:00
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.
2021-12-21 15:36:44 +00:00
- This parameter is optional, if omitted, no additional filtering by realm will be applied.
2021-02-24 10:10:37 +00:00
Example (goes into `users.xml`):
2021-02-22 16:18:59 +00:00
```xml
2021-10-26 05:50:15 +00:00
<clickhouse>
2021-02-22 16:18:59 +00:00
<!- ... -->
2021-02-24 10:10:37 +00:00
<users>
2021-02-22 16:18:59 +00:00
<!- ... -->
2021-02-24 10:10:37 +00:00
<my_user>
<!- ... -->
<kerberos>
<realm>EXAMPLE.COM</realm>
</kerberos>
</my_user>
</users>
2021-10-26 05:50:15 +00:00
</clickhouse>
2021-02-22 16:18:59 +00:00
```
2023-03-27 18:54:05 +00:00
:::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.
:::
2021-02-22 16:18:59 +00:00
2022-06-02 10:55:18 +00:00
:::info Reminder
Note, that now, once user `my_user` uses `kerberos`, Kerberos must be enabled in the main `config.xml` file as described previously.
:::
2021-02-24 10:10:37 +00:00
### Enabling Kerberos using SQL {#enabling-kerberos-using-sql}
2023-03-18 02:45:43 +00:00
When [SQL-driven Access Control and Account Management](/docs/en/guides/sre/user-management/index.md#access-control) is enabled in ClickHouse, users identified by Kerberos can also be created using SQL statements.
2021-02-24 10:10:37 +00:00
```sql
CREATE USER my_user IDENTIFIED WITH kerberos REALM 'EXAMPLE.COM'
```
...or, without filtering by realm:
```sql
CREATE USER my_user IDENTIFIED WITH kerberos
```