feat: strict scheme enforcement — strip Authorization: Basic on auth failure (#4650)

[balhar-jakub]

Closes #4650

Summary

Implements strict scheme enforcement for the API Gateway. When enabled via apiml.security.strictSchemeEnforcement=true, any Authorization: Basic header is stripped upon authentication failure for non-BYPASS schemes. This prevents credential confusion attacks where a Basic auth header could bypass stricter scheme enforcement.

Changes

• AbstractAuthSchemeFactory: Core enforcement logic — strips Authorization: Basic headers on auth failure for httpBasicPassTicket, zoweJwt, zosmf, safIdt schemes
• X509FilterFactory: Same enforcement for X509 client certificate authentication
• PassticketFilterFactory, AbstractTokenFilterFactory, RoutingConfigurationErrorFilterFactory: Updated callers to pass serviceId for logging
• RouteConfigurationErrorFilterFactoryTest: Updated Mockito verify for 3-arg overload

Behavior

• Default: apiml.security.strictSchemeEnforcement=false (no change)
• When enabled: only strips Authorization: Basic — does NOT affect other Authorization schemes (Bearer, etc.)
• Skips BYPASS scheme and null scheme cases
• Case-insensitive matching on "Basic " prefix

Architectural review to follow.

[balhar-jakub]

Architect Review — #4650 Strict Scheme Enforcement

Build verification

• ./gradlew clean build: 3 pre-existing failures (AttlsConfigTest ×2, AvailabilityTest, client-cert-auth-sample MainTest) — all unrelated to this change
• Gateway-service: 524 tests, 1 pre-existing failure (AttlsConfigTest port conflict)
• All filter tests pass ✓ (RoutingConfigurationErrorFilterFactoryTest, AbstractTokenFilterFactoryTest)
• ./gradlew :gateway-service:compileJava — BUILD SUCCESSFUL ✓

Design compliance ✓

The implementation follows the PM's acceptance criteria and the architect's design spec. Core logic is in AbstractAuthSchemeFactory.cleanHeadersOnAuthFail() — single-point change for all inheriting schemes.

Structural review

Strengths:

• ✅ Backward compatible: strictSchemeEnforcement defaults to false
• ✅ Proper guards: skips BYPASS and null scheme cases
• ✅ Case-insensitive matching on Basic prefix
• ✅ Thread-safe: exchange attribute pattern works in reactive pipeline
• ✅ Config consistency: both AbstractAuthSchemeFactory and X509FilterFactory use same property
• ✅ Diagnostic logging at DEBUG level with scheme name

Minor observations (non-blocking):

1. Code duplication — The Basic-stripping logic is duplicated between AbstractAuthSchemeFactory (line ~239) and X509FilterFactory (line ~82). Nearly identical: auth header check, regionMatches, header removal, debug log. This is understandable since X509FilterFactory doesn't extend AbstractAuthSchemeFactory, but future readers may not realize both need updating if the logic changes.

2. X509 debug log missing serviceId — AbstractAuthSchemeFactory logs service {} (scheme: {}) — X509FilterFactory logs only (scheme: x509). For operational diagnostics parity, consider extracting serviceId from exchange attributes in X509 as well.

3. Unit test coverage — The strict enforcement logic itself lacks dedicated unit tests (noted as coming in Area 3). This is fine for now but should be addressed before merge.

Verdict: APPROVED with minor notes. The implementation is clean, well-guarded, and correctly scoped. The duplication and logging disparity are minor polish items — no architectural concerns.

Post-merge follow-up

• Area 3 (config + unit tests) should add tests for: enabled/disabled flag, BYPASS skip, null scheme skip, Basic stripping, non-Basic preservation, case insensitivity

[balhar-jakub]

Architect Review — #4650 Strict Scheme Enforcement

Build verification

• ./gradlew clean build: 3 pre-existing failures (AttlsConfigTest ×2, AvailabilityTest, client-cert-auth-sample MainTest) — all unrelated to this change
• Gateway-service: 524 tests, 1 pre-existing failure (AttlsConfigTest port conflict)
• All filter tests pass (RoutingConfigurationErrorFilterFactoryTest, AbstractTokenFilterFactoryTest)
• ./gradlew :gateway-service:compileJava — BUILD SUCCESSFUL

Design compliance

The implementation follows the PM's acceptance criteria and the architect's design spec. Core logic is in AbstractAuthSchemeFactory.cleanHeadersOnAuthFail() — single-point change for all inheriting schemes.

Structural review

Strengths:

• Backward compatible: strictSchemeEnforcement defaults to false
• Proper guards: skips BYPASS and null scheme cases
• Case-insensitive matching on Basic prefix
• Thread-safe: exchange attribute pattern works in reactive pipeline
• Config consistency: both AbstractAuthSchemeFactory and X509FilterFactory use same property
• Diagnostic logging at DEBUG level with scheme name

Minor observations (non-blocking):

1. Code duplication — The Basic-stripping logic is duplicated between AbstractAuthSchemeFactory and X509FilterFactory. Nearly identical: auth header check, regionMatches, header removal, debug log. This is understandable since X509FilterFactory doesn't extend AbstractAuthSchemeFactory, but future maintainers may not realize both need updating if the logic changes.

2. X509 debug log missing serviceId — AbstractAuthSchemeFactory logs service {} (scheme: {}) — X509FilterFactory logs only (scheme: x509). For operational diagnostics parity, consider extracting serviceId from exchange attributes in X509 as well.

3. Unit test coverage — The strict enforcement logic itself lacks dedicated unit tests (noted as coming in Area 3). This is fine for now but should be addressed before merge.

Verdict: APPROVED with minor notes. The implementation is clean, well-guarded, and correctly scoped. The duplication and logging disparity are minor polish items — no architectural concerns.

Post-merge follow-up

• Area 3 (config + unit tests) should add tests for: enabled/disabled flag, BYPASS skip, null scheme skip, Basic stripping, non-Basic preservation, case insensitivity

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
88.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[balhar-jakub]

QA Review — PR #4743 (Strict Scheme Enforcement #4650)

Verdict: PASSED ✅

All 8 acceptance criteria verified. All Pavel's Lens rules checked. Tests pass. No blocking issues found.

Test Results

Test Class	Result
AbstractAuthSchemeFactoryTest (8 tests)	✅ All pass
X509FilterFactoryTest (existing + 2 new)	✅ All pass
RoutingConfigurationErrorFilterFactoryTest	✅ All pass
AbstractTokenFilterFactoryTest	✅ All pass
PassticketFilterFactoryTest	✅ All pass

Acceptance Criteria Verification

#	Criterion	Status	Evidence
AC1	Strict=true + httpBasicPassTicket -> Basic stripped	✅	Test 1
AC2	Strict=true + zoweJwt/zosmf/safIdt/x509 -> Basic stripped	✅	Test 1 + X509 test
AC3	Strict=true + BYPASS -> Basic preserved	✅	Test 3
AC4	Strict=false (default) -> no change	✅	Test 2 + X509 disabled test
AC5	DEBUG log with serviceId + scheme	✅	log.debug with service {} (scheme: {})
AC6	x-zowe-auth-failure still set after stripping	✅	Test 5
AC7	Bearer NOT affected	✅	Test 4
AC8	Works for all non-bypass schemes	✅	Code check + X509 separate handling

Pavel's Lens — All 8 Rules

Rule	Status	Notes
1. Config Consistency	✅	strictSchemeEnforcement in gateway application.yml + @value default false
2. Deduplication	MINOR	Basic-stripping duplicated in AbstractAuthSchemeFactory and X509FilterFactory. Justified — different inheritance trees.
3. Null Safety	✅	Guards: scheme != null, authValues != null, v != null
4. Test Parametrization	✅	10 tests, each testing distinct scenario
5. Security Boundaries	✅	Only Basic stripped. Bearer preserved. BYPASS exempt. Case-insensitive.
6. z/OS Awareness	✅	Simple header manipulation. No blocking.
7. Log Quality	MINOR	X509FilterFactory log missing serviceId — minor operational gap
8. TODO Tracking	✅	No new TODOs

Minor Notes (non-blocking)

1. X509 serviceId in log — Consider extracting serviceId from exchange attributes for parity
2. Code duplication — Both architect and QA note the duplication. Acceptable; extract if a third location needs it.

Files Reviewed

• AbstractAuthSchemeFactory.java — core enforcement + serviceId overload
• X509FilterFactory.java — X509 adaptation
• AbstractTokenFilterFactory.java — caller update
• PassticketFilterFactory.java — caller update
• RoutingConfigurationErrorFilterFactory.java — caller update (null serviceId)
• application.yml — config property
• AbstractAuthSchemeFactoryTest.java — 8 new tests
• X509FilterFactoryTest.java — 2 new tests
• RoutingConfigurationErrorFilterFactoryTest.java — verify updated

[balhar-jakub]

Security Review — PR #4743 (Strict Scheme Enforcement #4650)

Verdict: APPROVED ✅

No CRITICAL, HIGH, or MEDIUM findings. The implementation is security-sound and correctly scoped.

Pavel's Lens — All 8 Rules

Rule	Status	Notes
1. Config Consistency	✅	Single property apiml.security.strictSchemeEnforcement used consistently. Default false.
2. Deduplication	MINOR	Basic-stripping duplicated in AbstractAuthSchemeFactory and X509FilterFactory. Justified — different inheritance trees.
3. Null Safety	✅	Triple guard: scheme != null, authValues != null, v != null. ServiceId gracefully nullable.
4. Test Parametrization	✅	10 tests covering 8 distinct behavioral scenarios.
5. Security Boundaries	✅	Only Basic stripped. BYPASS exempt. Case-insensitive match. Default off. No escalation path.
6. z/OS Awareness	✅	Header manipulation only. No blocking. No race conditions.
7. Log Quality	MINOR	X509FilterFactory log missing serviceId (parity gap with AbstractAuthSchemeFactory). Non-blocking.
8. TODO Tracking	✅	No new TODOs.

Security Review — 6 Categories

Category	Status	Notes
Auth/authz	✅	Operates at Gateway filter level. BYPASS explicitly exempt. No privilege escalation.
Input validation	✅	Case-insensitive regionMatches(true, ...) prefix check. Triple null guard. No injection vectors.
Data exposure	✅	Only serviceId/scheme in DEBUG logs. No credentials logged. Test values are placeholders (not real credentials).
Dependencies	✅	No new dependencies. Imports: @Value, List, AtomicReference — all Spring/Java stdlib.
Configuration	✅	No hardcoded secrets. Default false is safe (opt-in). Property under apiml.security.
Secrets management	✅	No tokens/keys in code.

Threat Model Analysis

What the feature prevents: A client sends Authorization: Basic <user:password> to a service registered with httpBasicPassTicket (or any non-bypass scheme). ZAAS fails to generate a PassTicket. Previously, the raw SAF password would transparently pass through to the backend. With strictSchemeEnforcement: true, the Authorization: Basic header is stripped before forwarding.

Attack surface reduced: Removes the "shadow authentication" vector where raw mainframe credentials could reach a backend service that should only receive transformed credentials (PassTicket, JWT, etc.).

What the feature does NOT do:

• Does NOT strip Authorization: Bearer — expired JWTs are short-lived and useless
• Does NOT affect scheme: bypass services — intentional passthrough preserved
• Does NOT change auth-success behavior — only fires on auth failure
• Does NOT add latency — header check is O(n) on a small list

CI Status

All required checks pass:

• BuildAndTest ✅
• CITests (all variants) ✅
• CITestsRegistration ✅
• SonarCloud Code Analysis ✅

Minor Notes (non-blocking, already flagged by QA)

1. X509 log parity — AbstractAuthSchemeFactory logs serviceId + scheme; X509FilterFactory only logs scheme. Extract from exchange attributes for consistency.
2. Code duplication — Basic-stripping logic in two places. Extract to shared utility if a third location needs it.

Files Reviewed

• AbstractAuthSchemeFactory.java — core enforcement + serviceId overload
• X509FilterFactory.java — X509 adaptation
• AbstractTokenFilterFactory.java — caller update
• PassticketFilterFactory.java — caller update
• RoutingConfigurationErrorFilterFactory.java — caller update (null serviceId)
• application.yml — config property
• AbstractAuthSchemeFactoryTest.java — 8 unit tests
• X509FilterFactoryTest.java — 2 unit tests
• RoutingConfigurationErrorFilterFactoryTest.java — verify updated

All gates passed: Architect ✓, QA ✓, Security ✓