Как подключить и настроить федеративный доступ в Keycloak

Как подключиться к сервисам Selectel с помощью одной учетной записи

Максим Филимонов
Максим Филимонов Ведущий инженер
18 марта 2024

В статье рассказываем, как получить доступ к управлению сервисами и ресурсами Selectel через одну учетную запись и как все для этого настроить.

Изображение записи

Привет! Я Максим Филимонов, ведущий инженер команды администрирования сервисов в Selectel. Для доступа в аккаунты с инфраструктурой, которую мы сопровождаем, приходится хранить множество паролей, контролировать их соответствие парольным политикам, проводить ротацию учетных записей в панелях для каждого аккаунта отдельно. В какой-то момент менеджмент учетных записей стал проблемой. Для примера: чтобы три сотрудника могли администрировать 100 клиентских панелей, нужно создать 300 учеток.

С решением проблемы менеджмента учетных записей помогли коллеги из команды IAM. Они запустили федеративный доступ, благодаря которому с одной учетной записью можно попадать в неограниченное количество панелей.

Что такое федеративный доступ

Федерации удостоверений позволяют пользователям авторизоваться в панели управления Selectel с помощью технологии единого входа Single Sign-On (SSO). Другими словами, пользователь попадает в разные сервисы через одну и ту же учетную запись от поставщика удостоверений (IdP), например Keycloak или ADFS. Это упрощает вход в систему и повышает безопасность, так как не требует создания дополнительных паролей.

Кроме того, федеративный доступ синхронизирует информацию и настройки между различными сервисами. Скажем, если пользователь меняет пароль в одной учетной записи, эти изменения автоматически применяются ко всем остальным, которые с ней связаны.

На данный момент в федерациях Selectel используется открытый стандарт Security Assertion Markup Language (SAML). Он нужен для обмена аутентификационной и авторизационной информацией между IdP и сервис-провайдером (SP). Благодаря SAML пользовательская информация и авторизационные данные передаются между сервисами с использованием защищенных токенов, обеспечивая безопасность и удобство входа в систему. Для работы с федерациями IdP должен поддерживать SAML 2.0.

Далее на конкретном примере разберем, как работает федеративный доступ. В большинстве случаев все шаги можно воспроизвести в своей панели управления.

Деплой облачного сервера с Keycloak из образа

Из чего состоит образ

Вот как выглядит функционал образа с Keycloak для быстрого развертывания сервера:

  • Keycloak 22.0.1,
  • реверс-прокси на nginx,
  • выпуск и автопродление сертификатов Let’s Encrypt,
  • бэкапирование БД,
  • базовая настройка сервера (firewall, ssh-hardening).

Структурная схема выглядит так:

Структурная схема сервера с Keycloak.

Рассмотрим, за что отвечают отдельные ее компоненты.

  • Контейнер nginx-http отвечает за редирект всех запросов на порт https, а также предоставляет URL для выпуска и автопродления сертификатов. Подключен к сети nginx-net.
  • Контейнер certbot отвечает за первичный выпуск сертификата и его автопродление. Подключен к сети nginx-net.
  • Контейнер nginx-https принимает запросы по доменному имени на 443 порту и передает их в контейнер с keycloak. Подключен к сети nginx-net.
  • Контейнер keycloak поднят в production-моде. Настроены Keystore и Truststore. Подключен к сети nginx-net и postgres-net.
  • Контейнер postgres хранит в себе данные keycloak, например пользователей, realms и т. д. Подключен к сети postgres-net.
  • Две cron-задачи отвечают за перевыпуск сертификата и бэкапирование базы данных.

Создание сервера

Для создания сервера необходимо перейти в панель управления, выбрать Облачную платформу, проект и нажать кнопку Создать сервер. В пункте Источник кликаем на  Выбрать другой источник, а затем в разделе Ubuntu выбираем образ Cloud Keycloak 22.0.1 64-bit.

Конфигурирование сервера в панели управления Selectel.

Конфигурацию сервера можно выбрать на свое усмотрение. Рекомендую начать с двух vCPU и 4 ГБ RAM. В качестве диска можно использовать Универсальный SSD на 30 ГБ.

Конфигурирование сервера в панели управления Selectel.

В пункте Сеть выбираем Новый публичный IP-адрес. Обратите внимание: если планируете отправлять письма с этого сервера (например, приглашения новым пользователям), нужно выбрать публичную подсеть. Это связано с тем, что отправка почты с плавающего IP, закрепленного за виртуальной машиной, заблокирована.

Можете выбрать SSH-ключ или добавить новый для зашифрованного подключения. Подключение с помощью пароля по умолчанию отключено в целях безопасности сервера.Далее в разделе Автоматизация, нужно заполнить поле User data следующим образом:


    #cloud-config

write_files:
- path: "/opt/gomplate/values/user-values.yml"
  permissions: "0644"
  content: |
    keycloakDomain: "<your_domain>"
    keycloakAdminEmail: "<your_mail>"
    keycloakAdminUser: "<username>"
    keycloakAdminPassword: "example_admin_pwd_odVhfbpFcpomRH8UtkuK"
    keycloakAdminIP: "<your_allowed_IP>"
    keycloakPostgresDB: "keycloak"
    keycloakPostgresUser: "keycloak"
    keycloakPostgresPassword: "example_bd_pwd_bhznRrXKL5GPGUC0kYSQ"
  • keycloakDomain — укажите домен, по которому Keycloak будет доступен из сети.
  • keycloakAdminEmail — email администратора. Будет использоваться для восстановления админского доступа к Keycloak и выпуска SSL-сертификатов.
  • keycloakAdminUser — имя пользователя для входа в админ-панель Keycloak.
  • keycloakAdminPassword — пароль для входа в админ-панель Keycloak.
  • keycloakAdminIP — IP-адрес, для которого будет доступна админ-панель Keycloak. Подразумевается, что здесь будет указан IP-адрес вашего VPN или текущий IP. Узнать его можно, например, на 2ip.ru. Если нужно разрешить доступ всем IP-адресам, можно указать 0.0.0.0/0.
  • keycloakPostgresDB — имя БД для Keycloak. Можно оставить неизменным.
  • keycloakPostgresUser — имя пользователя БД для Keycloak. Можно оставить неизменным.
  • keycloakPostgresPassword — пароль БД для Keycloak.

После заполнения всех полей можно нажать на кнопку Создать внизу страницы. Спустя несколько минут (в зависимости от выбранной конфигурации) сервер запустится, инициализирует проект и будет готов к работе.

Проверка работы Keycloak

Первый логин

Открываем домен, который указали в User data при создании сервера. Нажимаем на Administration Console и вводим логин/пароль, которые ранее передали в User data. Доступ в Administration Console будет только с IP-адресов, указанных в keycloakAdminIP.

Если на этом этапе столкнулись с какими-либо проблемами, напишите обращение в техподдержку. Наши инженеры помогут разобраться с созданием сервера.

Настройка realm

Realm в Keycloak — это область, которая включает в себя учетные записи пользователей, роли, группы и настройки авторизации. Каждый Keycloak в состоянии управлять несколькими такими областями. Важно, что один и тот же набор данных не может находиться сразу в нескольких realm. Благодаря этому можно изолировать пользователей и их информацию в зависимости от контекста.

В рамках этой статьи дальнейшая настройка будет проведена для realm-а master, но вы можете создать отдельный realm.На данном этапе рекомендую включить логирование событий. Чтобы это сделать, перейдите в раздел Realm SettingsEvents. Здесь во вкладках User event settings и Admin event settings включите тумблеры и укажите ротацию логов, например семь дней.

Получение сертификата

В панели управления Keycloak перейдите в раздел Realm settings.

На первом шаге получения сертификата перейдите во вкладку Realm settings.

На вкладке Keys, в строке RS256 нажмите Certificate.

На втором шаге получения сертификата нажмите кнопку Certificate в строке RS256.

Скопируйте сертификат, он понадобится на следующем шаге для настройки федерации в панели Selectel.

Создание и настройка федерации в панели Selectel

Переходим на страницу федераций и нажимаем на кнопку Добавить Федерацию. Увидим следующую форму:

Страница создания федерации с полями, которые необходимо заполнить.

Заполняем следующие поля:

  • Имя Федерации — можно указать любое;
  • Описание — опциональное поле, краткое описание федерации;
  • IdP Issuer — ссылка на Keycloak в формате https://<keycloak_domain>/realms/<realm_name> (в моем случае http://keycloak-test.sre-team.space/realms/master);
  • Ссылка на страницу входа IdP — URL, на который браузер будет перенаправлять пользователя для аутентификации в формате https://<keycloak_domain>/realms/<realm_name>/protocol/saml (в моем случае https://keycloak-test.sre-team.space/realms/master/protocol/saml);
  • Время жизни сессии — время в часах, спустя которое сессия пользователя будет автоматически завершена;
  • Подписывать запросы аутентификации — все запросы аутентификации будут содержать цифровую подпись;
  • Принудительная аутентификация в Selectel — при включении этой опции IdP-провайдер будет запрашивать у пользователя аутентификацию после истечения сессии в Selectel.

После заполнения полей нажимаем кнопку Создать Федерацию. Откроется следующий шаг — добавление сертификата IdP:

Страница с полем для добавления сертификата IdP.

Имя сертификата можно указать любое. Сам сертификат мы получили ранее в разделе «Получение сертификата», вставляем его сюда. Сертификат обязательно указать в следующем формате:

——BEGIN CERTIFICATE——
PASTE_CERTIFICATE_DATA_HERE
——END CERTIFICATE——

Форма не даст отправить сертификат в других форматах. Мало того, что шрифт в форме не моноширинный, так еще и два дефиса объединяются в одно тире. Из-за этого может возникнуть путаница. Рекомендую копировать и вставлять строки ——BEGIN CERTIFICATE—— и ——END CERTIFICATE——.

После успешного добавления сертификата нажимаем кнопку Завершить добавление Федерации.

Финальная страница создания федерации.

Переходим в нашу федерацию, находим строку Подписывать запросы аутентификации и нажимаем кнопку Скачать сертификат. Он нам понадобится для настройки подписи. Теперь можем приступить к настройке клиента Keycloak.

Настройка клиента Keycloak

Создание клиента

Переходим в раздел Clients и нажимаем кнопку Create client.

Страница создания клиента в Keycloak.

В появившемся окне заполняем поля:

  • Client type — SAML;
  • Client ID — ссылка, куда будут перенаправляться пользователи после аутентификации, в формате https://api.selectel.ru/v1/federations/saml/<federation_id> (ID федерации можно получить на этой странице в ячейке с названием Федерации);
  • Name (опционально) — имя клиента;
  • Description (опционально) — описание клиента.
Окно создания клиента с полями, которые необходимо заполнить.

Нажимаем кнопку Next и переходим на следующий шаг. Теперь необходимо заполнить следующие поля:

  • Root URL и Home URL — указываем URL в формате https://api.selectel.ru/v1/federations/saml/<federation_id>;
  • Valid redirect URLs — указываем https://api.selectel.ru/v1/federations/<federation_id>/saml/acs;
  • остальные поля оставляем пустыми, нажимаем кнопку Save.

Наш клиент создан.

Проверка настроек

На этом шаге нужно внимательно проверить заполнение пяти полей.

  • В блоке SAML capabilities можно выбрать формат идентификатора пользователя: username или email. Я выберу email.
  • Параметры Force POST binding и Include AuthnStatement имеют значение On.
  • В блоке Signature and Encryption параметр Sign assertions имеет значение On.
  • В качестве Signature algorithm выбран RSA_SHA256, а SAML Signature Key Name выбран None.
  • В блоке Logout settings включен параметр Front channel logout.

Настройка цифровой подписи

Переходим на вкладку Keys и включаем опцию Encrypt assertions:

Окно настройки цифровой подписи. Необходимо включить опцию Encrypt assertions внизу.

Должно открыться окно, в нем нажимаем кнопку Generate. После создания сертификата нажимаем Confirm.

Финальное окно создания сертификата.

Импорт сертификата

Теперь нужно импортировать сертификат Selectel, который мы получили в конце настройки федерации. В блоке Encryption keys config нажимаем кнопку Import key:

Страница импорта сертификата.

В разделе Archive format выбираем пункт Certificate PEM, нажимаем кнопку Browse и загружаем сертификат. Завершаем импорт нажатием на кнопку Import. На этом настройка завершена.

Финальная страница настройки сертификата.

Создание первого пользователя и проверка работы

Рассмотрим пример создания пользователя. Его нужно создать как на стороне Keycloak, так и в панели Selectel. К сожалению, на данный момент еще не существует автоматизации создания пользователей, например через Terraform, поэтому будем делать все вручную.

Создание федеративного пользователя в панели Selectel

Переходим в раздел Управление пользователями и нажимаем кнопку Добавить пользователя. В появившемся окне заполняем все поля:

Окно добавления пользователя.
  • Тип аутентификации — выбираем нашу федерацию.
  • External ID — имя пользователя или почта (в зависимости от того, что выбрано в SAML capabilities в Keycloak), по которой пользователь будет входить в Keycloak. В моем случае это имя read-only.
  • Роль — укажите роль пользователя. В моем случае это наблюдатель аккаунта.

Создание федеративного пользователя в Keycloak

Выбираем realm, в котором настраивали ранее SAML-клиент. Переходим в раздел Users.

Страница создания федеративного пользователя в Keycloak.

Здесь представлен список всех пользователей выбранного realm. Нажимаем кнопку Add user.

Страница со списком пользователей. Здесь их можно добавлять или удалять.

В открывшемся окне заполняем поля.

  • Required user actions — действия, которые должен выполнить пользователь при первом логине в Keycloak, например Update Password.
  • Username, Email — имя пользователя и почта. Нужно указать в соответствии с тем, как заполняли при создании пользователя в панели Selectel (External ID).

После этого нажимаем Create. Теперь можно задать пользователю пароль на вкладке Credentials, нажав кнопку Set password.

Страница создания пароля для пользователя.

Проверка работы

После настройки IdP, федерации и создания первого пользователя можно перейти к тестированию. Открываем страницу федеративного входа. Ссылка будет в письме, которое придет на почту после создания пользователя, а также в панели управления на странице федераций. Если вы уже залогинились под каким-либо аккаунтом, вы увидите такое сообщение:

Страница федеративного входа.

Нажимаем на кнопку Авторизоваться в новой Федерации. Нас перенаправит на страницу входа в Keycloak.

Страница входа в Keycloak.

Вводим логин и пароль пользователя Keycloak и нажимаем Sign In. При первом входе вы увидите следующую форму:

Форма первого входа через Keycloak.

Здесь нужно указать ФИО и согласиться на обработку персональных данных. После нажатия кнопки Войти мы попадем в панель управления Selectel. В дальнейшем ID федерации сохранится в кэше браузера. На странице входа мы увидим кнопку Вход с помощью SSO. Если ее нажать, то можно выбрать нашу федерацию из выпадающего списка.

Общую информацию по ошибкам и путям их исправления можно найти в документации Selectel. Вы также можете составить обращение в нашу службу поддержки — мы обязательно вам поможем.

Заключение

До появления федеративного доступа в аккаунты с инфраструктурой, которую мы администрируем, нам приходилось хранить множество паролей, контролировать их соответствие разным политикам, проводить ротацию учетных записей для каждого аккаунта отдельно. Используя федерации, мы сильно упрощаем себе жизнь.