Что происходит внутри «Войти через 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.
Поток выглядит так:
- Подготовка. Бэкенд генерирует три случайных значения:
state(защита от CSRF),nonce(защита от повторного использования ID token) иcode_verifier(секрет PKCE). Всё сохраняется в сессии. - Редирект в Google. В URL —
client_id,redirect_uri,scope,state,nonceиcode_challenge = BASE64URL(SHA256(code_verifier)). Сам verifier в браузер не попадает никогда. - Пользователь входит в Google и даёт согласие. Пароль вы не видите — в этом главное преимущество OIDC.
- Google возвращает браузер на
redirect_uri?code=...&state=....code— короткоживущий одноразовый код. Это ещё не токен. - Бэкенд проверяет
stateи по серверному каналу отправляет код в token endpoint вместе сclient_secretиcode_verifier. - Google сравнивает
SHA256(code_verifier)с полученным ранееcode_challenge. Если совпало — возвращаетaccess_token,id_token,expires_in,scope. - Бэкенд проверяет 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в запросе недостаточно — проверяйте claimhdв токене на бэкенде.- Нет
state. Это открывает login CSRF: атакующий логинит жертву в свой аккаунт, и всё, что жертва введёт, окажется у атакующего. - Не совпадает
redirect_uri. Google требует точного совпадения:httpиhttps, завершающий/, порт — важно всё. За reverse proxyrequest.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 — и кнопка входа перестанет быть самым слабым местом сайта.
// комментарии
Загружаем комментарии...