Щоб тестувати OAuth-колбеки локально, потрібен публічний HTTPS-URL, що вказує на ваш локальний застосунок. OAuth-провайдери після автентифікації перенаправляють користувача на зареєстрований URL колбека — і більшість вимагає HTTPS, який чистий localhost не забезпечує без додаткового налаштування.
Чому redirect URI блокують localhost
Провайдери OAuth 2.0 перевіряють параметр redirect_uri за білим списком зареєстрованих URL. Під час розробки ваш колбек може виглядати так:
https://your-app.portpreview.dev/auth/callbackБез тунелю ви або реєструєте http://localhost:3000/auth/callback (дозволено деякими провайдерами, але не всіма), або деплоїте на staging за кожної зміни авторизації. Тунель до localhost дає справжній HTTPS-ендпоінт на вашій машині.
Що потрібно для локального тестування OAuth
- Облікові дані OAuth-застосунку (client ID і secret) від провайдера.
- Локальний застосунок із маршрутами авторизації для запуску входу й обробки колбека.
- URL тунелю, зареєстрований як дозволений redirect URI в панелі провайдера.
- Змінні середовища, що вказують на URL тунелю під час розробки.
Покроково: локальне тестування OAuth з PortPreview
- Запустіть застосунок локально з увімкненими маршрутами OAuth.
- Виконайте
npx portpreview 3000, щоб отримати публічний HTTPS-URL. - Додайте URL колбека (наприклад,
https://your-app.portpreview.dev/auth/callback) до дозволених redirect URI вашого OAuth-провайдера. - Оновіть локальне середовище, щоб воно використовувало URL тунелю як базовий.
- Запустіть OAuth-флоу в браузері й пройдіть повний цикл редиректу.
- Перевірте обмін токенами, створення сесії та обробку помилок.
Поради щодо провайдерів
Google OAuth
Google дозволяє http://localhost для розробки, але тестування через HTTPS-тунелі перевіряє поведінку, близьку до продакшену, зокрема прапорці secure-cookie й політики змішаного контенту.
GitHub OAuth
GitHub вимагає точного збігу redirect URI. Зареєструйте URL тунелю в налаштуваннях OAuth-застосунку й оновлюйте його при зміні сесії тунелю або використовуйте стабільний субдомен, якщо провайдер тунелю це підтримує.
Auth0 та корпоративні IdP
Корпоративні провайдери ідентичності часто вимагають HTTPS-колбеки й іноді повністю забороняють localhost. Тунелі — стандартний обхідний шлях для локального тестування інтеграцій SAML і OIDC.
Поширені помилки локального тестування OAuth
- Невідповідність redirect URI: URL колбека має збігатися точно, разом із кінцевими слешами й регістром шляху.
- Застарілий URL тунелю: якщо URL тунелю змінюється між сесіями, оновіть білий список провайдера.
- Параметр state не перевіряється: завжди перевіряйте параметр
stateдля захисту від CSRF, навіть під час розробки. - Проблеми з доменом cookie: сесійні cookie можуть не зберігатися, якщо налаштування домену конфліктують із хостнеймом тунелю.
Питання безпеки
OAuth-колбеки несуть коди авторизації, які потрібно обмінювати на боці сервера. Ніколи не розкривайте client secret у фронтенд-коді й сприймайте URL тунелів як тимчасові ендпоінти розробки, а не продакшен-домени. Прочитайте наш посібник із безпеки тунелів до localhost для найкращих практик.
Діліться OAuth-флоу з командою
Коли продукту або QA треба протестувати вхід через соцмережі, діліться URL тунелю замість деплою на staging. Дивіться як поділитися локальним dev-сервером для спільних воркфлоу.
Приєднайтеся до списку очікування PortPreview, щоб спростити тестування OAuth і вебхуків з одного тунелю.