Как настроить почтовое приложение Nextcloud с аутентификацией OAuth2

OAuth2 — это предпочтительный способ подключения многих почтовых аккаунтов к Nextcloud Mail, поскольку почтовый провайдер выдает токены вместо того, чтобы требовать от Nextcloud постоянного использования обычного пароля почтового ящика пользователя. Однако на практике хорошая настройка определяется не тем, успешно ли закрывается окно согласия OAuth. Полезным результатом является то, что Nextcloud Mail может загружать папки по протоколу IMAP, отправлять почту по протоколу SMTP, обновлять аутентификацию без повторных запросов пользователя и продолжать это делать после истечения срока действия первого токена доступа.

В этом руководстве описаны две интеграции OAuth, которые Nextcloud Mail документирует напрямую: учетные записи Google и размещенные учетные записи Microsoft Outlook/Microsoft 365. По состоянию на 6 октября 2026 года в магазине приложений Nextcloud в качестве стабильной версии для Nextcloud 32–35 указана Mail 5.12.3, а в текущем руководстве администратора описана настройка Google OAuth и Microsoft XOAUTH2. Если вы используете более старую версию Mail, обновите ее в пределах диапазона совместимости, поддерживаемого вашим сервером Nextcloud, прежде чем устранять неполадки, которые могли уже измениться.

В качестве официальных источников информации здесь использованы руководство администратора Nextcloud Mail , страница Nextcloud Mail в App Store , документация Google по OAuth для IMAP, POP и SMTP , а также документация Microsoft по OAuth для IMAP и SMTP .

Что должна обеспечить успешная настройка OAuth2 для почты Nextcloud?

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

• Провайдер перенаправляет пользователя обратно на тот же URI перенаправления Nextcloud, который настроен для клиента OAuth.
• Nextcloud Mail открывает почтовый ящик и отображает список папок, не запрашивая повторно обычный пароль от почтового ящика.
• Новые сообщения поступают через IMAP, и вручную обновленный почтовый ящик обновляется без ошибки аутентификации.
• Тестовое сообщение, отправленное из Nextcloud Mail, принимается по протоколу SMTP и отображается в папке «Отправленные».
• По истечении достаточного времени для истечения срока действия кратковременного токена доступа учетная запись продолжает работу с помощью токена обновления, вместо того чтобы каждый раз входить в систему заново.

Если настройка проходит только этап подтверждения согласия, но не проходит тесты IMAP и SMTP, считайте ее неполной. Авторизация OAuth и доступ по почтовому протоколу — это связанные, но отдельные этапы.

Шаг 1: Убедитесь, что ваш провайдер соответствует поддерживаемому пути OAuth.

В настоящее время Nextcloud Mail предоставляет встроенную обработку OAuth для учетных записей Google и Microsoft. Почтовые серверы Google поддерживают OAuth 2.0 с SASL XOAUTH2 для IMAP и SMTP. Microsoft документирует поддержку OAuth2 для IMAP, POP и SMTP в Microsoft 365 и Outlook.com. Затем Nextcloud использует выданный провайдером токен при аутентификации в почтовых протоколах.

Не следует предполагать, что любой почтовый сервер с поддержкой OpenID Connect или OAuth2 может быть подключен к одному и тому же интерфейсу. Запрос на улучшение Nextcloud Mail 2026 года для универсальных сторонних поставщиков OAuth/OpenID остался лишь предложением по улучшению, а не документированным общим путем настройки. Если ваш поставщик не является ни Google, ни Microsoft, проверьте поддержку именно этого поставщика, прежде чем развертывать систему на основе OAuth2. Обсуждение проекта доступно в теме «Улучшение Nextcloud Mail для универсальных поставщиков OAuth2» .

Настройка Gmail с использованием OAuth2

Шаг 2: Скопируйте URI перенаправления Gmail из Nextcloud.

Войдите в систему как администратор Nextcloud, откройте настройки администрирования, перейдите в раздел «Групповое ПО» и найдите интеграцию с Gmail . В руководстве администратора Nextcloud указано, что в этом разделе необходимо ввести идентификатор клиента Google и секретный ключ клиента. Используйте URI перенаправления, отображаемый вашим экземпляром при настройке Google; не восстанавливайте путь из примера, поскольку обратные прокси-серверы, изменения корневого каталога веб-сервера и структура развертывания могут повлиять на внешний видимый URL-адрес.

Проверка качества: URI перенаправления должен использовать ваше рабочее имя хоста HTTPS и быть доступен из браузера пользователя. Если Nextcloud отображает внутреннее имя хоста, в то время как пользователи обращаются к общедоступному имени хоста, сначала исправьте конфигурацию URL-адреса Nextcloud/прокси. OAuth не компенсирует несоответствие общедоступного URL-адреса.

Шаг 3: Создайте клиент Google OAuth.

В Google Cloud настройте параметры платформы аутентификации Google/согласия для проекта и создайте клиент OAuth для веб-приложения . Добавьте URI перенаправления, скопированный из Nextcloud, в качестве авторизованного URI перенаправления. Google требует, чтобы URI перенаправления в запросе авторизации точно соответствовал авторизованному значению; важны схема, регистр, путь и завершающая косая черта. Google описывает это поведение в документе « Использование OAuth 2.0 для веб-серверных приложений» .

Доступ к почте Gmail важен с точки зрения соответствия нормативным требованиям. Google классифицирует широкий спектр доступа, включая использование IMAP, SMTP и POP3, как ограниченный. В зависимости от того, является ли приложение внутренним, находится на стадии тестирования или предназначено для более широкого использования в производственной среде, могут применяться требования Google по проверке. Перед подключением большого количества пользователей ознакомьтесь с документациейhttps://mail.google.com/ Google по ограниченным областям доступа и рекомендациями по проверке приложений OAuth .

Шаг 4: Сохраните идентификатор клиента Google и секретный ключ в Nextcloud.

Вернитесь в настройки администрирования > Групповое ПО > Интеграция с Gmail , вставьте идентификатор клиента Google и секретный ключ клиента и сохраните. Избегайте раскрытия секретного ключа в скриншотах, заявках, истории командной строки или общих заметках. Если вы позже измените секретный ключ клиента OAuth, незамедлительно обновите Nextcloud и запланируйте контролируемую проверку существующих учетных записей.

Шаг 5: Добавьте учетную запись Gmail и подтвердите согласие.

Откройте Nextcloud Mail от имени пользователя и добавьте учетную запись Gmail. Текущая версия Mail распознает Gmail по стандартным IMAP/SMTP-хостам Gmail и переключает метод аутентификации на XOAUTH2, если администратор настроил Google OAuth. Документация Google imap.gmail.com:993описывает IMAP через SSL и smtp.gmail.comс TLS на поддерживаемых SMTP-портах.

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

Не останавливайтесь на отметке «учетная запись подключена». Откройте папку «Входящие», откройте хотя бы одно сообщение, отправьте сообщение во второй почтовый ящик, который вы контролируете, ответьте на него и подтвердите отправку и получение сообщения. Этот тест доказывает гораздо больше, чем простое перенаправление OAuth.

Настройте Microsoft 365 или Outlook с использованием OAuth2.

Шаг 6: Зарегистрируйте приложение в Microsoft Entra.

Откройте центр администрирования Microsoft Entra и создайте регистрацию приложения. В руководстве Nextcloud администраторам рекомендуется выбрать типы учетных записей, разрешающие использование организационных и личных учетных записей Microsoft, а также настроить URI перенаправления веб-сайта, скопированный из Nextcloud. Если ваша организация намеренно использует однопользовательскую среду, не следует слепо копировать пример для многопользовательской среды: согласуйте поддерживаемые типы учетных записей и настройки среды с вашей политикой идентификации.

Microsoft требует регистрации URI перенаправления в приложении. Несоответствие может привести к ошибкам, например, к ошибке AADSTS50011. Текущие рекомендации Microsoft содержатся в документе « Рекомендации и ограничения по использованию URI перенаправления» .

Шаг 7: Запишите идентификатор клиента и создайте секретный ключ клиента.

Скопируйте идентификатор приложения (клиента) . Затем откройте «Сертификаты и секреты» , создайте новый секрет клиента и сразу же скопируйте значение секрета . Microsoft заявляет, что значение больше не отображается после того, как вы покинете страницу. Компания также ограничивает срок действия секрета клиента 24 месяцами или менее и рекомендует более короткий срок действия в своей текущей документации по регистрации приложений.

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

Шаг 8: Введите учетные данные Microsoft в Nextcloud.

В настройках администрирования Nextcloud откройте раздел «Групповое ПО» и область интеграции с Microsoft. Введите идентификатор клиента и секретный ключ клиента. В официальном руководстве Nextcloud commonдля общей конфигурации размещенного Outlook используется значение клиента, и в нем прямо предупреждается, что пользовательский идентификатор клиента выходит за рамки этого базового руководства, если вы также не изменили поддерживаемые типы учетных записей.

Что касается разрешений базового протокола, Microsoft описывает делегированные области действия, в том числе https://outlook.office.com/IMAP.AccessAsUser.Allдля IMAP и https://outlook.office.com/SMTP.SendSMTP, а также offline_accessслучаи, когда требуется токен обновления. Nextcloud формирует поток поставщика; вам все равно следует убедиться, что политики арендатора и правила условного доступа разрешают запрошенный делегированный доступ.

Шаг 9: Подключите учетную запись Microsoft и подтвердите почтовый ящик.

Добавьте адрес Outlook или Microsoft 365 в Nextcloud Mail и продолжите процесс входа/согласия Microsoft. В руководстве администратора Nextcloud поясняется, что после настройки OAuth пароль, введенный при создании учетной записи, удаляется, и пользователю предлагается дать согласие Microsoft.

Повторюсь, видимый результат подтверждения согласия — это лишь промежуточный сигнал. Убедитесь, что список папок загружается, тестовое сообщение можно прочитать, сообщение можно отправить, и папка «Отправленные» содержит ожидаемую копию.

Как определить, работает ли OAuth2 на самом деле?

Когда следует изменить свой подход

Измените конфигурацию приложения OAuth, если URI перенаправления, поддерживаемая аудитория учетных записей, настройки арендатора или конфигурация согласия не соответствуют вашей конфигурации. Повторные попытки не устранят структурное несоответствие.

Измените конфигурацию URL-адреса развертывания/прокси, если Nextcloud генерирует внутренний, HTTP- или иной некорректный публичный адрес обратного вызова. Сначала исправьте канонический внешний URL-адрес, а затем пересоздайте или обновите URI перенаправления поставщика.

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

Рассматривайте другой метод аутентификации только в том случае, если поставщик услуг и ваша политика безопасности явно это разрешают. Например, в интерфейсе Nextcloud Mail указано, что пароль приложения Google может быть альтернативой, если Google OAuth не настроен, а учетная запись Google использует двухфакторную аутентификацию. Это не эквивалентно OAuth2 и не должно рассматриваться как предпочтительная замена в масштабах всей организации только потому, что его проще настроить.

Известные ограничения и меры предосторожности при устранении неполадок в 2026 году.

В истории проекта Nextcloud Mail есть важное диагностическое замечание. В июле 2026 года разработчики подтвердили сообщение об ошибке, из-за которой ошибки OAuth на стороне провайдера могли по-прежнему отображать ту же страницу перенаправления «Учетная запись подключена» как успешную авторизацию. В отчете, касающемся непосредственно Microsoft, была выявлена ​​та же схема контроллера для Google. В отдельном отчете 2026 года описывались трудности с повторным подключением учетной записи после того, как ее токен обновления стал непригодным для использования. Эти сообщения были отправлены для кода Mail версии 5.10.7; не следует предполагать, что каждая версия будет затронута навсегда, но и не следует использовать страницу перенаправления как единственное доказательство успеха.

Вы можете ознакомиться с проблемой обработки ошибок переадресации OAuth и проблемой повторного подключения OAuth в проекте . Если вы устраняете неполадки в текущей версии, сначала проверьте установленную версию Mail и последние примечания к выпуску, прежде чем применять обходные пути, написанные для более старой ветки.

Контрольный список окончательной проверки

• Убедитесь, что установленная версия почтового приложения поддерживается вашей версией сервера Nextcloud.
• Используйте URI перенаправления, отображаемый реальным экземпляром Nextcloud, и зарегистрируйте его точно у провайдера.
• Для Google проверьте целевую аудиторию OAuth, конфигурацию согласия, требования к ограничению области действия и статус работы в производственной/тестовой среде.
• Для Microsoft проверьте поддерживаемые типы учетных записей, выбор арендатора, идентификатор клиента, действительность секретного ключа клиента, а также любые политики условного доступа или согласия администратора.
• Перед широким внедрением конфигурации подключите одну пилотную учетную запись.
• Протестируйте загрузку папки «Входящие», чтение сообщений, отправку, сохранение в папке «Отправленные», а также последующее обновление токена.
• Регистрируйте истечение срока действия и право собственности на секретные ключи клиента, чтобы ротация учетных данных не привела к незапланированному сбою.

OAuth2 улучшает модель аутентификации для Nextcloud Mail, но не устраняет необходимости управлять политиками провайдера, URI перенаправления, учетными данными приложений и доступом к почтовому протоколу. Конфигурация готова к использованию в производственной среде, когда весь процесс — авторизация провайдера, обновление токенов, получение IMAP-токенов и отправка SMTP-токенов — работает предсказуемо в соответствии с политиками, применяемыми к вашим пользователям.