b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# Аутентификация
|
||
|
||
## Ключ доступа
|
||
|
||
Все запросы, кроме открытых путей, требуют заголовок:
|
||
|
||
```
|
||
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.
|