В современном мире разработки программного обеспечения безопасность и управление доступом к репозиториям кода играют ключевую роль. Gitea — это лёгкая и гибкая платформа для хостинга IT-проектов и их совместной разработки, а Keycloak — решение для управления идентификацией и доступом, которое позволяет реализовать SSO (единый вход) и управлять пользователями. Интеграция этих двух систем позволяет повысить безопасность проекта и упростить управление правами доступа.

В данной статье рассмотрим процесс интеграции Gitea и Keycloak, опишем необходимые шаги и возможные сложности, с которыми можно столкнуться при настройке.

Настройка Keycloak

Лучше не использовать мастер-realm для пользовательских приложений.

1. В левом верхнем углу нажмите на имя текущего realm → Create Realm.
2. Введите имя, например gitea-realm, и нажмите Create.

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

Зайдите в административную панель Keycloak и создайте новый клиент, который будет представлять Gitea. Укажите имя клиента, например, «gitea», и настройте допустимые перенаправления (redirect URIs). В качестве перенаправлений можно указать URL-адреса, которые будут использоваться после успешной аутентификации.

Настройте Capability config

• Client authentication: Включить (On) — это сделает клиент Confidential и выдаст ему Client Secret.
• Authorization: Выключить (Off).

Нажмите Next.

Заполните Login settings:

• Root URL: https://<ваш-домен-gitea> (например, https://git.example.com)
• Home URL: https://<ваш-домен-gitea>
• Valid redirect URIs: https://<ваш-домен-gitea>/user/oauth2/*/callback (Важно: именно с *, так как Gitea подставляет туда имя провайдера)
• Valid post logout redirect URIs: https://<ваш-домен-gitea>
• Web origins: https://<ваш-домен-gitea>

Настройка областей (scopes) и ролей. Определите, какие области (например, profile, email) и роли (например, admin, developer) будут использоваться для управления доступом в Gitea. Например, роль admin может иметь полный доступ к репозиториям и настройкам, а роль developer — только право на чтение и внесение изменений в определённые репозитории.

Генерация клиентского идентификатора и секрета

После создания клиента Keycloak сгенерирует клиентский идентификатор (client ID) и секрет (client secret), которые будут использоваться Gitea для взаимодействия с Keycloak. Запишите эти значения, они понадобятся на следующем этапе.

Настройка маппинга атрибутов (Claim mappings)

По умолчанию Keycloak может не передавать имя пользователя или группы в токене так, как ожидает Gitea. Нужно добавить мапперы:

1. Перейдите на вкладку Client scopes внутри вашего клиента gitea, выберите gitea-dedicated.
2. Нажмите Add mapper -> By configuration -> Groups membership.
3. Заполните:
   • Name: gitea-groups
   • Token Claim Name: groups (Gitea ищет группы именно в claim с именем groups)
   • Full group path: Выключить (Off), чтобы передавалось только имя группы, а не полный путь /realm/group.
4. Нажмите Save.

Настройка Gitea

В Gitea есть встроенная поддержка OpenID Connect, что сильно упрощает задачу.

Добавление источника аутентификации

1. Зайдите в Gitea под учетной записью администратора.
2. Перейдите в Site Administration (Администрирование) -> Identity & Access -> Authentication Sources (Источники аутентификации).
3. Нажмите Add Authentication Source.
4. Заполните форму:
   • Authentication Type: Выберите OAuth2 или OpenID Connect (рекомендуется OpenID Connect для автоматического обнаружения эндпоинтов).
   • Name: Имя провайдера, которое увидят пользователи на странице логина (например, Keycloak). (Важно: используйте только латиницу без пробелов, если планируете настраивать группы).
   • OAuth2 Provider: Выберите OpenID Connect.
   • Client ID: Вставьте Client ID из Keycloak (gitea).
   • Client Secret: Вставьте Client Secret из Keycloak.
   • OpenID Connect Auto Discovery URL: https://<ваш-домен-keycloak>/realms/gitea-realm/.well-known/openid-configuration (Gitea автоматически подтянет все нужные URL для авторизации и получения токена по этой ссылке)
5. Нажмите Add Authentication Source.

Отключаем OpenID

Опционально можем отключить авторизацию с использованием OpenID для чего в конфигурационном файле app.ini пропишите параметры:

[openid]
ENABLE_OPENID_SIGNIN = false
ENABLE_OPENID_SIGNUP = false

Включаем авторегистрацию пользователей

Включаем авторегистрацию пользователей, аналогично в конфигурационном файле app.ini:

[oauth2_client]
ENABLE_AUTO_REGISTRATION = true
ACCOUNT_LINKING = auto

Добавляем интеграцию групп Keycloak с группами Gitea

Добавляем интеграцию групп Keycloak с группами Gitea (пользователи и администраторы). В настройках интеграции устанавливаем:

• Additional Scopes — groups
• Required Claim Name — groups
• Required Claim Value — Users
• Claim name providing group names for this source — groups
• Group Claim value for administrator users — Administrators
• Group Claim value for restricted users — Users

Тестирование интеграции:

• Проверка аутентификации. Попробуйте войти в Gitea через Keycloak, используя учётные записи с разными ролями. Убедитесь, что процесс аутентификации работает без ошибок и пользователи могут успешно входить в систему.
• Проверка прав доступа. Удостоверьтесь, что права доступа работают корректно. Например, пользователь с ролью developer должен иметь возможность просматривать и вносить изменения в определённые репозитории, но не должен иметь доступа к настройкам системы. Пользователь с ролью admin должен иметь полный доступ.
• Анализ логов. Если возникают проблемы, изучите логи Gitea и Keycloak. Логи могут содержать информацию об ошибках аутентификации или других проблемах, которые помогут выявить и устранить неполадки.

5. Устранение возможных проблем:

• Ошибки аутентификации. Если пользователи не могут войти в систему, проверьте правильность указанных в конфигурационном файле Gitea параметров подключения к Keycloak (URL, клиентский идентификатор, секрет). Также убедитесь, что перенаправления (redirect URIs) в Keycloak настроены корректно.
• Неправильная работа прав доступа. Если права доступа не соответствуют ожидаемым, проверьте сопоставление ролей в конфигурационном файле Gitea. Убедитесь, что роли из Keycloak правильно сопоставляются с правами в Gitea.
• Обращение за помощью. Если проблему не удаётся решить самостоятельно, обратитесь к документации Gitea и Keycloak или к сообществу пользователей. На форумах и в чатах можно найти решения типовых проблем или получить помощь от опытных пользователей. Также можно воспользоваться сервисами технической поддержки или обратиться к специалистам, которые имеют опыт работы с этими системами.

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