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

# Настройка SAML SSO

> Как настроить SAML SSO для ClickHouse Cloud

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"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<EnterprisePlanFeatureBadge feature="SAML SSO" />

ClickHouse Cloud поддерживает единый вход (SSO) через Security Assertion Markup Language (SAML). Это позволяет безопасно входить в свою организацию ClickHouse Cloud, проходя аутентификацию через провайдер идентификации (IdP).

Мы поддерживаем SSO, инициируемый поставщиком услуг, несколько организаций с использованием отдельных подключений, а также just-in-time provisioning. Мы также поддерживаем [SCIM provisioning](/docs/ru/products/cloud/guides/security/cloud-access-management/scim-setup) в рамках закрытой предварительной версии с поддержкой Okta. Мы пока не поддерживаем сопоставление атрибутов.

Клиенты, включившие SAML-интеграции, также могут назначить роль по умолчанию, которая будет присваиваться новым пользователям, и настроить тайм-аут сеанса.

<div id="before-you-begin">
  ## Прежде чем начать
</div>

Вам потребуются права администратора в вашем IdP, возможность добавить TXT-запись в настройки DNS для вашего домена, а также роль **Admin** в вашей организации ClickHouse Cloud. Мы также рекомендуем настроить **прямую ссылку на вашу организацию** в дополнение к SAML-подключению, чтобы упростить вход. В каждом IdP это делается по-своему. Ниже описано, как это сделать для вашего IdP.

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

После настройки SAML SSO пользователи входят в систему по сценарию, инициируемому поставщиком услуг:

1. Пользователь переходит на `https://console.clickhouse.cloud` и вводит свой адрес электронной почты (или использует прямую ссылку вашей организации).
2. ClickHouse Cloud перенаправляет его к вашему провайдеру идентификации для аутентификации.
3. При успешной аутентификации провайдер идентификации перенаправляет его обратно в ClickHouse Cloud.
4. ClickHouse Cloud выполняет вход в систему, автоматически создавая аккаунт при первом входе и назначая настроенную вами роль по умолчанию.

Остальная часть этого руководства посвящена разовой настройке.

<div id="how-to-configure-your-idp">
  ## Как настроить IdP
</div>

<Steps>
  <Step title="Откройте настройки организации" id="access-organization-settings">
    Нажмите на название своей организации в нижнем левом углу и выберите Organization details.
  </Step>

  <Step title="Включите единый вход через SAML" id="enable-saml-sso">
    Нажмите переключатель рядом с `Enable SAML single sign-on`. Оставьте этот экран открытым: в процессе настройки вам нужно будет несколько раз к нему возвращаться.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-1.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=37bc32dd8c704500899a452bc388adcc" size="lg" alt="Начало настройки SAML" force width="2136" height="1334" data-path="images/cloud/security/saml-self-serve-1.webp" />
  </Step>

  <Step title="Создайте приложение в своём провайдере идентификации" id="create-idp-application">
    Создайте приложение в своём провайдере идентификации и скопируйте значения с экрана `Enable SAML single sign-on` в конфигурацию провайдера идентификации. Подробнее об этом шаге см. в разделе для вашего провайдера идентификации ниже.

    * [Okta](#okta)
    * [Google](#google)
    * [Azure (Microsoft)](#azure)
    * [Duo](#duo)

    <Tip>
      ClickHouse не поддерживает вход, инициированный провайдером идентификации. Чтобы упростить пользователям доступ к ClickHouse Cloud, создайте для них закладку, используя URL для входа в следующем формате: `https://console.clickhouse.cloud/?connection={orgId}`, где `{orgID}` — идентификатор вашей организации на странице сведений об организации.
    </Tip>

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-2.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=b7667eb8cf23219747842818880e3007" size="lg" alt="Создание приложения провайдера идентификации" force width="2952" height="1744" data-path="images/cloud/security/saml-self-serve-2.webp" />
  </Step>

  <Step title="Добавьте URL метаданных в конфигурацию SAML" id="add-metadata-url">
    Получите `Metadata URL` у своего SAML-провайдера. Вернитесь в ClickHouse Cloud, нажмите `Next: Provide metadata URL` и вставьте URL в текстовое поле.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-3.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=b6e65734eba7b75333347dcee2e56498" size="lg" alt="Добавьте URL метаданных" force width="2962" height="1536" data-path="images/cloud/security/saml-self-serve-3.webp" />
  </Step>

  <Step title="Получение кода для подтверждения домена" id="get-domain-verification-code">
    Нажмите `Next: Verify your domains`. Введите свой домен в текстовое поле и нажмите `Check domain`. Система сгенерирует случайный код подтверждения, который нужно добавить в TXT-запись у вашего DNS-провайдера.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-4.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=5c698b22fd991c2af8cae28135f58092" size="lg" alt="Добавьте домен для подтверждения" force width="2954" height="1530" data-path="images/cloud/security/saml-self-serve-4.webp" />
  </Step>

  <Step title="Подтвердите свой домен" id="verify-your-domain">
    Создайте TXT-запись у вашего DNS-провайдера. Скопируйте `TXT record name` в поле Name для TXT-записи у вашего DNS-провайдера. Скопируйте `Value` в поле Content у вашего DNS-провайдера. Нажмите `Verify and Finish`, чтобы завершить процесс.

    <Note>
      Обновление и подтверждение DNS-записи может занять несколько минут. Вы можете покинуть страницу настройки и вернуться позже, чтобы завершить процесс, не начиная его заново. Значение подтверждения действительно в течение 48 часов с момента первой генерации.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-5.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=9ef00f036771c1f1f2d7647b39c7c391" size="lg" alt="Подтвердите свой домен" force width="2962" height="1594" data-path="images/cloud/security/saml-self-serve-5.webp" />
  </Step>

  <Step title="Обновите роль по умолчанию и тайм-аут сеанса" id="update-defaults">
    После завершения настройки SAML вы можете задать роли по умолчанию, которые будут назначаться всем пользователям при входе в систему, а также настроить параметры тайм-аута сеанса. Список доступных системных ролей, которые можно назначить, см. в разделе [Роли и разрешения в консоли](/docs/ru/products/cloud/reference/security/console-roles).
  </Step>

  <Step title="Настройте своего пользователя с ролью Admin" id="configure-your-admin-user">
    <Note>
      Пользователи, настроенные с другим методом аутентификации, сохранятся, пока администратор вашей организации не удалит их.
    </Note>

    Чтобы назначить своего первого пользователя с ролью Admin через SAML:

    1. Выйдите из [ClickHouse Cloud](https://console.clickhouse.cloud).
    2. В вашем провайдере идентификации назначьте пользователю с ролью Admin приложения ClickHouse.
    3. Попросите пользователя войти через [https://console.clickhouse.cloud/?connection=\{orgId}](https://console.clickhouse.cloud/?connection=\{orgId}) (короткий URL). Это можно сделать, например, через закладку, которую вы создали на предыдущих шагах. Пользователь не появится в ClickHouse Cloud до первого входа.
    4. Если роль SAML по умолчанию отличается от Admin, пользователю может потребоваться выйти и снова войти, используя исходный метод аутентификации, чтобы обновить роль нового SAML-пользователя.
       * Для учетных записей email + password используйте `https://console.clickhouse.cloud/?with=email`.
       * Для входа через социальные сети нажмите соответствующую кнопку (**Continue with Google** или **Continue with Microsoft**)

    <Note>
      `email` в `?with=email` выше — это буквальное значение параметра, а не заполнитель
    </Note>

    5. Выйдите еще раз и снова войдите через короткий URL, чтобы выполнить последний шаг ниже.

    <Tip>
      Чтобы сократить число шагов, можно сначала установить для роли SAML по умолчанию значение `Admin`. Когда пользователь с ролью Admin будет назначен в вашем провайдере идентификации и впервые войдет в систему, он сможет изменить роль по умолчанию на другое значение.
    </Tip>
  </Step>

  <Step title="Удалите другие методы аутентификации" id="remove-other-auth-methods">
    Чтобы завершить интеграцию и ограничить доступ только пользователями, входящими через подключение к вашему провайдеру идентификации, удалите всех пользователей, использующих не SAML-метод аутентификации.
  </Step>
</Steps>

<div id="configure-idp">
  ### Настройте провайдер идентификации
</div>

<Tabs>
  <Tab title="Okta" id="okta">
    Для каждой организации ClickHouse вам нужно настроить в Okta две интеграции приложений: одно SAML-приложение и одну закладку, в которой будет храниться ваша прямая ссылка.

    #### Создайте группу для управления доступом

    1. Войдите в свой экземпляр Okta под учетной записью **Administrator**.
    2. Слева выберите **Groups**.
    3. Нажмите **Add group**.
    4. Введите имя и описание группы. Эта группа будет использоваться, чтобы состав пользователей в SAML-приложении и связанном с ним приложении-закладке оставался одинаковым.
    5. Нажмите **Save**.
    6. Нажмите имя созданной группы.
    7. Нажмите **Assign people**, чтобы назначить пользователей, которым вы хотите предоставить доступ к этой организации ClickHouse.

    #### Создайте приложение-закладку, чтобы пользователи могли входить без лишних действий

    1. Слева выберите **Applications**, затем подраздел **Applications**.
    2. Нажмите **Browse App Catalog**.
    3. Найдите и выберите **Bookmark App**.
    4. Нажмите **Add integration**.
    5. Укажите метку для приложения.
    6. Введите URL: `https://console.clickhouse.cloud/?connection={organizationid}`
    7. Перейдите на вкладку **Assignments** и добавьте созданную выше группу.

    #### Создайте SAML-приложение, чтобы настроить подключение

    1. Слева выберите **Applications**, затем подраздел **Applications**.

    2. Нажмите **Create App Integration**.

    3. Выберите SAML 2.0 и нажмите **Next**.

    4. Введите имя приложения, установите флажок рядом с **Don't display application icon to users**, затем нажмите **Next**.

    5. Используйте следующие значения для заполнения экрана настроек SAML.

       | Поле                           | Значение                                         |
       | ------------------------------ | ------------------------------------------------ |
       | Single Sign On URL             | Скопируйте Single Sign-On URL из консоли         |
       | Audience URI (SP Entity ID)    | Скопируйте Service Provider Entity ID из консоли |
       | Default RelayState             | Оставьте пустым                                  |
       | Name ID format                 | Unspecified                                      |
       | Application username           | Email                                            |
       | Update application username on | Create and update                                |

    6. Введите следующий Attribute Statement.

       | Name  | Name format | Value      |
       | ----- | ----------- | ---------- |
       | email | Basic       | user.email |

    7. Нажмите **Next**.

    8. Введите запрошенную информацию на экране Feedback и нажмите **Finish**.

    9. Перейдите на вкладку **Assignments** и добавьте созданную выше группу.

    10. На вкладке **Sign On** для нового приложения нажмите кнопку **Copy metadata URL**.

    11. Вернитесь к разделу [Добавить metadata URL в конфигурацию SAML](#add-metadata-url), чтобы продолжить процесс.
  </Tab>

  <Tab title="Google" id="google">
    Для каждой организации нужно настроить отдельное SAML-приложение в Google и, если используется multi-org SSO, предоставить пользователям прямую ссылку (`https://console.clickhouse.cloud/?connection={organizationId}`), чтобы они добавили её в закладки.

    #### Создайте веб-приложение в Google

    1. Перейдите в консоль администратора Google (admin.google.com).

           <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-google-app.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=85e5ddbddb3a53903268e8bb4595863d" size="md" alt="Google SAML App" force width="1224" height="608" data-path="images/cloud/security/saml-google-app.webp" />

    2. Нажмите **Apps**, затем слева выберите **Web and mobile apps**.

    3. В верхнем меню нажмите **Add app**, затем выберите **Add custom SAML app**.

    4. Введите имя приложения и нажмите **Continue**.

    5. Скопируйте metadata URL и сохраните его в удобном месте.

    6. Введите указанные ниже ACS URL и Entity ID.

       | Поле      | Значение                                         |
       | --------- | ------------------------------------------------ |
       | ACS URL   | Скопируйте Single Sign-On URL из консоли         |
       | Entity ID | Скопируйте Service Provider Entity ID из консоли |

    7. Установите флажок **Signed response**.

    8. Выберите **EMAIL** в качестве формата Name ID Format и оставьте Name ID равным **Basic Information > Primary email.**

    9. Нажмите **Continue**.

    10. Укажите следующее сопоставление атрибутов:

        | Поле              | Значение      |
        | ----------------- | ------------- |
        | Basic information | Primary email |
        | App attributes    | email         |

    11. Нажмите **Finish**.

    12. Чтобы включить приложение, нажмите **OFF** для всех и измените значение на **ON** для всех. Также можно ограничить доступ для групп или организационных единиц, выбрав соответствующие параметры в левой части экрана.

    13. Вернитесь к разделу [Добавить metadata URL в конфигурацию SAML](#add-metadata-url), чтобы продолжить.
  </Tab>

  <Tab title="Azure (Microsoft)" id="azure">
    Azure (Microsoft) SAML также может называться Azure Active Directory (AD) или Microsoft Entra.

    #### Создание корпоративного приложения Azure

    Вам нужно настроить одну интеграцию приложения с отдельным URL входа для каждой организации.

    1. Войдите в центр администрирования Microsoft Entra.

    2. Перейдите в раздел **Applications > Enterprise applications** слева.

    3. Нажмите **New application** в верхнем меню.

    4. Нажмите **Create your own application** в верхнем меню.

    5. Введите имя и выберите **Integrate any other application you don't find in the gallery (Non-gallery)**, затем нажмите **Create**.

           <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-azure-app.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=2b17a3cd8cc1fb3c8b4612fb0a4e4f14" size="md" alt="Приложение Azure не из коллекции" force width="980" height="624" data-path="images/cloud/security/saml-azure-app.webp" />

    6. Нажмите **Users and groups** слева и назначьте пользователей.

    7. Нажмите **Single sign-on** слева.

    8. Нажмите **SAML**.

    9. Используйте следующие настройки, чтобы заполнить поля на экране Basic SAML Configuration.

       | Field                                       | Value                                                           |
       | ------------------------------------------- | --------------------------------------------------------------- |
       | Идентификатор (Entity ID)                   | Скопируйте Service Provider Entity ID из консоли                |
       | URL ответа (Assertion Consumer Service URL) | Скопируйте Single Sign-On URL из консоли                        |
       | URL входа                                   | `https://console.clickhouse.cloud/?connection={organizationid}` |
       | Relay State                                 | Оставьте пустым                                                 |
       | URL выхода                                  | Оставьте пустым                                                 |

    10. Добавьте (A) или обновите (U) следующие значения в разделе Attributes & Claims:

        | Claim name                           | Format        | Source attribute |
        | ------------------------------------ | ------------- | ---------------- |
        | (U) Unique User Identifier (Name ID) | Email address | user.mail        |
        | (A) email                            | Basic         | user.mail        |
        | (U) /identity/claims/name            | Omitted       | user.mail        |

            <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-azure-claims.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=639d6890c29c84209f474ad82c130d68" size="md" alt="Атрибуты и утверждения" force width="1242" height="816" data-path="images/cloud/security/saml-azure-claims.webp" />

    11. Скопируйте metadata URL и вернитесь к разделу [Добавить metadata URL в конфигурацию SAML](#add-metadata-url), чтобы продолжить.
  </Tab>

  <Tab title="Duo" id="duo">
    #### Создайте универсального поставщика услуг SAML для Duo

    1. Следуйте инструкциям в [Duo Single Sign-On for Generic SAML Service Providers](https://duo.com/docs/sso-generic).

    2. Используйте следующее сопоставление атрибутов Bridge:

       | Атрибут Bridge          | Атрибут ClickHouse |
       | :---------------------- | :----------------- |
       | Адрес электронной почты | email              |

    3. Используйте следующие значения, чтобы обновить приложение Cloud в Duo:

       | Поле                                 | Значение                                                        |
       | :----------------------------------- | :-------------------------------------------------------------- |
       | Entity ID                            | Скопируйте Service Provider Entity ID из консоли                |
       | Assertion Consumer Service (ACS) URL | Скопируйте Single Sign-On URL из консоли                        |
       | Service Provider Login URL           | `https://console.clickhouse.cloud/?connection={organizationid}` |

    4. Скопируйте metadata URL и вернитесь к [Добавить metadata URL в конфигурацию SAML](#add-metadata-url), чтобы продолжить процесс.
  </Tab>
</Tabs>

<div id="troubleshooting">
  ## Устранение неполадок
</div>

<AccordionGroup>
  <Accordion title="В системе может быть ошибка конфигурации или сбой сервиса">
    **Причина:** вход, инициированный провайдером идентификации, не поддерживается.

    **Решение:** используйте прямую ссылку `https://console.clickhouse.cloud/?connection={organizationid}`. Следуя приведённым выше инструкциям для вашего провайдера идентификации, сделайте этот способ входа способом по умолчанию для ваших пользователей.
  </Accordion>

  <Accordion title="Вас перенаправляет к провайдеру идентификации, а затем обратно на страницу входа">
    **Причина:** у провайдера идентификации не настроено сопоставление атрибута email.

    **Решение:** следуя приведённым выше инструкциям для вашего провайдера идентификации, настройте атрибут email пользователя, а затем войдите снова.
  </Accordion>

  <Accordion title="Пользователь не назначен этому приложению">
    **Причина:** пользователь не назначен приложению ClickHouse у провайдера идентификации.

    **Решение:** назначьте пользователя приложению у провайдера идентификации и войдите снова.
  </Accordion>

  <Accordion title="При наличии нескольких SAML-организаций вы всегда попадаете в одну и ту же организацию">
    **Причина:** вы всё ещё вошли в первую организацию.

    **Решение:** выйдите из системы, затем войдите в другую организацию.
  </Accordion>

  <Accordion title="В URL на короткое время появляется сообщение об отказе в доступе">
    **Причина:** домен вашего email не совпадает с настроенным доменом.

    **Решение:** обратитесь в службу поддержки, чтобы устранить эту ошибку.
  </Accordion>
</AccordionGroup>

<div id="faq">
  ## Часто задаваемые вопросы
</div>

<AccordionGroup>
  <Accordion title="Поддерживает ли ClickHouse Cloud вход, инициированный провайдером идентификации?">
    Нет — только потоки, инициируемые поставщиком услуг. Пользователи переходят на `https://console.clickhouse.cloud` и вводят свой email, после чего перенаправляются к вашему провайдеру идентификации. Настройте закладку или прямую ссылку (`https://console.clickhouse.cloud/?connection={organizationid}`), чтобы пользователям не приходилось запоминать URL.
  </Accordion>

  <Accordion title="Как использовать SAML SSO с несколькими организациями?">
    ClickHouse Cloud поддерживает SSO для нескольких организаций с отдельным подключением для каждой организации. Используйте прямую ссылку (`https://console.clickhouse.cloud/?connection={organizationid}`), чтобы входить в каждую из них, и выходите из одной организации перед входом в другую. Если вы не хотите, чтобы пользователи вашего домена автоматически перенаправлялись в организацию, когда вводят свой email на `https://console.clickhouse.cloud`, обратитесь в поддержку, чтобы отключить это поведение.
  </Accordion>

  <Accordion title="Почему я вижу несколько аккаунтов для одного и того же пользователя?">
    ClickHouse Cloud не связывает автоматически SSO-аккаунты и аккаунты без SSO, поэтому пользователь, входивший обоими способами, может отображаться в списке пользователей несколько раз, даже с одним и тем же email-адресом.
  </Accordion>
</AccordionGroup>

<div id="next-steps">
  ## Следующие шаги
</div>

* [Manage cloud users](/docs/ru/products/cloud/guides/security/cloud-access-management/manage-cloud-users) — управление разрешениями пользователей и ограничение доступа только через SAML-подключения.
* [SCIM provisioning](/docs/ru/products/cloud/guides/security/cloud-access-management/scim-setup) — автоматизируйте подготовку пользователей и групп (закрытая предварительная версия).
* [Роли и разрешения в консоли](/docs/ru/products/cloud/reference/security/console-roles) — роли, которые можно назначить в качестве роли SAML по умолчанию.