Основы аутентификации и авторизации
Безопасность 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
- Header - тип токена и алгоритм
{
"alg": "HS256",
"typ": "JWT"
}
- Payload - данные
{
"sub": "1234567890",
"name": "John Doe",
"iat": 1516239022,
"exp": 1516242622
}
- 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
- Используйте короткое время жизни
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 минут
}
- Не храните sensitive данные в payload
Payload не шифруется, а только кодируется в Base64URL: его прочитает любой, у кого есть токен.
Плохо - пароль и номер карты в payload:
{
"user_id": 123,
"password": "secret123",
"credit_card": "4111111111111111"
}
Хорошо - только идентификатор и права:
{
"user_id": 123,
"role": "user",
"permissions": ["read", "write"]
}
- Используйте 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
- Resource Owner - пользователь
- Client - приложение, запрашивающее доступ
- Authorization Server - сервер, выдающий токены
- 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 это не защита.HttpOnlycookie - недостижима для 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)
ℹ️ «Самого безопасного» варианта в списке нет
Каждый пункт сильнее в одном и слабее в другом.
HttpOnlycookie закрывает кражу токена через XSS, но открывает CSRF - его придётся закрыватьSameSite, а для межсайтовых сценариев ещё и CSRF-токеном.localStorageот CSRF не страдает вовсе, зато сдаёт токен первому же выполненному на странице скрипту.Что не зависит от модели угроз: токен не место в параметрах URL (логи, история браузера, заголовок
Referer) и не константа в коде фронтенда. Остальное - осознанный компромисс; для SPA обычно берут access token в памяти плюс refresh вHttpOnlycookie (подробнее с кодом).
В мобильных приложениях
Токены кладут в защищённое хранилище платформы, а не в обычные настройки приложения:
| Платформа | Куда класть | Куда не класть |
|---|---|---|
| iOS | Keychain | UserDefaults |
| Android | ключ в Android Keystore (EncryptedSharedPreferences устарел, но встречается в существующих приложениях) | обычные SharedPreferences |
Обычные настройки лежат на устройстве открытым текстом и читаются из резервной копии или на рутованном телефоне.
Итоги
Безопасность API - это комплексная задача, требующая:
- Правильного выбора метода аутентификации
- Безопасного хранения и передачи токенов
- Защиты от распространённых атак
- Регулярного обновления и мониторинга
В следующем уроке мы изучим принципы проектирования REST API и лучшие практики создания понятных и удобных интерфейсов. Безопасность URL-параметров - в уроке web/url-security.