Основы аутентификации и авторизации

Безопасность API - это критически важный аспект современной разработки. В этом уроке мы разберём основные концепции и методы защиты API.

Аутентификация vs Авторизация

Аутентификация - это процесс проверки, кто вы такой. Авторизация - это процесс проверки, что вам можно делать.

Пример из жизни:

  • Когда вы показываете паспорт на входе в офис - это аутентификация
  • Когда охранник проверяет, есть ли вы в списке посетителей - это авторизация

В контексте API:

# Аутентификация: кто делает запрос?
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Авторизация: может ли этот пользователь удалять посты?
DELETE /api/posts/123

Как хранят пароли (и почему их нельзя вернуть)

Прежде чем разбирать методы, закроем вопрос, с которого начинается любая аутентификация: что лежит в базе на месте пароля.

Не пароль.

Представь мясорубку. Закинул мясо, покрутил - получил фарш. Из фарша обратно кусок мяса не собрать: операция односторонняя. Причём одинаковое мясо всегда даёт одинаковый фарш, и это как раз то, что нужно.

Так работает хеш-функция. Пароль пропускают через неё и в базу пишут результат. При входе пароль пропускают снова и сравнивают два фарша. Совпало - пустили.

Отсюда практический вывод, который стоит запомнить и вне разработки: нормальный сервис не знает пароль пользователя. Если на «забыли пароль» приходит письмо со старым паролем - сервис умеет его восстанавливать, то есть хранит либо открытым текстом, либо обратимо зашифрованным. Второе приличнее первого, но для парольной аутентификации не годится тоже: ключ расшифровки лежит в том же сервисе, и утечка базы обычно означает утечку ключа.

Хеширование, шифрование и кодирование - три разные операции, и их постоянно путают. Кодирование (base64, URL-encoding) меняет форму записи и разворачивается обратно без всяких секретов. Шифрование разворачивается обратно при наличии ключа. Хеширование не разворачивается вовсе: обратной функции не существует.

Поэтому «расшифровать хеш» - выражение бессмысленное. Украденную базу хешей не расшифровывают, а перебирают: берут кандидата, хешируют его и сравнивают результат. Ровно на удорожание этого перебора и работают приёмы ниже.

Почему обычного хеша мало

Односторонность - не единственное требование. SHA-256 тоже односторонний, но для паролей не годится: он быстрый. Он и создавался быстрым - для контрольных сумм и подписей это достоинство. Современная видеокарта считает миллиарды таких хешей в секунду, поэтому слабый пароль оказывается среди первых кандидатов перебора. Сколько именно займёт перебор конкретного пароля, зависит от его энтропии, алгоритма, параметров и железа - от миллисекунд до практически недостижимого времени.

Плюс беда с одинаковостью. Два человека выбрали qwerty123 - в базе две одинаковые строки. Взломщик подбирает один раз, а входит в два аккаунта. И готовые таблицы «хеш → пароль» для популярных паролей давно посчитаны за него.

Обе проблемы решают два приёма:

  • Соль - к каждому паролю дописывается случайная строка, своя у каждого пользователя. Одинаковые пароли дают разные хеши, готовые таблицы становятся бесполезны.
  • Рабочий фактор - функцию нарочно делают медленной и настраивают, насколько. Одна проверка при входе - десятки миллисекунд, человек не заметит. Перебор миллиарда вариантов при этом становится непозволительно дорогим.

Функции, которые так устроены: bcrypt, scrypt, argon2. Это не обычные хеш-функции, а схемы хеширования паролей (их же называют KDF - key derivation function): медленность и настраиваемая стоимость заложены в них по проекту. Соль они генерируют сами и хранят внутри итоговой строки, поэтому отдельного поля в базе под неё не нужно.

Разделение, которое стоит держать в голове при разговоре с пользователями: длина пароля защищает от перебора, а уникальность - от повторного использования украденных пар логин-пароль (credential stuffing). Это разные угрозы, и уникальный пароль не делает конкретный хеш труднее перебрать.

import (
    "errors"

    "golang.org/x/crypto/bcrypt"
)

var ErrBadCredentials = errors.New("неверный логин или пароль")

// HashPassword - регистрация: соль bcrypt сгенерирует сам и положит внутрь результата.
// hash это []byte вида $2a$10$N9qo8uLOickgx2ZMRZoMye... - в базу идёт он.
func HashPassword(password string) ([]byte, error) {
    return bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
}

// CheckPassword - вход: сравнивает за постоянное время, а соль достаёт из самого хеша.
func CheckPassword(hash []byte, password string) error {
    if err := bcrypt.CompareHashAndPassword(hash, []byte(password)); err != nil {
        return ErrBadCredentials
    }
    return nil
}

DefaultCost равен 10. Число задаёт рабочий фактор: каждая единица - удвоение времени проверки. Значение подбирают под своё железо так, чтобы одна проверка занимала десятки миллисекунд.

У bcrypt есть предел: 72 байта пароля. Одни реализации молча обрезают всё длиннее, другие возвращают ошибку. Здесь второй случай: на пароль длиннее 72 байт GenerateFromPassword вернёт bcrypt.ErrPasswordTooLong. Длину пароля в байтах проверяй до хеширования.

<?php
declare(strict_types=1);

// Регистрация: соль и алгоритм PHP выбирает сам.
$hash = password_hash($password, PASSWORD_DEFAULT);

// Вход
if (!password_verify($password, $hash)) {
    throw new RuntimeException('Неверный логин или пароль');
}

// Алгоритм по умолчанию со временем меняется. Эта проверка позволяет
// молча пересчитать хеш на новый при следующем успешном входе.
if (password_needs_rehash($hash, PASSWORD_DEFAULT)) {
    $newHash = password_hash($password, PASSWORD_DEFAULT);
    // сохранить $newHash
}

password_hash без соли не бывает - она генерируется и кладётся в строку результата. Собирать md5($password . $salt) руками не нужно и не стоит.

У bcrypt (а PASSWORD_DEFAULT сейчас это он) есть предел: 72 байта пароля. password_hash молча обрезает всё длиннее, и хвост длинной парольной фразы в проверке не участвует. Длину пароля в байтах проверяй до хеширования.

import bcrypt  # pip install bcrypt


class BadCredentialsError(Exception):
    """Неверный логин или пароль."""


def hash_password(password: str) -> bytes:
    """Регистрация: соль bcrypt сгенерирует сам и положит внутрь результата.

    Результат - bytes вида $2b$12$N9qo8uLOickgx2ZMRZoMye... - в базу идёт он.
    """
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12))


def check_password(password_hash: bytes, password: str) -> None:
    """Вход: сравнивает за постоянное время, а соль достаёт из самого хеша."""
    if not bcrypt.checkpw(password.encode(), password_hash):
        raise BadCredentialsError("неверный логин или пароль")

rounds - тот же рабочий фактор, по умолчанию 12: каждая единица удваивает время проверки. Предел в 72 байта тот же, но поведение зависит от версии: bcrypt 5.0 и новее бросает ValueError на пароль длиннее, старые версии молча обрезали. Длину пароля в байтах проверяй до хеширования. В hashlib готовой схемы хеширования паролей нет - только scrypt и pbkdf2_hmac, у которых соль и стоимость придётся задавать руками.

Что это значит для API

  • Восстановления пароля не существует, есть только сброс: одноразовая ссылка на почту, по ней задаётся новый.
  • Ответ на неверный вход не должен выдавать, что именно не подошло. «Неверный логин или пароль» вместо «такого пользователя нет» - иначе форма входа превращается в способ узнать, зарегистрирован ли адрес.
  • Проверка пароля медленная по замыслу, поэтому она же становится удобной мишенью для перебора. Ограничение частоты запросов из раздела Rate Limiting ниже здесь обязательно.

Дальше пароль в запросах не участвует: вместо него ходит токен. Как это устроено на практике - в уроках про сессии и cookie в PHP и JWT в Python, а целиком с кодом - в проекте TODO API.

Методы аутентификации

1. Basic Authentication

Самый простой метод - передача логина и пароля в каждом запросе.

# Логин:пароль кодируются в Base64
curl -H "Authorization: Basic YWxpY2U6cGFzc3dvcmQxMjM=" \
  https://api.example.com/users

Плюсы:

  • Простота реализации
  • Поддерживается везде

Минусы:

  • Небезопасно без HTTPS
  • Нужно хранить пароль на клиенте
  • Нет возможности отозвать доступ

2. API Keys

Клиент получает уникальный ключ для доступа к API.

# В заголовке
curl -H "X-API-Key: abc123def456" \
  https://api.example.com/users

# В query параметре - так делать не надо, см. ниже
curl https://api.example.com/users?api_key=abc123def456

Плюсы:

  • Простота использования
  • Можно ограничить права ключа
  • Легко отозвать

Минусы:

  • Ключ = полный доступ
  • Сложно ограничить по времени
  • Нужно безопасно хранить
  • В query-параметре ключ утекает: попадает в access-логи сервера и прокси, в историю браузера и в заголовок Referer при переходе по внешней ссылке. Передавать только заголовком - Authorization или свой X-API-Key

3. Bearer Tokens

Современный подход с использованием токенов.

# Получаем токен
curl -X POST https://api.example.com/auth/login \
 -d '{"email": "user@example.com", "password": "secret"}'

# Используем токен
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/users

Плюсы:

  • Можно задать время жизни
  • Не передаём пароль в каждом запросе
  • Поддержка refresh токенов

Минусы:

  • Нужно обновлять токены
  • Требует хранилища токенов

JWT (JSON Web Tokens)

JWT - это стандарт для создания токенов доступа.

ℹ️ Stateless - про проверку токена, а не про всю систему аутентификации

Главный аргумент за JWT звучит как «аутентификация становится stateless», и это правда ровно про один шаг: самодостаточный access-токен сервер проверяет подписью, без обращения к хранилищу сессий. Отсюда и выигрыш - проверка не ходит в базу на каждый запрос.

Дальше формулировку обычно расширяют до всей системы, и вот это уже неверно. Как только появляются вещи, которые нужны любому реальному продукту:

  • ротация refresh-токенов и обнаружение их повторного использования;
  • отзыв доступа до истечения срока;
  • список устройств и «выйти на всех»;
  • реакция на компрометацию,

серверное состояние возвращается - refresh-токены в базе, denylist, версия токена. Разница в том, где это состояние: не на горячем пути каждого запроса, а на редких операциях обновления и отзыва.

Точная формулировка: проверять самодостаточный access-токен можно без состояния; управление сессиями и отзывом состояния требует. Ниже в этом уроке - что именно происходит при /logout и чем платят за мгновенный отзыв.

Структура JWT

JWT состоит из трёх частей, разделённых точками:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  1. Header - тип токена и алгоритм
{
  "alg": "HS256",
  "typ": "JWT"
}
  1. Payload - данные
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622
}
  1. Signature - подпись для проверки

Пример работы с JWT

import (
    "errors"
    "fmt"
    "os"
    "time"

    "github.com/golang-jwt/jwt/v5"
)

// mustEnv читает секрет из окружения и роняет приложение при старте, если он пуст:
// иначе токены молча подписывались бы пустым ключом.
func mustEnv(key string) []byte {
    v := os.Getenv(key)
    if v == "" {
        panic(fmt.Sprintf("переменная окружения %s не задана", key))
    }
    return []byte(v)
}

// Секрет - из окружения, не из кода.
var secret = mustEnv("JWT_SECRET")

// IssueToken создаёт токен со сроком жизни 1 час.
func IssueToken(userID int64, email, role string) (string, error) {
    claims := jwt.MapClaims{
        "user_id": userID,
        "email":   email,
        "role":    role,
        "exp":     time.Now().Add(time.Hour).Unix(),
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString(secret)
}

// ParseToken проверяет подпись, алгоритм и exp.
// Без WithExpirationRequired токен без exp прошёл бы проверку как бессрочный.
func ParseToken(tokenStr string) (jwt.MapClaims, error) {
    token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (any, error) {
        return secret, nil
    },
        jwt.WithValidMethods([]string{"HS256"}),
        jwt.WithExpirationRequired(),
    )
    if err != nil {
        return nil, fmt.Errorf("invalid token: %w", err)
    }
    claims, ok := token.Claims.(jwt.MapClaims)
    if !ok {
        return nil, errors.New("unexpected claims type")
    }
    return claims, nil
}
<?php
declare(strict_types=1);

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// Секрет - из окружения, не из кода.
$secret = getenv('JWT_SECRET') ?: throw new RuntimeException('JWT_SECRET не задан');

// Создание токена
$payload = [
    'user_id' => 123,
    'email' => 'user@example.com',
    'role' => 'user',
    'exp' => time() + 3600, // 1 час
];
$token = JWT::encode($payload, $secret, 'HS256');

// Проверка токена: подпись и алгоритм проверяет decode, exp - только если он есть,
// поэтому наличие exp проверяем сами (иначе токен без exp был бы бессрочным).
try {
    $decoded = JWT::decode($token, new Key($secret, 'HS256'));
    if (!isset($decoded->exp)) {
        throw new UnexpectedValueException('нет exp');
    }
    echo $decoded->email;
} catch (LogicException | UnexpectedValueException $e) {
    // LogicException (и наследник DomainException) - ошибка ключа/алгоритма,
    // UnexpectedValueException (ExpiredException, SignatureInvalidException) - плохой токен
    error_log('Invalid token: ' . $e->getMessage());
}
import os
from datetime import datetime, timedelta, timezone

import jwt  # pip install PyJWT

# Секрет - из окружения, не из кода.
SECRET = os.environ["JWT_SECRET"]

# Создание токена
payload = {
    "user_id": 123,
    "email": "user@example.com",
    "role": "user",
    "exp": datetime.now(timezone.utc) + timedelta(hours=1),
}
token = jwt.encode(payload, SECRET, algorithm="HS256")

# Проверка токена: подпись и алгоритм проверяет decode, exp - только если он есть,
# поэтому require делает его обязательным (иначе токен без exp был бы бессрочным).
try:
    decoded = jwt.decode(
        token, SECRET, algorithms=["HS256"], options={"require": ["exp"]}
    )
    print(decoded["email"])
except jwt.InvalidTokenError as e:
    print(f"Invalid token: {e}")

Список допустимых алгоритмов при проверке задаётся явно (WithValidMethods, Key(..., 'HS256'), algorithms=[...]): иначе подделанный токен может сам выбрать алгоритм в заголовке.

JWT Best Practices

  1. Используйте короткое время жизни
claims := jwt.MapClaims{
    "user_id": userID,
    "exp":     time.Now().Add(15 * time.Minute).Unix(), // 15 минут
}
$payload = [
    'user_id' => $userId,
    'exp' => time() + 15 * 60, // 15 минут
];
payload = {
    "user_id": user_id,
    "exp": datetime.now(timezone.utc) + timedelta(minutes=15),  # 15 минут
}
  1. Не храните sensitive данные в payload

Payload не шифруется, а только кодируется в Base64URL: его прочитает любой, у кого есть токен.

Плохо - пароль и номер карты в payload:

{
  "user_id": 123,
  "password": "secret123",
  "credit_card": "4111111111111111"
}

Хорошо - только идентификатор и права:

{
  "user_id": 123,
  "role": "user",
  "permissions": ["read", "write"]
}
  1. Используйте refresh токены
// mustEnv - из примера выше: пустой секрет роняет приложение при старте.
var (
    accessSecret  = mustEnv("JWT_ACCESS_SECRET")
    refreshSecret = mustEnv("JWT_REFRESH_SECRET")
)

// IssuePair выдаёт пару токенов, подписанных разными секретами.
func IssuePair(userID int64, role string) (access, refresh string, err error) {
    now := time.Now()

    // Access token - короткоживущий
    access, err = jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
        "user_id": userID,
        "role":    role,
        "exp":     now.Add(15 * time.Minute).Unix(),
    }).SignedString(accessSecret)
    if err != nil {
        return "", "", fmt.Errorf("sign access token: %w", err)
    }

    // Refresh token - долгоживущий
    refresh, err = jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
        "user_id": userID,
        "exp":     now.Add(30 * 24 * time.Hour).Unix(),
    }).SignedString(refreshSecret)
    if err != nil {
        return "", "", fmt.Errorf("sign refresh token: %w", err)
    }
    return access, refresh, nil
}
<?php
declare(strict_types=1);

use Firebase\JWT\JWT;

/**
 * Выдаёт пару токенов, подписанных разными секретами.
 *
 * @return array{access: string, refresh: string}
 */
function issuePair(int $userId, string $role): array
{
    $now = time();

    // Access token - короткоживущий
    $access = JWT::encode(
        ['user_id' => $userId, 'role' => $role, 'exp' => $now + 15 * 60],
        getenv('JWT_ACCESS_SECRET') ?: throw new RuntimeException('JWT_ACCESS_SECRET не задан'),
        'HS256',
    );

    // Refresh token - долгоживущий
    $refresh = JWT::encode(
        ['user_id' => $userId, 'exp' => $now + 30 * 24 * 3600],
        getenv('JWT_REFRESH_SECRET') ?: throw new RuntimeException('JWT_REFRESH_SECRET не задан'),
        'HS256',
    );

    return ['access' => $access, 'refresh' => $refresh];
}
import os
from datetime import datetime, timedelta, timezone

import jwt  # pip install PyJWT

ACCESS_SECRET = os.environ["JWT_ACCESS_SECRET"]
REFRESH_SECRET = os.environ["JWT_REFRESH_SECRET"]


def issue_pair(user_id: int, role: str) -> tuple[str, str]:
    """Выдаёт пару токенов, подписанных разными секретами."""
    now = datetime.now(timezone.utc)

    # Access token - короткоживущий
    access = jwt.encode(
        {"user_id": user_id, "role": role, "exp": now + timedelta(minutes=15)},
        ACCESS_SECRET,
        algorithm="HS256",
    )

    # Refresh token - долгоживущий
    refresh = jwt.encode(
        {"user_id": user_id, "exp": now + timedelta(days=30)},
        REFRESH_SECRET,
        algorithm="HS256",
    )
    return access, refresh

Схема выше - минимальный каркас, и в этом виде у неё есть дыра: refresh token живёт 30 дней и не отзывается. Украли его - доступ у злоумышленника тоже на 30 дней, и «выйти со всех устройств» сделать нечем, потому что сервер о выданных токенах ничего не знает.

Поэтому refresh обычно не делают самодостаточным JWT:

  • хранят на сервере (таблица или Redis) - идентификатор сессии, устройство, дата выдачи. Тогда отзыв - это DELETE, а не ожидание истечения;
  • ротируют при каждом использовании: обмен refresh на новую пару инвалидирует старый. Повторное предъявление уже использованного refresh - сигнал кражи, и правильная реакция на него - погасить всю цепочку сессии;
  • привязывают к устройству (User-Agent, отпечаток клиента), чтобы токен, утёкший на другую машину, не подошёл.

Access token при этом остаётся stateless JWT - в этом и смысл пары: проверка на каждом запросе идёт без обращения к базе, а в базу мы ходим только при обновлении, то есть раз в 15-30 минут.

⚠️ Что на самом деле делает /logout

Самая частая ошибка в реализации выхода - считать, что endpoint /logout делает уже выданный access token недействительным. Со stateless JWT это не так и не может быть так: сервер его не хранит, а подпись остаётся валидной до exp.

Что происходит на самом деле:

POST /logout
  → refresh token отозван (удалён из базы)
  → новую пару получить нельзя
  → выданный access token продолжает работать до exp (15-30 минут)

Для большинства приложений это приемлемо - именно поэтому access делают короткоживущим. Но если требуется немедленный отзыв (сотрудника уволили, обнаружена компрометация), stateless-проверки недостаточно, и нужно серверное состояние. Варианты:

СпособКак работаетЦена
denylistсписок отозванных jti в Redis до истечения их expзапрос в Redis на каждый запрос API
версия токенав payload token_version, при отзыве версия в базе растётзапрос в базу или кеш на каждый запрос
opaque sessionвместо JWT - идентификатор сессии, состояние на серверевернулись к сессиям, зато отзыв мгновенный

Все три означают одно и то же: за мгновенный отзыв платят тем, ради чего JWT и брали, - проверкой без обращения к хранилищу. Это нормальный выбор, но делать его надо осознанно, а не обнаруживать после инцидента.

OAuth 2.0

OAuth 2.0 - это протокол авторизации, позволяющий приложениям получать ограниченный доступ к ресурсам пользователя.

Роли в OAuth 2.0

  1. Resource Owner - пользователь
  2. Client - приложение, запрашивающее доступ
  3. Authorization Server - сервер, выдающий токены
  4. Resource Server - API с защищёнными ресурсами

Authorization Code Flow

Самый безопасный flow для веб-приложений:

1. Пользователь нажимает "Войти через Google"
   → Redirect to: https://accounts.google.com/o/oauth2/v2/auth?
     client_id=abc123&
     redirect_uri=https://myapp.com/callback&
     response_type=code&
     scope=email%20profile&
     state=k3J9fQ2xLm8vT1aZ
   (state - случайная строка, приложение сохраняет её в сессии)

2. Пользователь разрешает доступ
   → Google redirects to: https://myapp.com/callback?code=xyz789&state=k3J9fQ2xLm8vT1aZ
   (приложение сверяет state с сохранённым в сессии: не совпал - запрос отклоняется)

3. Приложение обменивает код на токен
   POST https://oauth2.googleapis.com/token
   {
     "code": "xyz789",
     "client_id": "abc123",
     "client_secret": "secret456",
     "redirect_uri": "https://myapp.com/callback",
     "grant_type": "authorization_code"
   }

4. Получаем access token
   {
     "access_token": "ya29.a0AfH6SMBx...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "1//0gFu3..."
   }

Scopes (области доступа)

Scopes ограничивают, к чему токен даёт доступ:

import (
    "crypto/rand"
    "encoding/base64"
    "fmt"
    "net/url"
    "os"
)

// BuildAuthURL собирает ссылку на вход через Google и возвращает state.
// state сохраняется в сессии пользователя и сверяется на callback:
// так чужой сайт не подсунет пользователю свой code (защита от CSRF).
func BuildAuthURL() (authURL, state string, err error) {
    b := make([]byte, 16)
    if _, err := rand.Read(b); err != nil { // crypto/rand - криптостойкий
        return "", "", fmt.Errorf("generate state: %w", err)
    }
    state = base64.RawURLEncoding.EncodeToString(b)

    q := url.Values{}
    q.Set("client_id", os.Getenv("OAUTH_CLIENT_ID"))
    q.Set("redirect_uri", os.Getenv("OAUTH_REDIRECT_URI"))
    q.Set("response_type", "code")
    q.Set("scope", "email profile") // запрашиваем только email и профиль
    q.Set("state", state)
    // Токен будет иметь доступ только к email и profile API
    return "https://accounts.google.com/o/oauth2/v2/auth?" + q.Encode(), state, nil
}
// state сохраняется в сессии и сверяется на callback:
// так чужой сайт не подсунет пользователю свой code (защита от CSRF).
$state = bin2hex(random_bytes(16)); // random_bytes - криптостойкий
$_SESSION['oauth_state'] = $state;

$authUrl = 'https://accounts.google.com/o/oauth2/v2/auth?' . http_build_query([
    'client_id' => getenv('OAUTH_CLIENT_ID'),
    'redirect_uri' => getenv('OAUTH_REDIRECT_URI'),
    'response_type' => 'code',
    'scope' => 'email profile', // запрашиваем только email и профиль
    'state' => $state,
]);

// Токен будет иметь доступ только к email и profile API
import os
import secrets
from urllib.parse import urlencode

# state сохраняется в сессии и сверяется на callback:
# так чужой сайт не подсунет пользователю свой code (защита от CSRF).
state = secrets.token_urlsafe(16)  # secrets - криптостойкий
# session["oauth_state"] = state  - сессия зависит от фреймворка

auth_url = "https://accounts.google.com/o/oauth2/v2/auth?" + urlencode({
    "client_id": os.environ["OAUTH_CLIENT_ID"],
    "redirect_uri": os.environ["OAUTH_REDIRECT_URI"],
    "response_type": "code",
    "scope": "email profile",  # запрашиваем только email и профиль
    "state": state,
})

# Токен будет иметь доступ только к email и profile API

Безопасность API

1. Всегда используйте HTTPS

# HTTP-сервер только перенаправляет на HTTPS
server {
    listen 80;
    server_name YOUR_DOMAIN;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name YOUR_DOMAIN;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}

2. Rate Limiting

Ограничение: не больше 100 запросов с одного IP за 15 минут на всё под /api/. Ниже - простейший вариант «фиксированное окно».

import (
    "net"
    "net/http"
    "sync"
    "time"
)

// RateLimiter - фиксированное окно: не больше limit запросов с ключа за window.
// Счётчики в памяти процесса - только для примера: в проде - Redis/TTL,
// иначе память растёт и лимит не общий для нескольких инстансов.
type RateLimiter struct {
    mu     sync.Mutex
    limit  int
    window time.Duration
    hits   map[string]*counter
}

type counter struct {
    count   int
    resetAt time.Time
}

func NewRateLimiter(limit int, window time.Duration) *RateLimiter {
    return &RateLimiter{limit: limit, window: window, hits: make(map[string]*counter)}
}

func (rl *RateLimiter) allow(key string) bool {
    rl.mu.Lock()
    defer rl.mu.Unlock()

    now := time.Now()
    c, ok := rl.hits[key]
    if !ok || now.After(c.resetAt) {
        rl.hits[key] = &counter{count: 1, resetAt: now.Add(rl.window)}
        return true
    }
    c.count++
    return c.count <= rl.limit
}

func (rl *RateLimiter) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ip, _, err := net.SplitHostPort(r.RemoteAddr)
        if err != nil {
            ip = r.RemoteAddr
        }
        if !rl.allow(ip) {
            http.Error(w, "Too many requests", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

// Подключение: 100 запросов за 15 минут
// limiter := NewRateLimiter(100, 15*time.Minute)
// mux.Handle("/api/", limiter.Middleware(apiHandler))
<?php
declare(strict_types=1);

// PHP не держит память между запросами, поэтому счётчик живёт в Redis.
function allowRequest(Redis $redis, string $ip, int $limit = 100, int $window = 900): bool
{
    $key = 'rate:' . $ip;
    // Сначала атомарно создаём ключ с TTL (NX - только если его нет), потом INCR.
    // Пара INCR + EXPIRE не атомарна: упади процесс между ними - ключ останется
    // без TTL, и IP будет заблокирован навсегда.
    // Окно 15 минут отсчитывается от первого запроса.
    $redis->set($key, 0, ['nx', 'ex' => $window]);
    $count = $redis->incr($key);

    return $count <= $limit;
}

// В начале обработки запросов к /api/
if (!allowRequest($redis, $_SERVER['REMOTE_ADDR'])) {
    http_response_code(429);
    header('Content-Type: application/json');
    echo json_encode(['error' => 'Too many requests']);
    exit;
}
import time
from dataclasses import dataclass, field


@dataclass
class RateLimiter:
    """Фиксированное окно: не больше limit запросов с ключа за window секунд.

    Счётчики в памяти процесса - только для примера: в проде - Redis/TTL,
    иначе память растёт и лимит не общий для нескольких инстансов.
    """

    limit: int = 100
    window: float = 15 * 60
    _hits: dict[str, tuple[int, float]] = field(default_factory=dict)

    def allow(self, key: str) -> bool:
        now = time.monotonic()
        count, reset_at = self._hits.get(key, (0, now + self.window))
        if now >= reset_at:
            count, reset_at = 0, now + self.window
        count += 1
        self._hits[key] = (count, reset_at)
        return count <= self.limit


limiter = RateLimiter()
# В обработчике /api/: если limiter.allow(client_ip) вернул False - ответ 429.
# В FastAPI это middleware или зависимость (Depends) на роутере /api.

3. CORS (Cross-Origin Resource Sharing)

const trustedOrigin = "https://trusted-domain.com"

func CORS(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        h := w.Header()
        h.Add("Vary", "Origin")
        // Только доверенный origin: "*" вместе с credentials браузер не примет
        if r.Header.Get("Origin") == trustedOrigin {
            h.Set("Access-Control-Allow-Origin", trustedOrigin)
            h.Set("Access-Control-Allow-Credentials", "true")
            h.Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
            h.Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
        }
        // Preflight-запрос браузера: заголовки без тела
        if r.Method == http.MethodOptions {
            w.WriteHeader(http.StatusNoContent)
            return
        }
        next.ServeHTTP(w, r)
    })
}
<?php
declare(strict_types=1);

const TRUSTED_ORIGIN = 'https://trusted-domain.com';

header('Vary: Origin');
// Только доверенный origin: "*" вместе с credentials браузер не примет
if (($_SERVER['HTTP_ORIGIN'] ?? '') === TRUSTED_ORIGIN) {
    header('Access-Control-Allow-Origin: ' . TRUSTED_ORIGIN);
    header('Access-Control-Allow-Credentials: true');
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');
    header('Access-Control-Allow-Headers: Content-Type, Authorization');
}
// Preflight-запрос браузера: заголовки без тела
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}
TRUSTED_ORIGIN = "https://trusted-domain.com"


def cors_headers(origin: str | None) -> dict[str, str]:
    """Заголовки CORS для ответа; на preflight (OPTIONS) их отдают с кодом 204 без тела.

    Только доверенный origin: "*" вместе с credentials браузер не примет.
    """
    headers = {"Vary": "Origin"}
    if origin == TRUSTED_ORIGIN:
        headers.update({
            "Access-Control-Allow-Origin": TRUSTED_ORIGIN,
            "Access-Control-Allow-Credentials": "true",
            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
            "Access-Control-Allow-Headers": "Content-Type, Authorization",
        })
    return headers


# В FastAPI это CORSMiddleware(allow_origins=[TRUSTED_ORIGIN], allow_credentials=True, ...).

4. Валидация входных данных

import (
    "encoding/json"
    "net/http"
    "net/mail"
    "unicode/utf8"
)

type CreateUserRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

// Validate возвращает список ошибок; пустой список - данные валидны.
func (r CreateUserRequest) Validate() []string {
    var errs []string
    if addr, err := mail.ParseAddress(r.Email); err != nil || addr.Address != r.Email {
        errs = append(errs, "email: некорректный адрес")
    }
    if utf8.RuneCountInString(r.Password) < 8 {
        errs = append(errs, "password: минимум 8 символов")
    }
    return errs
}

// POST /api/users
func createUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "invalid JSON", http.StatusBadRequest) // 400: тело не разобрать
        return
    }
    if errs := req.Validate(); len(errs) > 0 {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusUnprocessableEntity) // 422: JSON прочитан, данные не прошли проверку
        _ = json.NewEncoder(w).Encode(map[string][]string{"errors": errs})
        return
    }
    // Обработка валидных данных
}
<?php
declare(strict_types=1);

/** @return list<string> пустой список - данные валидны */
function validateCreateUser(array $data): array
{
    $errors = [];
    if (filter_var($data['email'] ?? '', FILTER_VALIDATE_EMAIL) === false) {
        $errors[] = 'email: некорректный адрес';
    }
    if (mb_strlen((string) ($data['password'] ?? '')) < 8) {
        $errors[] = 'password: минимум 8 символов';
    }

    return $errors;
}

// POST /api/users
$decoded = json_decode(file_get_contents('php://input'), true);
if (!is_array($decoded)) {
    http_response_code(400); // тело не разобрать как JSON-объект
    header('Content-Type: application/json');
    echo json_encode(['errors' => ['invalid JSON']]);
    exit;
}
$errors = validateCreateUser($decoded);
if ($errors !== []) {
    http_response_code(422); // JSON прочитан, данные не прошли проверку
    header('Content-Type: application/json');
    echo json_encode(['errors' => $errors]);
    exit;
}
// Обработка валидных данных
import re
from dataclasses import dataclass

EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+
quot;) @dataclass(frozen=True) class CreateUserRequest: email: str password: str def validate(self) -> list[str]: """Возвращает список ошибок; пустой список - данные валидны.""" errors: list[str] = [] if not EMAIL_RE.match(self.email): errors.append("email: некорректный адрес") if len(self.password) < 8: errors.append("password: минимум 8 символов") return errors # В обработчике POST /api/users: тело не разобрать как JSON - ответ 400, # если errors не пуст - ответ 422 {"errors": errors}. # В FastAPI это Pydantic-модель с EmailStr и Field(min_length=8): # невалидный запрос отклоняется с кодом 422 ещё до вызова обработчика.

Коды разделены: 400 - тело не удалось разобрать как JSON, 422 - JSON прочитан, но данные не прошли проверку (подробнее о кодах ошибок).

Проверки email во вкладках не равнозначны: mail.ParseAddress пропускает адрес без точки в домене (a@b), а FILTER_VALIDATE_EMAIL и регулярное выражение его отклонят. Синтаксис - только первый фильтр: реально ли адрес существует, показывает лишь письмо с подтверждением.

5. Безопасные заголовки

func SecurityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        h := w.Header()
        h.Set("X-Content-Type-Options", "nosniff")
        h.Set("X-Frame-Options", "DENY")
        h.Set("Content-Security-Policy", "default-src 'self'")
        // X-XSS-Protection устарел: браузеры убрали XSS-фильтр, защищает CSP
        next.ServeHTTP(w, r)
    })
}
// В начале каждого ответа (или в middleware фреймворка)
header('X-Content-Type-Options: nosniff');
header('X-Frame-Options: DENY');
header('Content-Security-Policy: default-src \'self\'');
// X-XSS-Protection устарел: браузеры убрали XSS-фильтр, защищает CSP
SECURITY_HEADERS: dict[str, str] = {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Content-Security-Policy": "default-src 'self'",
}
# X-XSS-Protection устарел: браузеры убрали XSS-фильтр, защищает CSP

# Добавляются к каждому ответу. В FastAPI это middleware:
# @app.middleware("http") -> response.headers.update(SECURITY_HEADERS)

Хранение токенов на клиенте

В браузере - storage в JS

  • localStorage (localStorage.setItem('token', accessToken)) - переживает перезагрузку, читается любым скриптом на странице.
  • sessionStorage - тот же доступ из JS, разница только во времени жизни: чистится при закрытии вкладки. Против XSS это не защита.
  • HttpOnly cookie - недостижима для JS, её ставит сервер:
http.SetCookie(w, &http.Cookie{
    Name:     "token",
    Value:    accessToken,
    Path:     "/",
    HttpOnly: true,                    // JS не читает - XSS не выносит токен напрямую
    Secure:   true,                    // только по HTTPS
    SameSite: http.SameSiteStrictMode, // не уходит с межсайтовых запросов - защита от CSRF
    MaxAge:   3600,                    // 1 час
})
setcookie('token', $accessToken, [
    'expires' => time() + 3600, // 1 час
    'path' => '/',
    'httponly' => true,  // JS не читает - XSS не выносит токен напрямую
    'secure' => true,    // только по HTTPS
    'samesite' => 'Strict', // не уходит с межсайтовых запросов - защита от CSRF
]);
from http.cookies import SimpleCookie

cookie = SimpleCookie()
cookie["token"] = access_token
cookie["token"]["path"] = "/"
cookie["token"]["httponly"] = True  # JS не читает - XSS не выносит токен напрямую
cookie["token"]["secure"] = True  # только по HTTPS
cookie["token"]["samesite"] = "Strict"  # не уходит с межсайтовых запросов - защита от CSRF
cookie["token"]["max-age"] = 3600  # 1 час
set_cookie_header = cookie["token"].OutputString()  # значение заголовка Set-Cookie

# В FastAPI это response.set_cookie("token", access_token, httponly=True,
#     secure=True, samesite="strict", max_age=3600)

ℹ️ «Самого безопасного» варианта в списке нет

Каждый пункт сильнее в одном и слабее в другом. HttpOnly cookie закрывает кражу токена через XSS, но открывает CSRF - его придётся закрывать SameSite, а для межсайтовых сценариев ещё и CSRF-токеном. localStorage от CSRF не страдает вовсе, зато сдаёт токен первому же выполненному на странице скрипту.

Что не зависит от модели угроз: токен не место в параметрах URL (логи, история браузера, заголовок Referer) и не константа в коде фронтенда. Остальное - осознанный компромисс; для SPA обычно берут access token в памяти плюс refresh в HttpOnly cookie (подробнее с кодом).

В мобильных приложениях

Токены кладут в защищённое хранилище платформы, а не в обычные настройки приложения:

ПлатформаКуда кластьКуда не класть
iOSKeychainUserDefaults
Androidключ в Android Keystore (EncryptedSharedPreferences устарел, но встречается в существующих приложениях)обычные SharedPreferences

Обычные настройки лежат на устройстве открытым текстом и читаются из резервной копии или на рутованном телефоне.

Итоги

Безопасность API - это комплексная задача, требующая:

  • Правильного выбора метода аутентификации
  • Безопасного хранения и передачи токенов
  • Защиты от распространённых атак
  • Регулярного обновления и мониторинга

В следующем уроке мы изучим принципы проектирования REST API и лучшие практики создания понятных и удобных интерфейсов. Безопасность URL-параметров - в уроке web/url-security.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.