> ## 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 через консоль

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Бета</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Возможность в статусе бета</span>
        </a>;
};

export const VersionBadge = ({minVersion}) => <div className="versionBadge">
    <div className="versionIcon" style={{
  marginRight: "8px",
  marginTop: "4px"
}}>
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path d="M5 14C5.82843 14 6.5 13.3284 6.5 12.5C6.5 11.6716 5.82843 11 5 11C4.17157 11 3.5 11.6716 3.5 12.5C3.5 13.3284 4.17157 14 5 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M5 5C5.82843 5 6.5 4.32843 6.5 3.5C6.5 2.67157 5.82843 2 5 2C4.17157 2 3.5 2.67157 3.5 3.5C3.5 4.32843 4.17157 5 5 5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M13 10.5C13.8284 10.5 14.5 9.82843 14.5 9C14.5 8.17157 13.8284 7.5 13 7.5C12.1716 7.5 11.5 8.17157 11.5 9C11.5 9.82843 12.1716 10.5 13 10.5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M11.5 9H9.5C9.03426 9 8.57493 8.89157 8.15836 8.68328C7.74179 8.475 7.37944 8.17259 7.1 7.8L5 5V11" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
      </svg>
    </div>
    Доступно начиная с версии {minVersion}
  </div>;

export const EnterprisePlanFeatureBadge = ({feature = 'Эта возможность', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Возможность тарифа Enterprise
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'доступны' : 'доступна'} в тарифе Enterprise. {support ? `Чтобы включить эту возможность, обратитесь в службу поддержки.` : 'Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.'}</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

<BetaBadge />

<VersionBadge minVersion="26.4" />

<EnterprisePlanFeatureBadge feature="JWT-аутентификация с пользовательским провайдером идентификации" />

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

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

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

<div id="before-you-begin">
  ## Перед началом работы
</div>

Для настройки 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 может содержать ключи других типов, но в нём должен присутствовать хотя бы один пригодный для использования ключ.
</Note>

<div id="how-it-works">
  ## Как это работает
</div>

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

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

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

<div id="add-a-jwt-provider">
  ## Добавление JWT-провайдера
</div>

<Steps>
  <Step title="Откройте настройки безопасности сервиса" id="open-security-settings">
    Перейдите к сервису, откройте **Settings** и прокрутите страницу до раздела **Security**. Найдите карточку **JWT-аутентификация**.

    <Image img="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" size="lg" alt="Раздел JWT-аутентификации в настройках безопасности сервиса" force width="1850" height="422" data-path="images/cloud/security/jwt/jwt-section.png" />
  </Step>

  <Step title="Откройте выдвижную панель провайдеров" id="open-flyout">
    Выберите **Set up JWT providers** (или **Manage JWT providers**, если провайдеры уже настроены). Откроется выдвижная панель с готовой к заполнению формой нового провайдера.
  </Step>

  <Step title="Заполните сведения о провайдере" id="fill-provider-details">
    Заполните форму провайдера и нажмите **Save**.

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

  <Step title="При необходимости добавьте других провайдеров" id="add-more-providers">
    Используйте **Add another provider**, чтобы настроить дополнительные провайдеры. В сервисе может быть не более пяти JWT-провайдеров.
  </Step>
</Steps>

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

<div id="limits">
  ## Ограничения
</div>

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

<div id="related">
  ## Связанные материалы
</div>

* [JWT-аутентификация](/docs/ru/concepts/features/security/external-authenticators/jwt) — утверждения токена, эфемерные пользователи и использование клиентом.