Все заметки
Программирование

Что происходит внутри «Войти через Google»: OAuth 2.0, OpenID Connect и PKCE

Email или токен, пришедший на бэкенд, — ещё не доказательство. Поток Authorization Code + PKCE, разница между access token и ID token и правильная проверка ID token в Django: подпись, aud, iss, exp.

Вы добавили на сайт кнопку «Войти через Google». Фронтендер нашёл быстрое решение: по клику браузер получает данные пользователя от Google и отправляет на бэкенд {"email": "ali@gmail.com"}. Бэкенд находит пользователя по email и открывает сессию. Всё работает, демо выглядит отлично.

А потом кто-то открывает DevTools и повторяет этот запрос с чужим email. Бэкенд радушно пускает и его. Ни пароля, ни Google, ни одной проверки.

Есть и «более аккуратный» вариант: фронтенд получает от Google токен, отправляет его на бэкенд, а тот декодирует его из base64 и читает email. Это почти та же дыра. В статье разберём, какой протокол на самом деле стоит за «Войти через Google», какой токен для чего нужен и как шаг за шагом правильно проверить ID token на Django-бэкенде.

Почему наивный подход ломается

Главная ошибка: бэкенд доверяет утверждению клиента. Браузер — среда вне вашего контроля. Любой JSON, заголовок или токен оттуда означает лишь «кто-то так говорит». Бэкенду нужно доказательство: эти данные действительно выдал Google, выдал именно для вашего приложения, и они ещё не истекли.

Есть и более тонкий случай: бэкенд принимает токен и идёт с ним в API Google (например, userinfo), чтобы узнать, кто это. Токен настоящий, Google отвечает — в чём проблема? В том, что токен мог быть выдан другому приложению. Представьте: кто-то делает приложение «Бесплатный тест», через Google в него входят тысячи людей, а автор собирает их токены. Если ваш бэкенд рассуждает «Google принял — значит, всё хорошо», с этими токенами можно войти и на ваш сайт от имени тех же людей. Это называется token substitution, и защищает от него ровно одно: проверка того, кому выдан токен (aud).

OAuth 2.0 и OpenID Connect: кто за что отвечает

Сначала разведём термины — путаница начинается именно здесь.

OAuth 2.0 — протокол авторизации, то есть выдачи разрешений. Он отвечает на вопрос «может ли это приложение читать мои файлы в Google Drive от моего имени». На выходе приложение получает access token. На вопрос «кто этот пользователь?» сам OAuth 2.0 не отвечает.

OpenID Connect (OIDC) — слой аутентификации поверх OAuth 2.0. Если запрошен scope openid, провайдер дополнительно возвращает ID token: подписанный JWT с утверждением «это такой-то пользователь, я подтвердил его в такое-то время для такого-то приложения».

ID token Access token
Для кого Ваше приложение (client) Resource server (API)
Формат Всегда JWT (требование OIDC) Определяет провайдер; у Google непрозрачный (opaque)
aud Ваш client_id API
Зачем Узнать пользователя Вызывать API в пределах scope
Отправлять в API Нет Да, Authorization: Bearer

ID token говорит вашему приложению «кто пришёл». Access token говорит API «что этому приложению разрешено». Подмена одного другим — корень большинства ошибок.

Все адреса Google опубликованы в discovery-документе, запоминать их не нужно:

# Discovery document: endpoints, supported algorithms, claims
curl -s https://accounts.google.com/.well-known/openid-configuration \
  | python3 -m json.tool | grep -E '"(issuer|authorization_endpoint|token_endpoint|jwks_uri)"'

Authorization Code + PKCE: шаг за шагом

Для веб-приложения с серверной частью правильный поток — Authorization Code с PKCE. Старый Implicit flow (токен возвращается прямо во фрагменте URL) не рекомендуется в RFC 9700 — Best Current Practice по безопасности OAuth 2.0.

Поток выглядит так:

  1. Подготовка. Бэкенд генерирует три случайных значения: state (защита от CSRF), nonce (защита от повторного использования ID token) и code_verifier (секрет PKCE). Всё сохраняется в сессии.
  2. Редирект в Google. В URL — client_id, redirect_uri, scope, state, nonce и code_challenge = BASE64URL(SHA256(code_verifier)). Сам verifier в браузер не попадает никогда.
  3. Пользователь входит в Google и даёт согласие. Пароль вы не видите — в этом главное преимущество OIDC.
  4. Google возвращает браузер на redirect_uri?code=...&state=.... code — короткоживущий одноразовый код. Это ещё не токен.
  5. Бэкенд проверяет state и по серверному каналу отправляет код в token endpoint вместе с client_secret и code_verifier.
  6. Google сравнивает SHA256(code_verifier) с полученным ранее code_challenge. Если совпало — возвращает access_token, id_token, expires_in, scope.
  7. Бэкенд проверяет ID token, находит или создаёт пользователя по sub и открывает свою Django-сессию.

Зачем PKCE, если есть client_secret? Код проходит через браузер: он может осесть в логах сервера, прокси, истории браузера, а на мобильном устройстве — оказаться у другого приложения. С PKCE перехваченный код без verifier бесполезен. Поэтому RFC 9700 рекомендует PKCE и для confidential-клиентов.

Код: логин и callback в Django

Первая view: генерируем пару PKCE и отправляем пользователя в Google.

# accounts/views.py
import base64
import hashlib
import secrets
from urllib.parse import urlencode

from django.conf import settings
from django.shortcuts import redirect

GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"


def _pkce_pair() -> tuple[str, str]:
    # 64 random bytes -> 86 URL-safe chars (RFC 7636 allows 43..128)
    verifier = secrets.token_urlsafe(64)
    digest = hashlib.sha256(verifier.encode("ascii")).digest()
    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
    return verifier, challenge


def google_login(request):
    verifier, challenge = _pkce_pair()
    state = secrets.token_urlsafe(32)
    nonce = secrets.token_urlsafe(32)
    request.session["oauth_google"] = {
        "state": state,
        "nonce": nonce,
        "verifier": verifier,
    }
    params = {
        "client_id": settings.GOOGLE_CLIENT_ID,
        "redirect_uri": settings.GOOGLE_REDIRECT_URI,  # exact match with Console
        "response_type": "code",
        "scope": "openid email profile",
        "state": state,
        "nonce": nonce,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
    }
    return redirect(f"{GOOGLE_AUTH_URL}?{urlencode(params)}")

Callback: проверяем state, обмениваем код, проверяем ID token. Важно делать pop из сессии — раз код одноразовый, наше состояние тоже должно быть одноразовым.

# accounts/views.py (continued)
import requests
from django.contrib.auth import login
from django.http import HttpResponseBadRequest

from .google import InvalidIdToken, verify_google_id_token
from .services import AccountLinkRequired, get_or_create_user_from_google

GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"


def google_callback(request):
    saved = request.session.pop("oauth_google", None)
    if saved is None:
        return HttpResponseBadRequest("No login in progress")
    if "error" in request.GET:  # e.g. access_denied
        return HttpResponseBadRequest("Login cancelled")

    state = request.GET.get("state", "")
    if not secrets.compare_digest(state.encode(), saved["state"].encode()):
        return HttpResponseBadRequest("Invalid state")

    resp = requests.post(
        GOOGLE_TOKEN_URL,
        data={
            "grant_type": "authorization_code",
            "code": request.GET.get("code", ""),
            "redirect_uri": settings.GOOGLE_REDIRECT_URI,
            "client_id": settings.GOOGLE_CLIENT_ID,
            "client_secret": settings.GOOGLE_CLIENT_SECRET,
            "code_verifier": saved["verifier"],
        },
        timeout=10,
    )
    if resp.status_code != 200:
        return HttpResponseBadRequest("Token exchange failed")
    tokens = resp.json()

    try:
        claims = verify_google_id_token(tokens["id_token"], nonce=saved["nonce"])
        user = get_or_create_user_from_google(claims)
    except (KeyError, InvalidIdToken):
        return HttpResponseBadRequest("Invalid ID token")
    except AccountLinkRequired:
        return redirect("/login/?link=google")

    login(request, user, backend="django.contrib.auth.backends.ModelBackend")
    return redirect("/")

Обратите внимание: на этом работа с токенами Google заканчивается. Если вам нужен только вход, access_token хранить незачем — вы открываете собственную сессию, и задача решена.

Проверка ID token на сервере

Это самая важная часть статьи. ID token — JWT вида header.payload.signature. Чтобы прочитать payload, ключ не нужен: это обычный base64url. Поэтому «раскодировать и прочитать email» — не проверка. Настоящая проверка состоит из четырёх частей:

  • Подпись. Google подписывает токен своим закрытым ключом по RS256. Открытые ключи публикуются как набор JWK по адресу jwks_uri, нужный выбирается по kid из заголовка. Алгоритм берите из своего кода, а не из заголовка токена.
  • aud обязан совпадать с вашим client_id. Именно это защищает от атаки с «бесплатным тестом».
  • iss — для Google это https://accounts.google.com или accounts.google.com.
  • exp — токен не должен быть просрочен. Часы серверов немного расходятся, поэтому leeway в несколько секунд — обычная практика.

Кроме того, если вы отправляли nonce в запросе, nonce в токене должен совпасть с сохранённым в сессии.

С PyJWT:

# accounts/google.py
import jwt
from django.conf import settings

GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs"
GOOGLE_ISSUERS = {"https://accounts.google.com", "accounts.google.com"}

# Module-level: the JWK set is cached between requests in this process
_jwks = jwt.PyJWKClient(GOOGLE_JWKS_URL, lifespan=3600, timeout=5)


class InvalidIdToken(Exception):
    pass


def verify_google_id_token(token: str, nonce: str | None) -> dict:
    try:
        key = _jwks.get_signing_key_from_jwt(token)  # picks key by "kid"
        claims = jwt.decode(
            token,
            key.key,
            algorithms=["RS256"],             # never trust "alg" from the header
            audience=settings.GOOGLE_CLIENT_ID,
            options={"require": ["iss", "aud", "exp", "iat", "sub"]},
            leeway=30,                        # small clock skew tolerance
        )
    except jwt.PyJWTError as exc:
        raise InvalidIdToken(str(exc)) from exc

    if claims["iss"] not in GOOGLE_ISSUERS:
        raise InvalidIdToken("unexpected issuer")
    if nonce is None or claims.get("nonce") != nonce:
        raise InvalidIdToken("nonce mismatch")
    return claims

PyJWKClient кэширует набор JWK и перезагружает его, если в токене встретился незнакомый kid. Google периодически меняет ключи (key rotation), так что захардкоженный открытый ключ — это логин, который однажды внезапно сломается.

Если в проекте уже есть библиотека google-auth, та же проверка делается одним вызовом:

from google.auth.transport import requests as google_requests
from google.oauth2 import id_token

# Checks signature, exp, aud and iss; raises ValueError on failure.
# The nonce still has to be compared by you.
claims = id_token.verify_oauth2_token(
    token, google_requests.Request(), settings.GOOGLE_CLIENT_ID
)

Как привязать пользователя: sub, а не email

В ID token есть email, email_verified, name, picture и самое главное — sub. sub — неизменный и уникальный идентификатор аккаунта Google. Email же может измениться. Поэтому привязывайте по паре (provider, sub):

# accounts/models.py
from django.conf import settings
from django.db import models


class SocialAccount(models.Model):
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="social_accounts",
    )
    provider = models.CharField(max_length=32)
    subject = models.CharField(max_length=255)  # the "sub" claim
    email = models.EmailField(blank=True)        # informational only
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=["provider", "subject"],
                name="uniq_social_provider_subject",
            ),
        ]
# accounts/services.py
from django.contrib.auth import get_user_model
from django.db import IntegrityError, transaction

from .google import InvalidIdToken
from .models import SocialAccount


class AccountLinkRequired(Exception):
    pass


def get_or_create_user_from_google(claims: dict):
    sub = claims["sub"]
    account = (
        SocialAccount.objects.select_related("user")
        .filter(provider="google", subject=sub)
        .first()
    )
    if account is not None:
        return account.user

    if claims.get("email_verified") is not True:
        raise InvalidIdToken("email is not verified")

    User = get_user_model()
    email = claims["email"].lower()
    if User.objects.filter(email__iexact=email).exists():
        # Someone already registered with this email (e.g. with a password).
        # Make them log in first and link Google from settings.
        raise AccountLinkRequired(email)

    try:
        with transaction.atomic():
            user = User.objects.create_user(username=f"google_{sub}", email=email)
            SocialAccount.objects.create(
                user=user, provider="google", subject=sub, email=email
            )
    except IntegrityError:
        # A parallel callback for the same Google account won the race
        return SocialAccount.objects.get(provider="google", subject=sub).user
    return user

Здесь два решения. Первое: если email_verified не равен true, email мы не доверяем. Второе: если пользователь с таким email уже существует, аккаунты автоматически не связываем. Автопривязка удобна, но в тот день, когда вы добавите провайдера со слабой проверкой email, она превратится в account takeover. Безопасный путь — пусть пользователь сначала войдёт своим способом, а потом подключит Google в настройках. Блок с IntegrityError нужен для случая, когда callback открыли дважды одновременно: UniqueConstraint не даст создать дубликат.

Google Identity Services: поток в браузере

Актуальная JavaScript-библиотека Google — Google Identity Services (GIS). Её кнопка «Sign in with Google» и окно One Tap работают без редиректа: пользователь выбирает аккаунт, и в ваш callback приходит response.credential. Этот credential — тот самый ID token. Не access token и не код.

<!-- templates/accounts/login.html -->
<script src="https://accounts.google.com/gsi/client" async></script>
<div id="google-btn"></div>
<script>
  window.onload = () => {
    google.accounts.id.initialize({
      client_id: "{{ google_client_id }}",
      nonce: "{{ gis_nonce }}",
      callback: async (response) => {
        const r = await fetch("/auth/google/gis/", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "X-CSRFToken": "{{ csrf_token }}",
          },
          body: JSON.stringify({ credential: response.credential }),
        });
        if (r.ok) window.location.href = "/";
      },
    });
    google.accounts.id.renderButton(
      document.getElementById("google-btn"),
      { theme: "outline", size: "large" },
    );
  };
</script>

На бэкенде проверка ровно та же — подпись, aud, iss, exp, nonce. При открытии страницы кладём nonce в сессию и передаём его в GIS:

# accounts/views.py (continued)
import json

from django.http import JsonResponse
from django.shortcuts import render
from django.views.decorators.http import require_POST


def login_page(request):
    request.session["gis_nonce"] = secrets.token_urlsafe(32)
    return render(request, "accounts/login.html", {
        "google_client_id": settings.GOOGLE_CLIENT_ID,
        "gis_nonce": request.session["gis_nonce"],
    })


@require_POST
def google_gis(request):
    nonce = request.session.pop("gis_nonce", None)
    try:
        credential = json.loads(request.body)["credential"]
        claims = verify_google_id_token(credential, nonce=nonce)
        user = get_or_create_user_from_google(claims)
    except (ValueError, KeyError, TypeError, InvalidIdToken):
        return JsonResponse({"error": "invalid_credential"}, status=400)
    except AccountLinkRequired:
        return JsonResponse({"error": "link_required"}, status=409)

    login(request, user, backend="django.contrib.auth.backends.ModelBackend")
    return JsonResponse({"ok": True})

CSRF-защита Django остаётся на месте: запрос fetch отправляет заголовок X-CSRFToken. GIS-поток — для аутентификации. Если нужно вызывать API Google от имени пользователя, в GIS это делается отдельной, авторизационной частью (google.accounts.oauth2), и она снова приводит к потоку Authorization Code.

Scopes: просите меньше

Для входа достаточно openid email profile. Лишние scopes делают экран согласия пугающим и снижают конверсию. Если позже понадобится, например, доступ к календарю, запросите его в момент использования функции (incremental authorization; у Google — include_granted_scopes=true). Refresh token выдаётся только при access_type=offline — для входа он не нужен.

Ещё нюанс: на экране согласия пользователь может снять часть разрешений. Поле scope в ответе token endpoint показывает реально выданные права — проверяйте, что нужный scope там есть.

Ошибки, которые встречаются в продакшене

  • Не проверяется aud. Токен, выданный другому приложению, работает и у вас. Самая опасная и самая частая ошибка.
  • «Декодирование» без подписи. jwt.decode(token, options={"verify_signature": False}) удобно для отладки, но в продакшене принимает любой поддельный токен.
  • Не указан algorithms. Алгоритм всегда жёстко задаётся кодом, а не заголовком токена.
  • Email как первичный ключ. Email меняется, sub — нет.
  • Игнорируется email_verified. Неподтверждённый email — просто строка.
  • hd только в URL. Если пускать нужно только пользователей корпоративного домена Workspace, параметра hd в запросе недостаточно — проверяйте claim hd в токене на бэкенде.
  • Нет state. Это открывает login CSRF: атакующий логинит жертву в свой аккаунт, и всё, что жертва введёт, окажется у атакующего.
  • Не совпадает redirect_uri. Google требует точного совпадения: http и https, завершающий /, порт — важно всё. За reverse proxy request.build_absolute_uri() может вернуть http://, поэтому берите адрес из настроек.
  • SESSION_COOKIE_SAMESITE = "Strict". Возврат из Google — кросс-сайтовая навигация, а Strict-cookie при ней не отправляется: сессия теряется, и каждый раз выходит «Invalid state». Стандартное для Django значение Lax с этим потоком работает.
  • Повторное открытие callback. Код одноразовый; при обновлении страницы Google вернёт invalid_grant. pop из сессии превращает это в аккуратную ошибку.
  • Токены в логах. Не пишите code, id_token, access_token в логи и не передавайте их в URL.

Практический чеклист

  • Authorization Code + PKCE (S256), а не Implicit flow.
  • Для каждого входа — новые state, nonce, code_verifier; хранятся в сессии и используются один раз.
  • ID token: подпись (JWKS, kid), algorithms=["RS256"], aud, iss, exp, nonce.
  • Пользователь привязан по (provider, sub); есть UniqueConstraint.
  • Проверяется email_verified; автопривязки к существующему аккаунту нет.
  • redirect_uri берётся из настроек и в точности совпадает с указанным в Console.
  • Минимальные scopes; дополнительные права — по мере необходимости.
  • После входа — своя сессия; ненужные токены Google не хранятся.
  • Токены не попадают в логи и URL.

Итог

«Войти через Google» — это два протокола: OAuth 2.0 даёт механизм обмена кода на токены, а OpenID Connect добавляет к нему подписанный ID token. Бэкенд никогда не должен верить клиенту на слово: токен без проверки подписи, aud, iss, exp и nonce — просто строка в base64. Привязывайте пользователя по sub, не пропускайте PKCE и state — и кнопка входа перестанет быть самым слабым местом сайта.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯