OAuth 2.x и OpenID Connect

01Идея: ключ для парковщика, а не ключ от дома

У некоторых машин есть valet key — ключ для парковщика: он заводит двигатель, но не открывает багажник. OAuth выдаёт приложениям такие ключи. Участвуют четыре роли. Resource owner — пользователь. Client — приложение, которому нужен доступ. Authorization server аутентифицирует пользователя и выдаёт токены. Resource server — это API, который принимает токены. Пользователь входит только на сервере авторизации и одобряет конкретные scopes — «читать ваш календарь», — а клиент получает access token, действующий для этих scopes и ограниченное время. Клиент никогда не видит пароль. Важное различие: OAuth 2.0 — это про авторизацию (что приложению разрешено делать), а не про аутентификацию (кто пользователь). Использовать голый OAuth access token как доказательство личности — классическая ошибка; ровно этот пробел и закрывает OpenID Connect.

• Resource owner: пользователь
• Client: веб-, мобильное или серверное приложение
• Authorization server: выполняет вход пользователя, выдаёт токены
• Resource server: ваш API, проверяет токены

02Authorization code flow с PKCE, шаг за шагом

Это рекомендуемый flow для веб-приложений, SPA и мобильных приложений. Клиент создаёт случайный code_verifier и отправляет его SHA-256-хэш (code_challenge) в запросе авторизации. Пользователь входит и даёт согласие, а сервер делает редирект обратно с одноразовым authorization code. Клиент по back channel обменивает код плюс исходный verifier на токены. PKCE (Proof Key for Code Exchange, RFC 7636) означает, что украденный код бесполезен без verifier, который никогда не покидал приложение. Параметр state защищает от CSRF на редиректе, а в OIDC nonce привязывает ID token к этому входу. Redirect URI должны быть зарегистрированы и совпадать точно. OAuth 2.1, на конец 2026 года всё ещё черновик IETF, но уже отражённый в RFC 9700 (OAuth 2.0 Security Best Current Practice), требует PKCE для всех клиентов и убирает implicit и password grants.

1# 1) Browser is redirected to the authorisation server
2GET https://auth.example.com/authorize?response_type=code
3  &client_id=web-app
4  &redirect_uri=https://app.example.com/callback
5  &scope=openid%20profile%20email%20orders:read
6  &state=af0ifjsldkj&nonce=n-0S6_WzA2Mj
7  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
8  &code_challenge_method=S256
9 
10# 2) Back channel: exchange the code for tokens
11POST https://auth.example.com/token
12Content-Type: application/x-www-form-urlencoded
13 
14grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
15&redirect_uri=https://app.example.com/callback
16&client_id=web-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

03Токены: access, refresh и ID token

Access token — это то, что клиент отправляет в API, обычно как «Authorization: Bearer ...». Он должен жить недолго — минуты, а не месяцы, — потому что bearer-токеном может воспользоваться любой, кто им владеет. Он может быть непрозрачным (opaque — API проверяет его у сервера авторизации через introspection) или JWT (API проверяет подпись локально). Refresh token позволяет клиенту получать новые access token без повторного входа пользователя; он долгоживущий и мощный, поэтому храните его бережно, ротируйте при каждом использовании и отзывайте при выходе. ID token из OpenID Connect — это подписанный JWT, который сообщает клиенту, кто вошёл: issuer (iss), идентификатор субъекта (sub), audience (aud), срок действия (exp), nonce и при желании email или имя. ID token предназначен для чтения клиентом; его не нужно отправлять в ваши API вместо access token.

• Access token: для API, короткоживущий, со scopes
• Refresh token: для клиента, чтобы обновлять доступ; ротируйте и отзывайте
• ID token: для клиента, доказывает, кто вошёл

04OpenID Connect: «Войти через Google / Apple»

OpenID Connect (OIDC) — тонкий слой идентификации поверх OAuth 2.0. Вы добавляете scope «openid», и сервер авторизации возвращает ID token вместе с access token. Провайдеры публикуют discovery-документ по адресу /.well-known/openid-configuration, где перечислены их эндпоинты и URL JWKS с ключами подписи. Чтобы безопасно залогинить пользователя, бэкенд должен проверить ID token: подпись текущим ключом провайдера, iss равен провайдеру, aud равен вашему client id, exp не истёк, а nonce совпадает с отправленным. Затем привязывайте аккаунт по стабильному sub провайдера, а не по email, потому что email меняются и не всегда подтверждены. На мобильных устройствах нативные SDK (Google Sign-In, Sign in with Apple) возвращают ID token или authorization code, который приложение отправляет на бэкенд для той же проверки, прежде чем вы выдадите собственную сессию или API-токены.

1use Laravel\Socialite\Facades\Socialite;
2 
3// Redirect the user to Google
4Route::get('/auth/google', fn () => Socialite::driver('google')->redirect());
5 
6// Callback: Socialite exchanges the code and fetches the profile
7Route::get('/auth/google/callback', function () {
8    $g = Socialite::driver('google')->user();
9 
10    $user = User::firstOrCreate(
11        ['google_id' => $g->getId()],          // stable provider "sub"
12        ['name' => $g->getName(), 'email' => $g->getEmail()],
13    );
14    Auth::login($user);
15    return redirect('/account');
16});

05Другие grants и API-ключи

Не у каждого клиента есть пользователь в браузере. Client credentials: бэкенд-сервис аутентифицируется сам за себя (client id и secret, а лучше подписанный assertion или mutual TLS), чтобы вызвать другой сервис, — machine-to-machine. Device authorization (RFC 8628): смарт-телевизоры и CLI показывают код, который пользователь вводит на телефоне. Token exchange (RFC 8693): сервис обменивает один токен на другой с более узким scope или другой audience. Refresh token grant: обновление доступа. Устаревшие: implicit grant (токены во фрагменте URL) и resource owner password grant (приложение само собирает пароль пользователя) — оба убраны в OAuth 2.1. Простые API-ключи по-прежнему распространены в интеграциях server-to-server; если вы их используете, делайте их со scopes, с префиксом окружения (live/test), храните в виде хэша, ограничивайте по частоте и обеспечьте ротацию без простоя.

06Laravel Passport на практике

Laravel Passport — полноценный OAuth2-сервер для Laravel API, построенный на League OAuth2 server. Актуальные версии поддерживают authorization code grant (с PKCE для публичных клиентов), client credentials, device authorization, refresh tokens и personal access tokens; password и implicit grants отключены, если не включить их явно. Scopes задаются через Passport::tokensCan, роуты защищаются guard auth:api плюс middleware для scope, а сроки жизни токенов настраиваются в service provider — по умолчанию access token живёт год, что для большинства приложений слишком долго, так что сокращайте. Для first-party SPA на том же домене сессии Laravel Sanctum на cookies часто проще OAuth; Passport хорош, когда нужны настоящие OAuth-клиенты, доступ третьих сторон или мобильные приложения на токенах.

1// AppServiceProvider::boot()
2use Carbon\CarbonInterval;
3use Laravel\Passport\Passport;
4 
5Passport::tokensCan([
6    'orders:read'   => 'View your orders',
7    'orders:create' => 'Place orders',
8]);
9Passport::tokensExpireIn(CarbonInterval::minutes(30));
10Passport::refreshTokensExpireIn(CarbonInterval::days(30));
11 
12// routes/api.php
13use Laravel\Passport\Http\Middleware\CheckToken;
14 
15Route::get('/orders', [OrderController::class, 'index'])
16    ->middleware(['auth:api', CheckToken::using('orders:read')]);

07Правильная проверка JWT (и классические атаки)

JWT — это header.payload.signature в кодировке base64url. Проверка должна быть строгой. Зафиксируйте ожидаемый алгоритм в коде (например, RS256 или ES256) и отклоняйте всё остальное — исторические уязвимости возникали из-за библиотек, доверявших alg из заголовка, что позволяло «none» или путаницу HS256 с публичным ключом. Получайте ключи подписи с JWKS-эндпоинта издателя, кэшируйте их, выбирайте по kid и обновляйте при неизвестном kid, чтобы поддерживать ротацию ключей. Проверяйте iss и aud точно, exp и nbf с небольшим допуском на рассинхрон часов, а для ID token — nonce. Не кладите чувствительные данные в payload — он подписан, но не зашифрован. Эталонный документ — RFC 8725 (JWT Best Current Practices). Предпочитайте асимметричную подпись, чтобы у resource servers были только публичные ключи, а выпускать токены мог только сервер авторизации.

1import { createRemoteJWKSet, jwtVerify } from "jose";
2 
3const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));
4 
5export async function verifyAccessToken(token: string) {
6  const { payload } = await jwtVerify(token, JWKS, {
7    issuer: "https://auth.example.com",
8    audience: "https://api.example.com",
9    algorithms: ["RS256"],      // never trust the header's alg
10    clockTolerance: 30,         // seconds
11  });
12  if (await denylist.has(payload.jti as string)) throw new Error("revoked");
13  return payload; // sub, scope, exp, ...
14}

08Ротация refresh token и обнаружение повторного использования

Refresh token — это драгоценности короны: они долгоживущие и могут выпускать access token. Ротация означает, что каждое обновление возвращает новый refresh token и делает старый недействительным. Обнаружение повторного использования добавляет ключевое свойство безопасности: если старый, уже использованный refresh token предъявлен снова, значит, у легитимного клиента или у атакующего есть украденная копия, — поэтому сервер отзывает всё семейство токенов и заставляет войти заново. Реализуйте это, храня для каждого refresh token id семейства и флаг использования. Добавьте абсолютный срок жизни (например, 30–90 дней) и таймаут простоя, чтобы брошенные сессии умирали. Обрабатывайте гонки в мобильных приложениях, где два параллельных запроса одновременно пытаются обновить токен: сериализуйте обновления на клиенте или разрешите очень короткое окно для предыдущего токена. Sender-constrained токены идут дальше: они привязывают токен к ключу клиента, так что украденный токен нельзя воспроизвести в другом месте.

09Sender-constrained токены: DPoP и mTLS

Bearer-токены работают как наличные: кто держит, тот и тратит. Sender-constrained токены работают как карта с PIN-кодом. В DPoP (RFC 9449) клиент генерирует пару ключей и с каждым запросом отправляет короткий подписанный proof JWT с HTTP-методом, URL, временной меткой и хэшем access token. Сервер авторизации привязывает токен к публичному ключу клиента (claim cnf), а API проверяет, что каждый запрос подписан тем же ключом. Токен, утёкший через логи или прокси, становится бесполезным. Mutual TLS (RFC 8705) достигает того же, привязывая токены к клиентскому сертификату, — это распространено в банковских и open-finance профилях вроде FAPI 2.0. Pushed Authorization Requests (PAR, RFC 9126) дополняют это, отправляя параметры авторизации по back channel, а не через URL в браузере, что предотвращает их подмену.

1POST /orders HTTP/1.1
2Host: api.example.com
3Authorization: DPoP eyJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ...
4DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Li4ufX0...
5 
6# DPoP proof payload (signed with the client's private key):
7# { "htm": "POST", "htu": "https://api.example.com/orders",
8#   "iat": 1793000000, "jti": "e1j3V_bKic8-LAEB", "ath": "<sha256 of access token>" }

10Идентификация в multi-tenant и B2B

В SaaS идентификация усложняется: пользователи принадлежат организациям, иногда нескольким, а корпоративные клиенты хотят свой SSO. Кладите тенанта в токен осознанно — claim tenant или org, выбранный при входе или через переключатель организаций, — и на каждом запросе проверяйте, что ресурс принадлежит этому тенанту; никогда не берите tenant id только из тела запроса. Храните роли и права в своём приложении, при необходимости маппя их из групп IdP, а не доверяйте произвольным claims от внешних IdP. Поддерживайте OIDC- или SAML-подключения для каждого тенанта для корпоративного SSO, плюс SCIM для провиженинга пользователей, если клиенты просят. Продумайте имперсонацию: сотрудники поддержки должны получать отдельный ограниченный по времени токен с claim act (actor), обязательной причиной и полным аудит-логом — и никогда не учётные данные самого клиента.