Реалізація OAuth 2.0 аутентифікації для веб-застосунку

Впровадження OAuth2 аутентифікації для веб-додатків

OAuth2 — це протокол делегованої авторизації. Користувач дозволяє сторонній програмі доступ до своїх даних на іншому сервісі без передачі пароля. Google, GitHub та Facebook діють як Identity Providers (IdPs), а ваш додаток — це Client. OAuth2 ≠ аутентифікація — це про авторизацію доступу до ресурсів, але аутентифікація будується на його основі через OpenID Connect (OIDC).

Authorization Code Flow (основна)

Послідовність для веб-додатків:

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

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

PKCE (Proof Key for Code Exchange) — обов'язковий для SPA та мобільних додатків, де немає зберігання client_secret на сервері:

// Генерування 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);

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

Впровадження OAuth2-сервера на Laravel (Laravel Passport)

Якщо ваш додаток сам є OAuth2-сервером (видає токени для API-клієнтів або мобільного додатка):

composer require laravel/passport
php artisan passport:install

// User model
use HasApiTokens;

// AuthServiceProvider
Passport::routes();
Passport::tokensExpireIn(now()->addDays(15));
Passport::refreshTokensExpireIn(now()->addDays(30));
Passport::personalAccessTokensExpireIn(now()->addMonths(6));

// Створюємо клієнт для SPA (з PKCE)
php artisan passport:client --public
// Створюємо клієнт для server-to-server
php artisan passport:client --client

Scopes для гранульованого контролю доступу:

// AuthServiceProvider
Passport::tokensCan([
    'read:profile'  => 'Читати профіль',
    'write:profile' => 'Редагувати профіль',
    'read:orders'   => 'Читати замовлення',
    'write:orders'  => 'Створювати замовлення',
]);

// Захист маршрутів за scope
Route::middleware(['auth:api', 'scope:read:orders'])->get('/orders', ...);

Client Credentials Flow (Machine-to-Machine)

Для server-to-server без участі користувача:

// Отримуємо токен (мікросервіс A запитує токен у OAuth-сервера)
$response = Http::post('https://auth.example.com/oauth/token', [
    'grant_type'    => 'client_credentials',
    'client_id'     => config('services.microservice_a.client_id'),
    'client_secret' => config('services.microservice_a.client_secret'),
    'scope'         => 'read:inventory write:orders',
]);

$accessToken = $response->json('access_token');
$expiresIn   = $response->json('expires_in'); // секунди

// Кешуємо токен до спливання
Cache::put('microservice_token', $accessToken, now()->addSeconds($expiresIn - 60));

Introspection та валідація токена

Сервер ресурсів перевіряє токен:

// Варіант 1: Локальна перевірка JWT (найшвидший)
$token = JWT::decode($accessToken, $publicKey, ['RS256']);

// Варіант 2: Token introspection endpoint (RFC 7662)
$response = Http::withBasicAuth($resourceServerId, $resourceServerSecret)
    ->post('https://auth.example.com/oauth/introspect', [
        'token' => $accessToken,
    ]);

$data = $response->json();
if (!$data['active']) {
    return response()->json(['error' => 'Token inactive'], 401);
}

OIDC — аутентифікація на основі OAuth2

OpenID Connect додає id_token (JWT з даними користувача) до OAuth2:

// Декодуємо id_token (після перевірки підпису)
const [header, payload, signature] = idToken.split('.');
const claims = JSON.parse(atob(payload));

// claims містить:
// sub: "user_123"          — унікальний ID користувача у IdP
// email: "[email protected]"
// name: "John Doe"
// picture: "https://..."
// iss: "https://accounts.google.com" — хто видав токен
// aud: "your_client_id"   — для кого токен
// exp: 1735689600          — дата спливання

// КРИТИЧНО ВАЖЛИВО: перевіряйте підпис перед використанням claims!
import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://accounts.google.com/.well-known/jwks.json'));
const { payload } = await jwtVerify(idToken, JWKS, {
  issuer: 'https://accounts.google.com',
  audience: process.env.GOOGLE_CLIENT_ID,
});

Refresh Token Rotation

// При спливанні access_token — обмін refresh_token на нову пару
$response = Http::post('/oauth/token', [
    'grant_type'    => 'refresh_token',
    'refresh_token' => $user->refresh_token,
    'client_id'     => config('passport.client_id'),
    'client_secret' => config('passport.client_secret'),
    'scope'         => '',
]);

$user->update([
    'access_token'  => $response->json('access_token'),
    'refresh_token' => $response->json('refresh_token'), // ротація!
    'token_expires_at' => now()->addSeconds($response->json('expires_in')),
]);

Refresh Token Rotation: кожного разу при використанні refresh_token він інвалідується та видається новий. Якщо хтось використав украдений refresh_token, старий уже невалідний і атака виявляється.

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

Для «Увійти через Google/GitHub» — використовуйте Socialite (Laravel) або Passport.js/next-auth:

// Socialite
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(),
            'google_id'         => $googleUser->getId(),
            'email_verified_at' => now(),
        ]
    );

    Auth::login($user, remember: true);
    return redirect('/dashboard');
});

Терміни

OAuth2-сервер з Passport, authorization code + client credentials, PKCE для SPA, scopes, introspection: 1–2 тижні. Social Login (Google, GitHub, VK) через Socialite: 2–3 дні. OIDC з JWT-верифікацією та refresh rotation: 3–5 днів.