Nextcloud — отличное решение для хранения файлов, но управление пользователями вручную становится головной болью при масштабировании. Keycloak позволяет централизовать аутентификацию, обеспечивая безопасность, поддержку MFA (двухфакторной аутентификации) и удобный вход через корпоративный портал.
В этом руководстве мы настроим сквозную авторизацию, где Keycloak выступает провайдером удостоверений (IdP), а Nextcloud — клиентом (RP).
📋 Что нам понадобится
- Keycloak: уже установленный и запущенный (версия 21+ или Red Hat SSO).
- Nextcloud: установленный экземпляр (желательно последней версии).
- Модуль OIDC: для Nextcloud он называется Social Login.
- HTTPS: крайне рекомендуется использовать SSL/TLS на обеих сторонах.
Настройка клиента в Keycloak
В целом настройка Keycloak аналогична настройке для Gitea и таким же образом сначала создадим точку входа для Nextcloud в Keycloak.
- Зайдите в административную панель Keycloak.
- Выберите нужный или создайте новый Realm (область безопасности).
- Перейдите в раздел Clients → Create client.
- Заполните основные поля:
- Client type: OpenID Connect.
- Client ID: nextcloud (или любое уникальное имя, например my-company-nextcloud).
- Нажмите Next.
Конфигурация клиента (Capability config)
- Client authentication: On (включить). Это позволит Nextcloud использовать Client Secret.
- Authorization: Off (если не планируете сложные права доступа внутри Keycloak).
- Authentication flow: оставьте стандартные настройки (Standard flow).
Root URL и Redirect URIs
Это критически важный шаг. Nextcloud должен знать, куда отправлять пользователя после входа.
- Root URL: https://your-nextcloud-domain.com/
- Valid redirect URIs: https://your-nextcloud-domain.com/index.php/apps/sociallogin/custom_oidc/
- Важно: если у вас кастомный плагин или другая версия модуля, URI может отличаться, но чаще всего используется путь /apps/sociallogin/custom_oidc/
- Web origins: https://your-nextcloud-domain.com/
Сохраните настройки.
Получение данных для Nextcloud
Перейдите во вкладку Credentials вашего нового клиента.
- Скопируйте Client secret. Он понадобится нам позже.
Настройка Realm (маппинг атрибутов)
Чтобы Nextcloud знал имя и почту пользователя, нужно настроить сопоставление полей (Mappers).
- В настройках клиента перейдите на вкладку Client scopes.
- Нажмите на scope по умолчанию (обычно это название клиента + -dedicated или просто выберите roles, email, profile).
- Перейдите в Mappers.
- Убедитесь, что есть мапперы для:
- email → email;
- username → preferred_username (или
nickname); - name → name.
Если их нет, создайте их вручную:
- Protocol: OpenID Connect.
- Mapper Type: User Attribute (для имени) или User Property (для email).
- Token Claim Name: name, email, preferred_username.
Установка и настройка плагина Social Login в Nextcloud
Установка приложения Social Login
- Зайдите в ваш Nextcloud под администратором.
- Перейдите в Apps → найдите «Social Login» (by Christian Gräfe) и установите его.
- После установки перейдите в настройки администратора (Settings → Administration → Social Login).
Настройте основные параметры как вам больше нравится. В моем случае получилось так.
- Не разрешать создание учётной записи, если адрес электронной почты уже используется другой учётной записью
- Обновлять профиль пользователя при каждом входе
- Автоматически создавать группы, если они не существуют
- Запрещать вход пользователям без сопоставленных групп
- Запрещать вход пользователям без назначенных групп
Конфигурация провайдера
Нажмите кнопку «Custom OpenID Connect».
Заполните форму следующими данными:
| Параметр | Значение | Описание |
|---|---|---|
| Internal name | keycloak | Имя для отображения внутри админки NC. |
| Title | Company SSO | Текст на кнопке входа («Войти через Company SSO»). |
| Authorize URL | https://keycloak.domain.com/realms/<YOUR_REALM>/protocol/openid-connect/auth | Адрес авторизации Keycloak. |
| Token URL | https://keycloak.domain.com/realms/<YOUR_REALM>/protocol/openid-connect/token | Адрес получения токена. |
| User Info URL | https://keycloak.domain.com/realms/<YOUR_REALM>/protocol/openid-connect/userinfo | Профиль пользователя. |
| Logout URL | (опционально) | Можно оставить пустым или указать эндпоинт логаута Keycloak. |
| Client ID | nextcloud | Тот самый ID из шага 1. |
| Client Secret | ваш_секрет_из_Keycloak | Скопированный ранее секрет. |
| Scope | openid email profile | Обязательные скоупы. |
Маппинг полей (Attribute Mapping)
Укажите, откуда брать данные:
- User ID key: sub (это уникальный идентификатор пользователя в Keycloak, менять не стоит).
- Nickname key: preferred_username.
- Email key: email.
- Name key: name.
💡 Совет: включите опцию «Auto create users», если хотите, чтобы аккаунты создавались автоматически при первом входе. Также включите «Disable login form», если хотите принудительно перенаправлять всех на Keycloak.
Группы и права доступа
Интеграция работает, но пользователи заходят с правами «по умолчанию». Чтобы управлять доступом через Keycloak:
- В настройках Social Login нажмите на созданный провайдер (keycloak) и откройте вкладку Groups.
- Создайте связь: группа в Keycloak → группа в Nextcloud.
- Например, роль nc_admins в Keycloak должна давать группу admin в Nextcloud.
- В Keycloak зайдите в Roles, создайте роль (например, nextcloud_admin) и назначьте её нужным пользователям.
- В Nextcloud убедитесь, что группы с такими именами существуют, или разрешите их автоматическое создание.
Тонкая настройка (config.php)
Иногда возникают проблемы с циклическими редиректами или проверкой сертификатов. Добавьте следующие параметры в файл config/config.php вашего Nextcloud:
// Отключаем принудительную проверку HTTPS для внутренних вызовов к Keycloak,
// если у вас самоподписанный сертификат на Keycloak (НЕ РЕКОМЕНДУЕТСЯ ДЛЯ PROD)
'allow_local_remote_servers' => true,
// Если Nextcloud за обратным прокси (Nginx/Traefik)
'overwriteprotocol' => 'https',
'overwritewebroot' => '/',Для работы Logout (выхода) добавьте в конфиг:
'logout_url' => 'https://keycloak.domain.com/realms/<REALM>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2Fnextcloud.domain.com'Решение часто возникающих при настройке проблем проблем
Ошибка «Invalid redirect URI»
Проверьте точное написание URL в поле Valid redirect URIs в Keycloak. Не должно быть лишних слешей в конце или разницы между http и https.
Пользователь создаётся без почты или имени
Проверьте вкладку Mappers в Client Scopes Keycloak. Убедитесь, что claim names (email, name) совпадают с тем, что вы указали в настройках Social Login в Nextcloud.
Циклическая переадресация (Loop)
Обычно возникает, если пользователь залогинился в Nextcloud локально, а потом пытается зайти через SSO.
- Решение: в настройках Social Login поставьте галочку «Hide login form». Тогда пользователь всегда будет уходить на Keycloak.
Проблема с CORS / Mixed Content
Если Keycloak и Nextcloud на разных доменах, убедитесь, что в Keycloak заполнено поле Web Origins. Обычно туда ставят + (разрешить всё) или конкретные домены.
Итоговый результат
Теперь процесс входа выглядит так:
- Пользователь заходит на nextcloud.yourcompany.com.
- Нажимает кнопку «Company SSO».
- Перенаправляется на страницу логина Keycloak.
- Вводит пароль (и проходит MFA, если настроено).
- Keycloak возвращает токен Nextcloud.
- Пользователь авторизован в Nextcloud под своей учётной записью с правами, привязанными к ролям Keycloak.
