Ycsecurity/auth_and_access/keycloak

Развёртывание федерации удостоверений в Yandex Cloud на базе решения Keycloak

Описание решения

Для предоставления доступа корпоративным пользователям к облачным ресурсам в Yandex Cloud используются:

• сервис организации
• федерация удостоверений
• Identity Provider (IdP)

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

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

Федерация удостоверений выступает посредником между сервисом организации и IdP. С помощью федерации учетные записи пользователей из IdP синхронизируются в организацию Yandex Cloud.

После успешной синхронизации учетных записей пользователей в организацию, им можно назначать роли (выдавать права) на различные облачные объекты. В Yandex Cloud поддерживаются федерации удостоверений на базе стандарта SAML v2.0.

В данном решении аутентификация пользователя реализована так:

1. Пользователь вводит в браузере URL облачной консоли Yandex Cloud с указанием идентификатора федерации, например, https://console.yandex.ru/federations/bpf3375ucdgp5dxq823tt.
2. Облачная консоль перенаправляет запрос пользователя на IdP, который развёртывается в виде виртуальной машины (ВМ) с решением Keycloak.
3. На странице IdP пользователь видит форму для аутентификации - ввода имени и пароля.
4. Пользователь вводит свои учетные данные в форму.
5. idP проверяет учетные данные пользователя и в случае их успешной проверки возвращает пользователя в консоль Yandex Cloud уже аутентифицированным.
6. Авторизация (проверка полномочий) пользователя на облачные ресурсы будет выполняться на стороне Yandex Cloud.
7. После успешной проверки полномочий в облачной консоли пользователь должен увидеть каталоги облачных ресурсов к которым у него есть доступ.

Архитектура решения

Обобщенная архитектура решения показана на рисунке ниже.

В данном решение IdP развёртывается в виде виртуальной машины с Keycloak.

Данное решение реализовано в виде двух Terraform модулей:

• keycloak-deploy
• keycloak-config

Разбиение решения на два модуля вызвано тем, что Keycloak Terraform провайдер требует уже работающего (alive) Keycloak.

Модуль keycloak-deploy

Модуль keycloak-deploy создаёт следующие объекты в Yandex Cloud:

• кластер Managed Service for PostgreSQL - для хранения конфигурации Keycloak
• сертификат Let's Encrypt для веб-сервера Keycloak
• статический публичный IP-адрес для ВМ Keycloak
• группу безопасности для ВМ Keycloak
• ВМ с решением Keycloak

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

После завершения своей работы модуль возвращает значение FQDN для ВМ с развёрнутым решением Keycloak, например, kc1.mydom.net

Модуль keycloak-config

Модуль keycloak-config выполняет следующие действия:

• создаёт федерацию удостоверений в Yandex Cloud
• создаёт Realm и сопутствующие объекты в конфигурации Keycloak
• обеспечивает обмен сертификатами между федерацией Yandex Cloud и Keycloak Realm
• создаёт учётную запись для тестового пользователя в Keycloak
• импортирует учётную запись тестового пользователя из Keycloak в организацию Yandex Cloud

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

После завершения своей работы модуль возвращает значение URL федерации удостоверений, например, https://console.yandex.ru/federations/bpf3375ucdgp5dxq823tt

Синхронизация данных между TF модулями

Модуль keycloak-config использует часть входных и выходных данных модуля keycloak-deploy.

Развёртывание решения требует последовательного запуска сначала модуля keycloak-deploy, а затем модуля keycloak-config.

Для исключения ошибок при ручном переносе данных из одного модуля в другой рекомендуется использовать скрипт sync.sh, который синхронизирует нужные данные из модуля keycloak-deploy в модуль keycloak-config.

Внешние зависимости

Решение должно развёртываться в уже подготовленной инфраструктуре Yandex Cloud. Значения параметров инфраструктуры должны передаваться в TF модули решения в виде входных переменных.

Перед развёртывание решения в Yandex Cloud уже должны существовать следующие объекты:

• каталог облачных ресурсов (folder) в котором будут развёртываться компоненты решения (kc_folder_name)
• публичная зона в сервисе Cloud DNS. Домен, который будет создаваться в сервисе Cloud DNS должен быть предварительно делегирован со стороны регистратора домена (dns_zone_name)
• сеть (network) в которой будут развёртываться компоненты решения (kc_network_name)
• подсеть (subnet) в которой будут развёртываться компоненты решения (kc_subnet_name)

В списке выше в круглых скобках указаны имена входных переменных для развёртывания из keycloak-deploy.

Порядок развёртывания решения

Развёртывание решения предполагается под управлением ОС Linux или MacOS.

Развёртывание решения под управлением ОС Windows не тестировалось.

1. Загрузить решение из репозитория на github.com:

   curl -s https://raw.githubusercontent.com/yandex-cloud/yc-solution-library-for-security/master/auth_and_access/keycloak/examples/install.sh | bash
   

2. Перейти в папку с примером развёртывания модуля keycloak-deploy:

   cd keycloak/keycloak-deploy
   pwd
   

3. Важно! Убедиться что все внешние зависимости созданы.

4. Проверить значения переменных в файле main.tf и скорректировать их при необходимости.

5. Выполнить инициализацию Terraform:

   source ../env-yc.sh
   terraform init
   

6. Выполнить развёртывание keycloak-deploy:

   terraform apply
   

   Обработка запроса на выдачу сертификата в сервисе Let's Encrypt может выполняться до 30 минут!

7. Опционально. Проверить состояние выданного сертификата Let's Encrypt:

   yc cm certificate list
   

8. Перейти в папку с примером развёртывания модуля keycloak-config:

   cd ../keycloak-config
   pwd
   

9. Выполнить синхронизацию параметров между TF модулями:

   bash sync.sh
   

10. Проверить значения переменных в файле main.tf и скорректировать их при необходимости.

11. Выполнить инициализацию Terraform:

    terraform init
    

12. Выполнить развёртывание keycloak-config:

    terraform apply
    

13. Опционально. Проверить наличие тестовой учётной записи Keycloak в организации Yandex Cloud с помощью yc CLI:

    ORG_ID=$(cat terraform.tfstate | jq -r '.resources[] | select(.type == ('\"yandex_organizationmanager_saml_federation\"')) | .instances[0].attributes.organization_id')
    yc organization-manager user list --organization-id=$ORG_ID
    

Результаты развёртывания

В результате развёртывания решения в Yandex Cloud будут созданы следующие объекты:

• федерация удостоверений в указанной организации
• сертификат Let's Encrypt для ВМ с Keycloak в сервисе Certificate Manager
• виртуальная машина с IdP Keycloak интегрированная с федерацией на стороне Yandex Cloud
• запись в Yandex Cloud DNS с публичным IP-адресом ВМ Keycloak
• учётная запись пользователя в IdP Keycloak и её синхронизация в организации Yandex Cloud

После развёртывания решения останется выдать необходимые роли на нужные облачные ресурсы для созданной в организации учётной записи пользователя.