Fix: Swagger UI/OpenAPI под префиксом /pdf-converter, документация открыта без ключа
Прод (наружный nginx срезает /pdf-converter/): springdoc генерировал абсолютные URL от корня хоста — пути до /v3/api-docs и swagger-ui битые. server.forward-headers-strategy=framework + X-Forwarded-* (добавляет наружный nginx) дают server https://pjandro.ru/pdf-converter и configUrl с префиксом; 'native'-клапан Tomcat X-Forwarded-Prefix не понимает. ApiKeyFilter: матч по пути без forwarded-contextPath (под префиксным заголовком getRequestURI() включает префикс — HEALTHCHECK получил бы 401) + открытые без ключа /swagger-ui* и /v3/api-docs* (браузер не может положить ключ в заголовок при загрузке UI; /api/** под ключом). OpenApiConfig: @SecurityScheme X-API-Key — кнопка Authorize в UI, @SecurityRequirement на convert — «Try it out» с ключом. springdoc.swagger-ui.persist-authorization=true. Регрессии: ApiKeyFilterTest#docsOpenWithoutKey, #forwardedPrefix_healthStaysOpen, #forwardedPrefix_docsOpenWithoutKey (вместо удалённого openApiRequiresKey). AGENTS.md синхронизирован.
This commit is contained in:
@@ -15,17 +15,24 @@ import java.security.MessageDigest;
|
||||
/**
|
||||
* Единственная граница доступа: заголовок {@value #HEADER} обязан совпадать с
|
||||
* {@code wordpdf.api-key}. Пустое свойство = фильтрация выключена (dev/тесты).
|
||||
* {@code /actuator/**} открыт — им дышит Docker HEALTHCHECK. Ответ 401 пишется
|
||||
* здесь же, {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела —
|
||||
* Наружу без ключа открыты {@code /actuator/**} (им дышит Docker HEALTHCHECK)
|
||||
* и документация springdoc ({@code /swagger-ui*}, {@code /v3/api-docs*}) —
|
||||
* браузер не может положить ключ в заголовок при загрузке UI; ключ обязателен
|
||||
* для всего остального (фактически {@code /api/**}). Ответ 401 пишется здесь же,
|
||||
* {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела —
|
||||
* та же {@code {"error": …}}.
|
||||
*
|
||||
* <p>Регрессия — ApiKeyFilterTest.</p>
|
||||
* <p>Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen,
|
||||
* ApiKeyFilterTest#docsOpenWithoutKey.</p>
|
||||
*/
|
||||
@Component
|
||||
final class ApiKeyFilter extends OncePerRequestFilter {
|
||||
|
||||
static final String HEADER = "X-API-Key";
|
||||
|
||||
/** Открытые пути без ключа: actuator (Docker HEALTHCHECK) и springdoc-документация. */
|
||||
private static final String[] OPEN_PREFIXES = {"/actuator/", "/swagger-ui", "/v3/api-docs"};
|
||||
|
||||
/** null — аутентификация выключена. */
|
||||
private final byte[] expected;
|
||||
|
||||
@@ -37,7 +44,7 @@ final class ApiKeyFilter extends OncePerRequestFilter {
|
||||
@Override
|
||||
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
|
||||
FilterChain chain) throws ServletException, IOException {
|
||||
if (expected == null || request.getRequestURI().startsWith("/actuator/")) {
|
||||
if (expected == null || isOpen(path(request))) {
|
||||
chain.doFilter(request, response);
|
||||
return;
|
||||
}
|
||||
@@ -54,4 +61,23 @@ final class ApiKeyFilter extends OncePerRequestFilter {
|
||||
response.getWriter().write(
|
||||
"{\"error\":\"Ключ доступа не передан или неверен (заголовок X-API-Key)\"}");
|
||||
}
|
||||
|
||||
/**
|
||||
* Путь приложения без forwarded-префикса: при
|
||||
* server.forward-headers-strategy=framework заголовок X-Forwarded-Prefix
|
||||
* становится contextPath, и getRequestURI() возвращает URI уже с ним —
|
||||
* матч по сырому URI теряет /actuator/ (Docker HEALTHCHECK получил бы 401).
|
||||
*/
|
||||
private static String path(HttpServletRequest request) {
|
||||
return request.getRequestURI().substring(request.getContextPath().length());
|
||||
}
|
||||
|
||||
private static boolean isOpen(String path) {
|
||||
for (String prefix : OPEN_PREFIXES) {
|
||||
if (path.startsWith(prefix)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
package ru.pjandro.wordpdf.app;
|
||||
|
||||
import io.swagger.v3.oas.annotations.Operation;
|
||||
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
|
||||
import org.springframework.http.ContentDisposition;
|
||||
import org.springframework.http.HttpHeaders;
|
||||
import org.springframework.http.MediaType;
|
||||
@@ -60,6 +61,7 @@ final class ConvertController {
|
||||
description = "renderCharts/renderSmartArt — факультативно, по умолчанию настройки ядра; "
|
||||
+ "лимиты входа (размер/страницы) задаёт только конфигурация сервера "
|
||||
+ "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются")
|
||||
@SecurityRequirement(name = OpenApiConfig.SCHEME)
|
||||
@PostMapping(
|
||||
path = "/api/v1/convert",
|
||||
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
package ru.pjandro.wordpdf.app;
|
||||
|
||||
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
|
||||
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
|
||||
import io.swagger.v3.oas.annotations.security.SecurityScheme;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
|
||||
/**
|
||||
* Схема доступа X-API-Key для springdoc: без неё Swagger UI не показывает
|
||||
* Authorize и «Try it out» слал бы запросы без ключа (401). Документация
|
||||
* наружу открыта (ApiKeyFilter), секрет — сам ключ, он в спеке не хранится.
|
||||
*/
|
||||
@Configuration(proxyBeanMethods = false)
|
||||
@SecurityScheme(
|
||||
name = OpenApiConfig.SCHEME,
|
||||
type = SecuritySchemeType.APIKEY,
|
||||
paramName = ApiKeyFilter.HEADER,
|
||||
description = "Ключ доступа (свойство сервера wordpdf.api-key, прод — env WORDPDF_API_KEY)")
|
||||
class OpenApiConfig {
|
||||
|
||||
static final String SCHEME = "ApiKey";
|
||||
}
|
||||
@@ -17,3 +17,11 @@ wordpdf.convert-timeout=2m
|
||||
# Ключ доступа (заголовок X-API-Key). Пусто = аутентификация выключена
|
||||
# (dev: java -jar / тесты). В docker-compose задан ${WORDPDF_API_KEY:?} — fail-closed.
|
||||
wordpdf.api-key=
|
||||
|
||||
# Работа за префикс-срезающим прокси (прод: наружный nginx срезает
|
||||
# /pdf-converter/): ForwardedHeaderFilter восстанавливает схему/хост/префикс из
|
||||
# X-Forwarded-*, springdoc генерирует swagger-config и server спека с префиксом.
|
||||
# 'native' (клапан Tomcat) X-Forwarded-Prefix не понимает — только 'framework'.
|
||||
server.forward-headers-strategy=framework
|
||||
# Swagger UI: не требовать ключ заново после перезагрузки страницы
|
||||
springdoc.swagger-ui.persist-authorization=true
|
||||
|
||||
@@ -88,10 +88,28 @@ class ApiKeyFilterTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
void openApiRequiresKey() throws Exception {
|
||||
// в тестах springdoc включён; в проде выключен env'ом — фильтр
|
||||
// накрывает документацию, когда она активна
|
||||
void docsOpenWithoutKey() throws Exception {
|
||||
// документация наружу открыта без ключа (браузер не может положить
|
||||
// ключ в заголовок при загрузке UI); в тестах springdoc включён
|
||||
mockMvc.perform(get("/v3/api-docs"))
|
||||
.andExpect(status().isUnauthorized());
|
||||
.andExpect(status().isOk())
|
||||
.andExpect(jsonPath("$.components.securitySchemes.ApiKey.type").value("apiKey"))
|
||||
.andExpect(jsonPath("$.components.securitySchemes.ApiKey.name").value("X-API-Key"));
|
||||
mockMvc.perform(get("/swagger-ui/index.html"))
|
||||
.andExpect(status().isOk());
|
||||
}
|
||||
|
||||
@Test
|
||||
void forwardedPrefix_healthStaysOpen() throws Exception {
|
||||
// X-Forwarded-Prefix переезжает в contextPath, getRequestURI() — с префиксом;
|
||||
// без отсечения contextPath в фильтре HEALTHCHECK получил бы 401
|
||||
mockMvc.perform(get("/actuator/health").header("X-Forwarded-Prefix", "/pdf-converter"))
|
||||
.andExpect(status().isOk());
|
||||
}
|
||||
|
||||
@Test
|
||||
void forwardedPrefix_docsOpenWithoutKey() throws Exception {
|
||||
mockMvc.perform(get("/v3/api-docs").header("X-Forwarded-Prefix", "/pdf-converter"))
|
||||
.andExpect(status().isOk());
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user