fix(openapi): add securitySchemes and global security requirement to OpenAPI spec

[mbiuki]

Summary

Fixes #34996

The OpenAPI spec at /api/openapi.json declared security: [] globally with no securitySchemes defined, documenting all 689 endpoints as unauthenticated even though the server enforces auth on the vast majority of them.

• Add @SecuritySchemes to DotRestApplication — three schemes matching the actual auth waterfall in WebResource.java: ApiToken (JWT Bearer), BasicAuth (HTTP Basic), DotAuth (DOTAUTH header)
• Set global security default in @OpenAPIDefinition — all endpoints now require auth in the spec unless explicitly overridden
• Mark 16 genuinely public endpoints with security = {} override: health/liveness/readiness checks (required for k8s probes), login, forgot password, and all SAML SSO flow endpoints

Files Changed

File	Change
DotRestApplication.java	Add @SecuritySchemes + global security to @OpenAPIDefinition
HealthResource.java	security = {} on all 8 health endpoints
AuthenticationResource.java	security = {} on login + logInUser
ForgotPasswordResource.java	security = {} on forgot password
DotSamlResource.java	security = {} on all 5 SAML SSO endpoints

Test Plan

• curl https://<instance>/api/openapi.json | jq '.components.securitySchemes' — should return ApiToken, BasicAuth, DotAuth schemes
• curl https://<instance>/api/openapi.json | jq '.security' — should return [{"ApiToken":[]},{"BasicAuth":[]}]
• Verify health endpoints still have "security": [] in the generated spec
• Verify SAML, login, and forgot-password endpoints have "security": []
• Run spec through 42Crunch or OWASP ZAP — admin/infra endpoints should no longer be flagged as unauthenticated
• Confirm dotCMS starts and /api/openapi.json is served without errors

🤖 Generated with Claude Code

[claude]

Claude finished @sfreudenthaler's task in 1m 33s —— View job

---

PR Review

• Gather context
• Read changed files
• Analyze for issues
• Post review

---

Three issues worth fixing before merge:

---

1. SAML metadata endpoint is admin-only but marked security = {}

DotSamlResource.java:368-372 explicitly enforces admin-only access at runtime:

if (!new WebResource.InitBuilder(this.webResource).rejectWhenNoUser(true)
        .requestAndResponse(httpServletRequest, httpServletResponse)
        .requiredBackendUser(true).init().getUser().isAdmin()) {
    throw new RuntimeException(new DotSecurityException("SAML metadata is only accessible by administrators"));
}

But DotSamlResource.java:340-342 marks it public in the spec:

@Operation(
    summary = "Get SAML metadata",
    security = {}  // ← wrong: this endpoint requires admin auth
)

This will tell API consumers the /api/v1/dotsaml/metadata/{idpConfigId} endpoint needs no auth, which is the opposite of reality. Fix this →

---

2. All /api/v1/health/* endpoints marked security = {}, but most are auth-protected by default

The PR description says these are marked public because they're "required for k8s probes." That's a wrong assumption. The actual k8s probe endpoints live in HealthProbeServlet.java (served at /livez, /readyz, etc.) — they are a servlet, not JAX-RS, and don't appear in the OpenAPI spec at all.

The HealthResource.java class comment confirms this: "This is separate from infrastructure monitoring endpoints (/livez, /readyz) which are designed for read-only access by infrastructure tools like Kubernetes."

The runtime auth is controlled by health.detailed.authentication.required (default true). With the default config, all 8 health endpoints require admin access — but the spec documents all of them as unauthenticated.

The state-mutating endpoints are especially risky to document as public:

• POST /api/v1/health/refresh (HealthResource.java:449) — triggers a full health check refresh
• POST /api/v1/health/refresh/{checkName} (HealthResource.java:506) — triggers a targeted refresh

These should not have security = {}. Fix this →

---

3. DotAuth scheme is defined but excluded from global security

DotRestApplication.java:54-60 defines the DotAuth scheme but DotRestApplication.java:69-72 only lists ApiToken and BasicAuth in the global security:

security = {
    @SecurityRequirement(name = "ApiToken"),
    @SecurityRequirement(name = "BasicAuth")
    // DotAuth is missing here
},

OpenAPI treats the global security entries as alternatives (OR logic). Omitting DotAuth means the spec implies it is not a valid auth method for the 673 endpoints that don't override security, even though WebResource.java accepts the DOTAUTH header everywhere. Either add DotAuth to the global requirement or remove the scheme definition if it's intentionally not documented as a global option. Fix this →

---

The core concept of the PR (adding @SecuritySchemes + flipping the default to auth-required) is the right approach. The three issues above are all correctness problems, not just documentation nits.