Перейти к основному содержимому

Setting Up Gmail OAuth Authentication

Это руководство проведёт вас через создание приложения Google Cloud для OAuth-аутентификации с Gmail. OAuth обеспечивает более безопасный доступ к аккаунту Gmail по сравнению с традиционной парольной аутентификацией.

Prerequisites​

  • Аккаунт Google (личный или Google Workspace)
  • Доступ к Google Cloud Console
  • URL вашей установки Perfex CRM (для настройки redirect URI)

Step-by-Step Setup​

Step 1: Create a Google Cloud Project​

  1. Перейдите в Google Cloud Console
  2. Нажмите на выпадающий список проектов в верхней части страницы
  3. Нажмите "New Project"
  4. Введите имя проекта (например, "Perfex Mailbox OAuth")
  5. Нажмите "Create"
  6. Дождитесь создания проекта и выберите его

Step 2: Enable Gmail API​

  1. В Google Cloud Console перейдите в "APIs & Services" > "Library"
  2. Найдите "Gmail API"
  3. Нажмите на "Gmail API" в результатах
  4. Нажмите "Enable"
  5. Дождитесь активации API
  1. Перейдите в "APIs & Services" > "OAuth consent screen"
  2. Выберите тип пользователя "External" (если есть Google Workspace, можно выбрать "Internal")
  3. Нажмите "Create"
  4. Заполните обязательную информацию:
    • App name: Имя приложения (например, "Perfex CRM Mailbox")
    • User support email: Ваш email
    • Developer contact information: Ваш email
  5. Нажмите "Save and Continue"
  6. На странице "Scopes" нажмите "Add or Remove Scopes"
  7. Добавьте следующие области:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
  8. Нажмите "Update", затем "Save and Continue"
  9. На странице "Test users" (при типе External):
    • Добавьте ваш Gmail как тестового пользователя
    • Нажмите "Save and Continue"
  10. Проверьте и нажмите "Back to Dashboard"

Step 4: Create OAuth 2.0 Credentials​

  1. Перейдите в "APIs & Services" > "Credentials"
  2. Нажмите "Create Credentials" > "OAuth client ID"
  3. Выберите тип приложения "Web application"
  4. Введите имя OAuth-клиента (например, "Perfex Mailbox Client")
  5. В "Authorized redirect URIs" нажмите "Add URI"
  6. Добавьте redirect URI в формате:
https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

Замените your-domain.com на фактический домен Perfex CRM.

  1. Нажмите "Create"
  2. ВАЖНО: Скопируйте и сохраните оба:
    • Client ID
    • Client Secret (нажмите "Show" для отображения)

Step 5: Configure in Perfex CRM​

  1. Перейдите в область администрирования Perfex CRM
  2. Навигация Mailbox > Configuration
  3. Выберите "OAuth2" как метод аутентификации
  4. Выберите "Gmail" как провайдера
  5. Введите Client ID в поле "Gmail Client ID"
  6. Введите Client Secret в поле "Gmail Client Secret"
  7. Нажмите "Save Configuration"
  8. Нажмите кнопку "Connect Gmail"
  9. Авторизуйте приложение во всплывающем окне Google
  10. Должно появиться сообщение об успешном подключении

Important Limitations & Considerations​

Google Test App Limitations​

These limitations are imposed by Google, not by our software.

  1. Token Expiry (7 Days) - Непроверенные приложения (в режиме тестирования) имеют OAuth-токены со сроком 7 дней. После 7 дней пользователям необходимо повторно авторизовать подключение. Это политика безопасности Google для непроверенных приложений.

  2. Test User Restrictions - Только пользователи, добавленные в список "Test users", могут использовать OAuth-приложение. Максимум 100 тестовых пользователей. Ограничение действует до проверки и публикации приложения.

  3. App Verification Process - Для снятия 7-дневного срока действия токена необходимо отправить приложение на проверку Google. Проверка может занять несколько недель (обычно 4-8 недель).

App Verification & Publishing​

Для снятия ограничений:

  1. Submit for Verification

    • В Google Cloud Console перейдите в "OAuth consent screen"
    • Нажмите кнопку "PUBLISH APP"
    • Заполните форму проверки (назначение, функциональность, политика конфиденциальности, условия использования, видео (опционально))
    • Отправьте на проверку

  2. Verification Timeline

    • Начальная проверка: 1-2 недели
    • Дополнительные запросы: переменная (если Google нужны уточнения)
    • Финальное одобрение: 4-8 недель (типично)

  3. After Verification

    • Токены больше не истекают через 7 дней
    • Ограничения тестовых пользователей сняты
    • Приложение доступно любому пользователю Gmail

Production vs Testing​

  • Testing Mode: Быстрая настройка, но токены истекают каждые 7 дней
  • Production Mode: Требуется проверка, но токены не истекают
  • Выбор за вами - наше ПО работает в обоих режимах

Token Refresh​

Наш модуль автоматически обрабатывает обновление токенов, когда возможно. Однако:

  • Непроверенные приложения: Токены истекают через 7 дней, требуется ручная повторная авторизация
  • Проверенные приложения: Токены обновляются автоматически без участия пользователя

Notes​

  • Redirect URI должен точно совпадать с настройкой в Google Cloud Console
  • Храните Client Secret в безопасности - никогда не публикуйте
  • При смене домена обновите redirect URI в Google Cloud Console
  • OAuth-поток полностью обрабатывается Google - наш модуль только инициирует и получает callback

Troubleshooting​

Ошибка "Redirect URI mismatch":

  • Убедитесь, что redirect URI в Google Cloud Console точно совпадает: https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
  • Проверьте завершающие слэши и HTTP vs HTTPS

"Token expired" через 7 дней:

  • Ожидаемо для непроверенных приложений (политика Google)
  • Повторная авторизация: нажмите "Connect Gmail" снова
  • Чтобы избежать: отправьте приложение на проверку Google

Ошибка "Access blocked":

  • Убедитесь, что email добавлен в "Test users" (для непроверенных приложений)
  • Проверьте, что Gmail API включён в проекте Google Cloud

Не удаётся найти Gmail API:

  • Убедитесь, что вы в правильном проекте Google Cloud
  • Попробуйте поиск "Gmail" в API Library

Additional Resources​

к сведению

7-дневный срок действия токена и ограничения тестовых пользователей — это политики безопасности Google для непроверенных приложений. Эти ограничения не накладываются нашим ПО. После проверки приложения Google эти ограничения снимаются.