> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Настройка JWT-аутентификации

> Как настроить провайдеры JWT-аутентификации (JWKS) для отдельных сервисов ClickHouse Cloud через консоль

Доступно начиная с версии 26.4

Возможность тарифа Enterprise

JWT-аутентификация с пользовательским провайдером идентификации доступна в тарифе Enterprise. Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.

> [!TIP]
>
> В этом руководстве описывается настройка JWKS-провайдеров в консоли Cloud. О том, как создать JWT, какова его структура, какие утверждения обязательны, что представляют собой утверждения ролей и привилегий, а также как работают эфемерные пользователи, см. в справочнике [JWT-аутентификация](https://clickhouse.com/docs/ru/concepts/features/security/external-authenticators/jwt.md).

ClickHouse Cloud позволяет аутентифицировать соединения с сервисом с помощью JSON Web Tokens (JWT), проверяемых по вашим конечным точкам JSON Web Key Set (JWKS). Вместо управления учетными данными базы данных ваш провайдер идентификации выпускает краткоживущие токены, которые ClickHouse проверяет по открытым ключам, опубликованным по указанному вами URL JWKS.

Вы можете самостоятельно настроить эти JWKS-провайдеры для каждого сервиса в разделе **Settings → Security** консоли ClickHouse Cloud.

> [!TIP]
>
> **Используете Microsoft Entra ID?**
>
> Воспользуйтесь руководством [JWT-аутентификация с Microsoft Entra ID](https://clickhouse.com/docs/ru/products/cloud/guides/security/cloud-access-management/jwt-authentication-entra-id): в нём описаны настройка Entra ID и значения, которые нужно указать для провайдера, а также рассказано, как сопоставить роли приложений Entra ID с ролями ClickHouse.

## Перед началом работы

Для настройки JWT-провайдеров для сервиса необходимы:

* Организация на тарифе **Enterprise**.
* Сервис, работающий под управлением **ClickHouse версии 26.4 или более поздней**.
* Роль с разрешением `control-plane:service:manage` для этого сервиса (например, **Admin** или **Service admin**). Участники без этого разрешения могут только просматривать данный раздел.
* Общедоступный URL JWKS по протоколу **HTTPS**, публикующий хотя бы один ключ **RSA** (`RS256`) или, для сервисов версии 26.8 или более поздней, ключ **EC** (`ES256`, `ES384`, `ES512`).

> [!NOTE]
>
> Провайдеры на основе JWKS поддерживают ключи **RSA** и, начиная с версии 26.8, ключи **EC** на кривых P-256, P-384 и P-521. Документ JWKS может содержать ключи других типов, но в нём должен присутствовать хотя бы один пригодный для использования ключ.

## Как это работает

Клиент (ваш провайдер идентификации или приложение) создаёт JWT и подписывает его своим **закрытым ключом**. Токен должен соответствовать ожидаемому [формату токена](https://clickhouse.com/docs/ru/concepts/features/security/external-authenticators/jwt.md#token-claims). Затем ClickHouse проверяет его с помощью **открытых** ключей, опубликованных по указанному вами URL JWKS:

1. ClickHouse считывает из заголовка токена `kid` (ID ключа) и выбирает соответствующий ключ из вашего документа JWKS.
2. Он проверяет подпись токена с помощью этого открытого ключа, а также сверяет утверждения `iss` (издатель) и `aud` (аудитория) с конфигурацией вашего провайдера.
3. При успешной проверке соединение выполняется от имени эфемерного пользователя, чьи права доступа определяются утверждениями `clickhouse:grants` и `clickhouse:roles` токена и ограничены верхней границей разрешений (пользователь `default`). Подробнее см. в разделе [Права доступа](https://clickhouse.com/docs/ru/concepts/features/security/external-authenticators/jwt.md#access-rights).

ClickHouse проверяет доступность URL JWKS и получает данные по нему при добавлении или обновлении провайдера, поэтому неверно настроенный или недоступный URL отклоняется сразу.

## Добавление JWT-провайдера

**1. Откройте настройки безопасности сервиса**

Перейдите к сервису, откройте **Settings** и прокрутите страницу до раздела **Security**. Найдите карточку **JWT-аутентификация**.

![Раздел JWT-аутентификации в настройках безопасности сервиса](https://mintcdn.com/private-7c7dfe99/-6hzQ2QWO_HW75mL/images/cloud/security/jwt/jwt-section.png?fit=max\&auto=format\&n=-6hzQ2QWO_HW75mL\&q=85\&s=79179b401f3a527316bffe67be424977)

**2. Откройте выдвижную панель провайдеров**

Выберите **Set up JWT providers** (или **Manage JWT providers**, если провайдеры уже настроены). Откроется выдвижная панель с готовой к заполнению формой нового провайдера.

**3. Заполните сведения о провайдере**

Заполните форму провайдера и нажмите **Save**.

| Поле | Описание |
| - | - |
| **Name** | Уникальное имя этого провайдера в сервисе. После создания его нельзя изменить. |
| **Issuer** | Ожидаемое значение утверждения `iss` во входящих токенах. |
| **Audience** | Ожидаемое значение утверждения `aud` во входящих токенах. |
| **URL JWKS** | Общедоступный HTTPS URL, по которому публикуются открытые ключи для проверки подписей токенов. |
| **Roles claim** (необязательно) | Утверждение токена, из которого считываются роли ClickHouse. Оставьте пустым, чтобы использовать имя утверждения по умолчанию `clickhouse:roles`. Роли, указанные в токене, должны уже существовать в сервисе. |

**4. При необходимости добавьте других провайдеров**

Используйте **Add another provider**, чтобы настроить дополнительные провайдеры. В сервисе может быть не более пяти JWT-провайдеров.

> [!WARNING]
>
> При удалении JWT-провайдера токены, выданные для него, немедленно перестают приниматься, и все рабочие нагрузки, которые по-прежнему аутентифицируются с помощью этих токенов, перестанут работать.

## Ограничения

* Для каждого сервиса допускается не более **пяти** JWT-провайдеров.
* JWKS-провайдеры поддерживают ключи **RSA** (`RS256`), а начиная с версии 26.8 — ключи **EC** (`ES256`, `ES384`, `ES512`).
* URL JWKS должен быть общедоступной конечной точкой HTTPS. Частные, внутренние и локальные адреса канального уровня отклоняются.

## Связанные материалы

* [JWT-аутентификация](https://clickhouse.com/docs/ru/concepts/features/security/external-authenticators/jwt.md) — утверждения токена, эфемерные пользователи и использование клиентом.
* [JWT-аутентификация с Microsoft Entra ID](https://clickhouse.com/docs/ru/products/cloud/guides/security/cloud-access-management/jwt-authentication-entra-id) — настройка Entra ID в качестве Провайдера JWT.
