Files
java-word-pdf/docs/api/authentication.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

2.5 KiB
Raw Blame History

Аутентификация

Ключ доступа

Все запросы, кроме открытых путей, требуют заголовок:

X-API-Key: <ключ>

Ключ сверяется со свойством сервера wordpdf.api-key (env WORDPDF_API_KEY). Сравнение — MessageDigest.isEqual (защита от timing-атак). Пустое свойство = аутентификация выключена — так работают java -jar и dev-стенд (:9011).

Без ключа или с неверным:

HTTP 401
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}

Открытые пути

Без ключа всегда доступны (матч по префиксу со слэшем, без учёта forwarded-contextPath):

Префикс Что
/actuator/ health-checks Spring Boot
/swagger-ui Swagger UI
/v3/api-docs OpenAPI-спек

!!! warning "Точечные сегменты обходят открытие" Пути с точечными сегментами (.. или их URL-код %2e) никогда не считаются открытыми: запрос вида /actuator/../api/v1/convert потребует ключ даже на открытом префиксе. Это защита от обхода фильтра через нормализацию пути.

Где задаётся ключ

Среда Как
java -jar wordpdf.api-key= пусто — auth выключен; включить: --wordpdf.api-key=… или env WORDPDF_API_KEY
prod-like стенд (:9010) обязателен .env с WORDPDF_API_KEY (fail-closed: без него стек не поднимется), шаблон — .env.example
прод env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)

Сгенерировать ключ: openssl rand -hex 32.

Как фронтенд узнаёт про ключ

SPA при старте опрашивает сервис (probeApiKey(), GET /api/v1/convert): 401 — сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу. Введённый ключ хранится в localStorage браузера и стирается при ответе 401.