[server] Enforce access control on admin API routes

[xiangfu0]

Summary

• apply the configured Server AccessControlFactory centrally across the admin listener
• keep the three health/readiness declarations public and preserve table-level checks for the two data-download declarations
• define a Server-specific administrative authorization contract for built-in and custom access-control implementations
• attach configurable service identities to in-scope Controller and Broker calls to protected Server operations
• document the route inventory, rolling migration, default behavior, and the separate Minion trust-boundary assumption

The inventoried boundary is 3 public JAX-RS declarations, 2 table-data declarations, 48 privileged JAX-RS declarations, and 3 privileged static-handler prefixes. New or custom routes fail closed as privileged unless the built-in classification is deliberately extended.

Root cause and reproduction

The Server admin application bound an AccessControlFactory, but only handlers that explicitly performed table-data authorization consulted it. As a result, configuring Server access control did not consistently cover non-table administrative operations.

To reproduce the previous behavior, configure a Server access-control factory and send an unauthenticated request to a non-table administrative operation. The request could reach the resource without consulting the configured factory. With this change, missing or invalid credentials receive 401, authenticated identities without administrative authority receive 403, and authorized administrators succeed.

Compatibility

• Existing table-data authorization remains in the resource methods.
• AllowAllAccessFactory preserves the unconfigured/default behavior.
• The additive authorizeAdminAccess SPI method defaults to deny, so custom implementations remain binary compatible and must opt into administrative access explicitly.
• Basic authentication requires an explicit admin permission; ZK-backed authentication requires role ADMIN and component SERVER.
• Controller and Broker service credentials can be configured before enabling the Server boundary for rolling upgrades.
• Minion code is unchanged. Deployments using protected Server listeners with affected task paths must retain a trusted internal network or inject identity at a proxy/service-mesh boundary.

Validation

• 112 targeted tests passed across Server authorization, table-data, health/readiness, static handlers, AllowAll, ZK auth, shared HTTP transport, Controller/Broker internal calls, and protected-cluster integration coverage.
• spotless:apply, license:format, checkstyle:check, and license:check passed for all affected modules.
• Warning-enabled test-compile passed for all affected modules.
• git diff --check passed.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 36.89320% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.78%. Comparing base (cb89c0e) to head (70348bb).

Files with missing lines	Patch %	Lines
...he/pinot/server/access/BasicAuthAccessFactory.java	0.00%	21 Missing ⚠️
.../pinot/server/access/ZkBasicAuthAccessFactory.java	61.70%	12 Missing and 6 partials ⚠️
...che/pinot/server/access/HttpRequesterIdentity.java	0.00%	13 Missing ⚠️
...e/pinot/common/utils/FileUploadDownloadClient.java	0.00%	6 Missing ⚠️
...apache/pinot/common/swagger/SwaggerSetupUtils.java	0.00%	4 Missing ⚠️
...org/apache/pinot/core/auth/BasicAuthPrincipal.java	0.00%	1 Missing ⚠️
.../org/apache/pinot/server/access/AccessControl.java	0.00%	1 Missing ⚠️
...che/pinot/server/access/AllowAllAccessFactory.java	0.00%	1 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (cb89c0e) and HEAD (70348bb). Click for more details.

HEAD has 14 uploads less than BASE

Flag	BASE (cb89c0e)	HEAD (70348bb)
unittests	2	1
java-25	4	1
temurin	4	1
lane-a	1	0
integration	2	0
integration2	2	0
lane-b	1	0
unittests2	1	0

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #19233      +/-   ##
============================================
- Coverage     66.97%   57.78%   -9.20%     
+ Complexity     1417        1    -1416     
============================================
  Files          3453     2657     -796     
  Lines        218858   159207   -59651     
  Branches      34787    26115    -8672     
============================================
- Hits         146591    91999   -54592     
+ Misses        60556    59393    -1163     
+ Partials      11711     7815    -3896     

Flag	Coverage Δ
integration	?
integration2	?
java-25	57.78% <36.89%> (-9.20%)	⬇️
lane-a	?
lane-b	?
temurin	57.78% <36.89%> (-9.20%)	⬇️
unittests	57.78% <36.89%> (-9.20%)	⬇️
unittests1	57.78% <36.89%> (+0.06%)	⬆️
unittests2	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.