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

Оглавление

• Описанние решения
• Аутентификация пользователя через федерацию
• Архитектура решения
  • Структура контейнера Zitadel
  • Логическая модель Zitadel
• Базовое развёртывание решения
  • Модуль zitadel-deploy
  • Модуль zitadel-config
  • Модуль usersgen
• Внешние зависимости
• Порядок развёртывание решения
• Результаты резвёртывания
• Расширенные варианты развёртывания решения
  • Интеграция Zitadel с Yandex Managed Service for Gitlab
  • Интеграции Zitadel с решением Big Blue Button
  • Интеграции Zitadel с Yandex Managed Service for Gitlab и решением Big Blue Button
• Удаление развёртывания и освобождение ресурсов
• Хранение Terraform State в Yandex Object Storage (опционально)

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

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

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

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

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

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

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

Ознакомиться со списком IdP, которые были протестированы для работы с федерациями удостоверений в Yandex Cloud вы можете в соответствующем разделе документации.

Аутентификация пользователя через федерацию

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

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

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

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

Ниже дано краткое описание наиболее значимых элементов решения:

• IdP Zitadel - основной элемент решения. Развёртывается в виде docker-контейнера с решением Zitadel внутри виртуальной машины zitadel-vm. Контейнер собирается в процессе развёртывания решения. Структуру контейнера Zitadel можно посмотреть на рисунке ниже. Ознакомиться с подробностями сборки контейнера можно в его Dockerfile.

• Кластер БД на базе Yandex Managed Service for PostgreSQL. Вспомогательный элемент, который требуется для создания базы данных для решения Zitadel. В данном решении кластер PostgreSQL развертывается в составе одного узла. Это неотказоустойчивая конфигурация, рекомендуемая только для тестирования. В продуктивной среде рекомендуется создавать кластер как минимум из 2х узлов. При необходимости количество узлов в кластере PostgreSQL может быть увеличено до нужного количества.

• Сloud и Folder. Развертывание решения происходит в заданных при развертывании облаке и каталоге облачных ресурсов.

• Доменная зона DNS и сервис Cloud DNS. Доменная зона DNS должна быть создана в каталоге облачных ресурсов до начала развертывания решения. Имя зоны DNS необходимо будет обязательно указать в параметрах развертывания. Доменная зона будет использоваться:

  • для создания A-записи при резервировании публичного IP-адреса для ВМ zitadel-vm.
  • для создания проверочной записи в процессе проверки прав на домен при создании запроса в Certificate Manager на получение сертификата от сервиса Let's Encrypt (LE).

• Сервис Certificate Manager(CM) будет использоваться для получения сертификата от сервиса Let's Encrypt и взаимодействия в процессе получения сертификата с сервисом Cloud DNS. Контейнер IdP Zitadel будет обращаться при старте к CM для получения актуальной версии LE-сертификата.

Структура контейнера Zitadel

Docker-контейнер с Zitadel собирается в процессе развёртывани виртуальной машины.

Структура контейнера (состав компонентов) показана на схеме ниже.

Логическая модель Zitadel

Логическая структура объектов в данном развертывании и их связи между собой показаны на схеме ниже.

Основные объекты Zitadel, показанные на схеме:

• Instance - высший уровень иерархии в архитектуре Zitadel. На этом уровне находятся параметры конфигурации по умолчанию и различные политики. В одном Instance можно создать одну или несколько организаций.

  В данном развёртывании используется Instance ZITADEL, который обрабатывает запросы на подключения по URL: https://zitadel-vm.my-domain.net:8443.

• Organization - это контейнер для пользователей и проектов, а также связей между ними. Отдельные параметры конфигурации и политики Instance могут быть переопределены на уровне организации.

  В данном развёртывании внутри Zitadel Instance создаются две организации:

  • SysOrg - системная организация (не показана на схеме), которая создаётся на этапе (zitadel-deploy). В этой организации создаётся сервисная учётная запись с JWT-ключом для аутентификации в Zitadel API с максимально широкими полномочиями. Ключ сервисной учётной записи будет использоваться далее для создания всех прочих объектов внутри Zitadel, в том числе, и при работе через Terraform провайдер. Имя файла с ключом сервисной учетной записи формирутеся в виде <имя-ВМ>-sa.json, в данном случае это будет ~/.ssh/zitadel-vm-sa.json.

  • MyOrg - пользовательская организация, которая создаётся на этапе zitadel-config. В этой организации будут созданы все дочерние объекты, которые показаны на схеме выше. При создании этой организации ей ставится статус Default для упрощения операций с ней в дальнейшем. Только одна организация в составе Instance может иметь такой статус.

• Manager - специальный пользователь в организации с особыми полномочиями (ролями), которые позволяют ему управлять другими пользователями в организации. Этот пользователь не будет имеет прав доступа к ресурсам Yandex Cloud. Вид полномочий (список ролей) можно задать в параметрах развёртывания.

  В данном развёртывании будет создан пользователь userman с полномочиями ORG_USER_MANAGER. Этот пользователь сможет создавать учетные записи обычных пользователей (User), а также предоставлять им возможность аутентификации в Yandex Cloud. Подробнее о полномочиях.

• Users - обычные пользователи, которым предоставляется доступ в Yandex Cloud.

  В данном развёртывании будут созданы обычные пользователи zuser1 и zuser2 с учётными записями которых можно аутентифицироваться в федерации удостверений Yandex Cloud.

• Project - это контейнер для ролей пользователей и приложений. В одной организации может быть несколько проектов.

  В данном развёртывании создаётся проект yc-users.

• Application - приложение является точкой входа пользователя в проект. Через приложения реализуются интерфейсы взаимодействия с внешними системами в рамках процессов аутентификации, авторизации и т.п.

  В данном развертывании создаётся приложение yc-federation-saml (тип SAML), которое реализует интеграцию Zitadel с федерацией удостоверений в Yandex Cloud с помощью протокола SAMLv2.

• Authorizations - механизм для добавления пользователей в проект (в Zitadel нет обычных групп пользователей). В Terraform провайдере сущность Authorization называется User Grant.

Процесс работы с пользователями в Ziadel для предоставления им доступа в Yandex Cloud сводится к двум простым шагам:

1. Создать пользователя типа Human User.
2. Авторизовать (создать User Grant) для этого пользователя в нужном проекте.

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

Базовое развёртывание решения

Данное решение реализовано в виде набора Terraform модулей для упрощения процедуры развёртывания и его дальнейшей эксплуатации:

• Модуль zitadel-deploy
• Модуль zitadel-config
• Модуль usersgen

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

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

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

• Облако в котором будет выполняться развёртывание (yc_infra.cloud_id).
• Каталог облачных ресурсов в котором будет выполняться развёртывание (yc_infra.folder_name).
• Публичная зона в сервисе Cloud DNS. Домен (yc_infra.dns_zone_name), который будет создаваться в сервисе Cloud DNS, должен быть предварительно делегирован со стороны регистратора домена.
• Сеть (network) в которой будет выполняться развёртывание (yc_infra.network).
• Подсеть (subnet) в которой будет выполняться развёртывание (yc_infra.subnet1).

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

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

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

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

1. Перед началом развертывания необходимо убедиться, что все необходимые инструменты установлены и настроены:

• yc CLI - установлен и настроен
• Terraform - установлен и настроен
• Python3, а также модули requests и jwt установлены (pip3 install requests jwt)

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

   git clone https://github.com/yandex-cloud-examples/yc-iam-federation-with-zitadel.git

3. Выбрать нужный вариант развертывания (deploy) из следующих:

• zitadel-deploy - базовое развёртывание Zitadel.

• zitadel-gitlab-deploy - расширенный вариант разввертывания Zitadel. Интеграция с Yandex Managed Service for Gitlab (Gitlab).

• zitadel-bbb-deploy - расширенный вариант разввертывания Zitadel. Интеграция с ПО Big Blue Button (BBB).

• zitadel-bbb-gitlab-deploy - расширенный вариант разввертывания Zitadel. Комбинированная интеграция с Gitlab и BBB.

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

4. Перейти в папку с примером выбранного варианта развёртывания, например, zitadel-deploy:

   cd yc-iam-federation-with-zitadel/examples/zitadel-deploy

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

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

7. Подготовить среду для развёртывания:

   terraform init
   source env-setup.sh

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

   terraform apply

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

9. Проверить состояние выданного сертификата Let's Encrypt:

   yc cm certificate list

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

    cd ../zitadel-config

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

    Важно! Убедиться, что в переменной template_file выбран шаблон, соответствующий выбранному варианту развёртывания решения!

12. Скорректировать информацию о пользователях в файле users.yml или сгенерировать его с помощью yamlgen.sh.

13. Задать значения переменным окружения TF_VAR_ZITA_BASE_URL и TF_VAR_JWT_KEY в файле env-setup.sh в соответствии со значениями outputs, полученными при выполнении zitadel-deploy, например:

    export TF_VAR_ZITA_BASE_URL="https://zitadel.mydom.net:8443"
    export TF_VAR_JWT_KEY="~/.ssh/zitadel-sa.json"

14. Подготовить среду для развёртывания:

    terraform init
    source env-setup.sh

15. Выполнить развёртывание zitadel-config и генерацию файла с пользовательcкими ресурсами - users.tf:

    terraform apply

16. Выполнить развёртывание пользовательских ресурсов из файла users.tf:

    terraform apply

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

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

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

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

В результате расширенных вариантов развёртывания будут созданы дополнительные объекты, соответствующие выбранному варианту.

Расширенные варианты развёртывания решения

Решение может быть развёрнуто не только в базовом варианте, но и в расширенных вариантах с интеграцией дополнительных компонентов, таких как:

• Система управления разработкой Yandex Managed Service for GitLab (Gitlab)
• Система видеоконференций Big Blue Button (BBB)
• Интеграция с компонентами Gitlab и BBB одновременно

Расширенные варианты развёртывания отличаются от базового только в части zitadel-deploy, остальные части развертывания - zitadel-config и usersgen работают для всех вариантов развёртывания одинаково.

Интеграция Zitadel с Yandex Managed Service for Gitlab

Пример развёртывания представлен в каталоге zitadel-gitlab-deploy.

Интеграция Zitadel с решением Big Blue Button

Пример развёртывания представлен в каталоге zitadel-bbb-deploy.

Интеграции Zitadel с Yandex Managed Service for Gitlab и решением Big Blue Button

Пример развёртывания представлен в каталоге zitadel-bbb-gitlab-deploy.

Удаление развёртывания и освобождение ресурсов

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

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

   cd yc-iam-federation-with-zitadel/examples/zitadel-config

2. Подготовить окружение:

   source env-setup.sh

3. Удалить ресурсы:

   terraform destroy

   Не обращать внимания на ошибку Default Organisation must not be deleted.

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

   cd ../zitadel-deploy

5. Подготовить окружение:

   source env-setup.sh

6. Удалить ресурсы:

   terraform destroy

7. Удалить каталог с проектом (при необходимости)

   Выйти на уровень выше из проектного каталога и выполнить команду:

   rm -rf yc-iam-federation-with-zitadel