Реалізація OAuth2 аутентифікації: PKCE, Refresh Rotation, Social Login

Ви запускаєте SaaS і вирішуєте додати вхід через Google. Здавалося б, просте завдання, але ручна реалізація OAuth2 часто призводить до вразливостей: перехоплення authorization code, CSRF-атаки, витік refresh-токенів. Одна помилка — і облікові записи користувачів під загрозою. Ми впровадили безпечну аутентифікацію більш ніж у 30 проєктах — від стартапів до enterprise. У цій статті розповімо, як уникнути типових помилок і реалізувати OAuth2 з PKCE, Refresh Token Rotation та OIDC, скоротивши час розробки на 2–3 тижні.

Типовий сценарій: розробник копіює приклад з документації, забуває про state, не перевіряє підпис id_token і використовує Implicit Flow через простоту. Результат — передбачуваний. Ми пропонуємо системний підхід: від вибору гранту до deployment з моніторингом.

Проблеми, які вирішуємо

• Складність ручної інтеграції. Помилки при генерації state та code_verifier ведуть до CSRF та перехоплення коду. Ми автоматизуємо ці кроки за допомогою перевірених бібліотек.
• Застарілі реалізації. Implicit Flow deprecated — використовуємо Authorization Code з PKCE. Це знижує ризик витоку access token у URL.
• Відсутність ротації refresh-токенів. Без неї вкрадений refresh_token дає зловмиснику необмежений доступ. Впроваджуємо rotation з інвалідацією після кожного використання.

Типові помилки при інтеграції

Розробники часто ігнорують перевірку state у callback-запиті, що відкриває CSRF-атаки. Використовують Implicit Flow, не знаючи, що він deprecated. Не верифікують id_token на сервері — покладаються на клієнтську перевірку. Або зберігають refresh_token у localStorage без шифрування. Кожна з цих помилок може призвести до компрометації облікових записів.

Як працює Authorization Code Flow з PKCE?

Основний потік для веб-застосунків та SPA:

1. Клієнт → IdP: GET /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&scope=openid email&state=random
2. Користувач логіниться у IdP, дає дозвіл
3. IdP → Клієнт: GET /callback?code=AUTH_CODE&state=random
4. Клієнт → IdP backend: POST /oauth/token з кодом → отримує access_token, id_token, refresh_token
5. Клієнт → IdP: GET /userinfo з access_token → профіль користувача

State — захист від CSRF: генерується перед редиректом, перевіряється при поверненні.

PKCE — обов'язковий для SPA та мобільних застосунків, де немає серверного зберігання client_secret. Приклад генерації code_verifier та code_challenge:

// Генерація code_verifier та code_challenge
const verifier = crypto.randomUUID().replace(/-/g, '') + crypto.randomUUID().replace(/-/g, '');
const encoder = new TextEncoder();
const data = encoder.encode(verifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const challenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');

// Зберегти verifier у sessionStorage
sessionStorage.setItem('pkce_verifier', verifier);

// Додати до authorize URL
const url = `${authUrl}?...&code_challenge=${challenge}&code_challenge_method=S256`;

Чому PKCE обов'язковий для SPA?

У SPA client_secret зберігати не можна — він стає публічним. Без PKCE зловмисник може перехопити authorization code (наприклад, через редирект на підроблений URI) та обміняти його на токен. PKCE додає перевірку code_verifier, яка доводить, що запит токена виконало те саме застосунок, яке ініціювало авторизацію. Це робить атаку практично неможливою. Порівняння: Implicit Flow без PKCE має на 80% більше вразливостей, ніж Authorization Code з PKCE.

Реалізація OAuth2-сервера та клієнтів

Якщо ваш застосунок сам є OAuth2-сервером (видає токени для API-клієнтів), використовуємо Laravel Passport. Приклад налаштування:

composer require laravel/passport
php artisan passport:install

// AuthServiceProvider
use Laravel\Passport\Passport;
Passport::routes();
Passport::tokensCan([
    'read:profile' => 'Читати профіль',
    'write:profile' => 'Редагувати профіль',
]);
Passport::tokensExpireIn(now()->addDays(15));
Passport::refreshTokensExpireIn(now()->addDays(30));

OpenID Connect додає id_token (JWT з даними користувача). Верифікація підпису виконується за допомогою JWKS-ендпоінту провайдера. На стороні клієнта (SPA) можна перевірити id_token, використовуючи бібліотеку 'jose'. Однак критично важлива перевірка на сервері бекенду, щоб не допустити підробку.

Чому Refresh Token Rotation критичний?

При кожному обміні refresh_token на нову пару старий інвалідизується. Якщо токен вкрадено, зловмисник не зможе його використати повторно — при спробі він дізнається, що атака сталася, і ми зможемо вжити заходів. Реалізація на Laravel:

$response = Http::post('/oauth/token', [
    'grant_type' => 'refresh_token',
    'refresh_token' => $user->refresh_token,
    ...
]);
$user->update([
    'access_token' => $response->json('access_token'),
    'refresh_token' => $response->json('refresh_token'), // rotate!
    'token_expires_at' => now()->addSeconds($response->json('expires_in')),
]);

Провайдери: Social Login

Для «Увійти через Google/GitHub» використовуємо Socialite (Laravel) або NextAuth. Приклад з Laravel:

Route::get('/auth/google/redirect', fn() => Socialite::driver('google')->redirect());
Route::get('/auth/google/callback', function () {
    $googleUser = Socialite::driver('google')->user();
    $user = User::updateOrCreate(
        ['email' => $googleUser->getEmail()],
        ['name' => $googleUser->getName(), 'avatar' => $googleUser->getAvatar()]
    );
    Auth::login($user, remember: true);
    return redirect('/dashboard');
});

Порівняння потоків OAuth2

Орієнтовні строки по етапах

Більше 7 років досвіду та 30+ реалізованих інтеграцій дозволяють нам скорочувати строки без втрати якості. Додатково знижуємо витрати на безпеку на 40% за рахунок автоматизації.

Входить у роботу: документація потоків, налаштування провайдерів, реалізація PKCE, refresh rotation, верифікація JWT, unit-тестування та підтримка після деплою.

Гарантуємо безпеку: використовуємо PKCE, rotate refresh tokens, валідуємо JWT. Оцінимо ваш проєкт — напишіть нам на пошту або в Telegram, отримайте консультацію безкоштовно. Замовте реалізацію OAuth2 з гарантією безпеки.

Додаткові матеріали: OAuth2 RFC 6749.

Аутентифікація та авторизація: OAuth, JWT, сесії, RBAC, 2FA

На одному проєкті токен JWT із роллю admin: false» міг бути змінений клієнтом на admin: true» — і сервер прийняв його без верифікації підпису. Ми знайшли це на тестовому стенді, коли робили огляд існуючої кодової бази новому замовнику. Причина — застаріла бібліотека jsonwebtoken, яка в певних версіях пропускала алгоритм «none». Наслідки — повний доступ до адміністративного API для будь-якого зареєстрованого користувача. Замовник не знав про це, але ми оцінили ризик, переписали модуль авторизації під ключ і запровадили обов’язкову перевірку алгоритму. Тепер подібних інцидентів немає. За 7+ років ми реалізували понад 50 проєктів із системами аутентифікації та авторизації користувачів — від стартапів до корпоративних рішень, що працюють із фінансовими даними.

Чому JWT не варто зберігати в localStorage?

JWT складається з трьох частин: header (алгоритм), payload (дані), signature (підпис). Підпис верифікує, що payload не змінено. Без перевірки підпису — це просто base64-encoded JSON, який будь-хто може підробити. Помилки, які бачимо в коді регулярно:

• Зберігання в localStorage. LocalStorage доступний будь-якому JS на сторінці — XSS-атака читає токен і відправляє на сервер зловмисника. Access token в пам’яті (змінна модуля), refresh token в httpOnly cookie — правильна схема.
• Довгоживучі access-токени. Access token на 7 днів без можливості відкликання — витік дає 7 днів доступу. Стандарт: 15 хвилин для access token, 30 днів для refresh token з ротацією. При кожному використанні refresh token видається новий, старий інвалідується — якщо старий хтось використовує повторно, це детектується як Token Reuse Attack, уся сім’я токенів відкликається.
• Зберігання секретних даних у payload. JWT payload не зашифровано, лише підписано — його видно в base64. Паролі, платіжні дані, особиста інформація — не в JWT. Алгоритм RS256 (асиметричний) кращий за HS256 (симетричний) у мікросервісній архітектурі: сервіси можуть верифікувати токен публічним ключем, не маючи доступу до секрету для його створення.

Як обрати між сесіями та токенами?

Сесії зберігають стан на сервері (Redis, database) — сервер може миттєво відкликати сесію. При масштабуванні на кілька інстансів потрібен спільний store (Redis Cluster). Cookie з session ID — httpOnly, Secure, SameSite=Strict.

Stateless JWT не вимагають server-side storage, масштабуються горизонтально. Але відкликання токена до завершення терміну — тільки через blacklist (Redis), що частково знімає перевагу stateless.

Для більшості веб-додатків сесії простіші та безпечніші. JWT має сенс для API, що споживаються з мобільного додатку, та для мікросервісної архітектури. Оцініть ваш сценарій — ми допоможемо обрати правильний підхід.

OAuth 2.0 та OpenID Connect

OAuth 2.0 — протокол делегованої авторизації, не аутентифікації. «Увійти через Google» — це OpenID Connect поверх OAuth 2.0, який додає id_token з даними користувача. Authorization Code Flow з PKCE — єдиний правильний flow для браузерних SPA та мобільних додатків. Implicit Flow застарів і небезпечний. PKCE (Proof Key for Code Exchange) захищає від перехоплення authorization code.

Реалізація OAuth сервера: не пишемо з нуля. Keycloak (open source, self-hosted), Auth0, Okta — готові рішення. Laravel Passport або Laravel Sanctum для серверних додатків. NextAuth.js для Next.js — підтримує 50+ провайдерів з коробки. Для B2B продуктів з корпоративними клієнтами — SAML 2.0 SSO. Корпоративні IT-відділи часто вимагають його замість OAuth. @boxyhq/saml-jackson — node.js бібліотека для SAML → OAuth2 адаптера.

RBAC, ABAC, ReBAC — що і коли застосовувати

Role-Based Access Control — у користувача є ролі, у ролей — права. Проста реалізація: user → roles → permissions. Але коли з'являється ресурсна авторизація («користувач може редагувати лише свої пости»), RBAC ускладнюється. У такому разі використовуйте Spatie Laravel Permission (стандарт для Laravel): поліморфні ролі та права, кешування, super-admin через gate. Інтеграція з Eloquent — $user->can('edit posts'), $user->hasRole('editor').

ABAC (Attribute-Based Access Control) — політики на основі атрибутів: користувача, ресурсу, середовища. Потрібен, коли правила доступу складні: «менеджер може переглядати замовлення свого регіону, якщо замовлення створено більше 24 годин тому». Casbin — популярна cross-language бібліотека для ABAC.

ReBAC (Relationship-Based Access Control) — Google Zanzibar model. Доступ визначається графом відносин: «користувач X є учасником команди Y, яка має доступ до проєкту Z». OpenFGA — open source реалізація від Okta.

Як ми це робимо: кейс із впровадження 2FA

Проєкт — платіжний шлюз для маркетплейсу. Потрібно було захистити доступ до операцій виводу коштів. Ми спроєктували систему:

• Основний пароль замінили на комбінацію пароль + TOTP (Google Authenticator). Використали otplib (Node.js) для генерації та верифікації кодів.
• Під час першого підключення 2FA показували QR-код (base32-encoded secret) і генерували 10 одноразових backup-кодів, хешованих bcrypt. Відображали коди лише один раз.
• Secret для TOTP зберігали у зашифрованому вигляді в базі даних (AES-256-GCM, ключ у AWS KMS).
• На стороні фронтенду інтегрували @simplewebauthn/browser для passkeys — біометрична аутентифікація як альтернатива паролю. Публічний ключ зберігали на сервері, private key на пристрої користувача.
• Результат: час на логін зріс на 5 секунд, але кількість зламаних акаунтів упала до нуля за пів року роботи. Гарантія безпеки — на рівні OWASP ASVS Level 2.

Також варто зазначити, що TOTP значно надійніше за SMS-верифікацію через SIM-swapping, тому для фінансових даних ми рекомендуємо TOTP або апаратні ключі.

Типові вразливості, які ми знаходимо

• Broken Object Level Authorization (BOLA/IDOR): /api/orders/12345 повертає замовлення без перевірки, чи належить воно поточному користувачу. Найпоширеніша вразливість API за OWASP. Кожен запит до ресурсу — перевірка через $user->can('view', $order).
• Mass Assignment: User::create($request->all()) — користувач передає is_admin: true в тілі запиту. Laravel вирішує через $fillable / $guarded, але часто забувають.
• Небезпечний CORS: Access-Control-Allow-Origin: * на API з авторизацією по cookie — credentials не передаються з wildcard origin, але якщо хтось зробив Allow-Credentials: true + Allow-Origin: * — це діра.

Penetration testing обов’язковий для продуктів з фінансовими даними або персональними даними користувачів. Ми проводимо аудит коду й інфраструктури на етапі приймання.

Що входить у роботу

Ми передаємо замовнику:

• Документацію архітектури авторизації (flow діаграми, опис токенів, політик доступу).
• Репозиторій із вихідним кодом, покритий unit- та integration-тестами.
• Конфігурацію для CI/CD (GitHub Actions/ GitLab CI) із перевірками безпеки.
• Доступи до середовищ (staging, production) із правами адміністратора.
• Інструкцію з експлуатації та супроводу.
• Підтримку після впровадження — 2 тижні безкоштовних консультацій.

Терміни та вартість

Базова аутентифікація (email/password + OAuth + JWT/сесії): 1–3 тижні. RBAC з детальними політиками доступу: 2–4 тижні. 2FA (TOTP + SMS): 1–2 тижні. WebAuthn/Passkeys: 2–3 тижні. Повна система аутентифікації для SaaS з multi-tenancy: 4–8 тижнів.

Вартість розраховується індивідуально залежно від обсягу та складності. Замовте консультацію — оцінимо ваш проєкт безкоштовно. Отримайте гарантію безпеки вашої авторизації користувачів.