PR D: Phase 2.0 integration test — auth-code flow + introspection + token-response augmentation end-to-end (closes #122 Step 6) #148

Summary

The literal acceptance criterion of #122 Step 6 ("one integration test that boots both modules, mints a real token via the authorization code flow, calls a data-custodian endpoint, and asserts the principal carries subscription_id") has not been written. The work shipped across PRs B1 → B2 → C1 → C2a → C2b → C3 → C4 enabled this test; PR D writes it. Closes #122 cleanly and gives Phase 2 (#119) a concrete fence-post to build on.

Filed as a tracking issue per project lead. Implementation queued until DC API completion work is in flight or AS attention is available.

Goal

One automated integration test that boots AS + DC in a real Spring context, programmatically completes the OAuth2 authorization-code flow (bypassing customer UI), exchanges the code at /oauth2/token, asserts the response and introspection both carry C4's canonical URI claims, and uses the access token against a DC resource endpoint.

What "real" means

• AS and DC both fully bean-wired (not mocked).
• The back-channel call (AS → DC /internal/backchannel/v1/subscriptions) actually goes over HTTP.
• The opaque-token introspection call (DC → AS /oauth2/introspect) actually goes over HTTP.
• Customer UI (login form, Authorization Screen) is bypassed by pre-seeding OAuth2AuthorizationConsent + the C4.1 GrantContext — equivalent to what the customer would have produced if walked through the flow.

Sub-tasks

D.1 — Test harness scaffolding (2-3h)

• New test class: openespi-datacustodian/src/test/java/.../integration/AuthCodeFlowEndToEndIntegrationTest.java
• Single-JVM, dual-Spring-context approach:
  • @SpringBootTest(classes = DataCustodianApplication.class, webEnvironment = RANDOM_PORT)
  • AS booted programmatically in @BeforeAll via new SpringApplicationBuilder(AuthorizationServerApplication.class).run(...) on a separate random port
  • @DynamicPropertySource injects AS's chosen port into DC's spring.security.oauth2.resourceserver.opaquetoken.introspection-uri, and vice versa for AS's espi.backchannel.endpoint
• TestContainers MySQL: single container with datacustodian + oauth2_authserver schemas pre-created via init SQL

D.2 — Auth-flow simulation (2-3h)

Pre-seed via direct repository / service calls (not HTTP):

• DC: RetailCustomerEntity with known username and numeric id
• AS: OAuth2AuthorizationConsent for (third_party_client_id, customer_principal_name, "FB_1;FB_4_5")
• AS: GrantContext for that customer's session via the C4.1 session store

Then exercise the flow:

• Build MockMvc / TestRestTemplate for AS, manually inject SecurityContext with the customer's Authentication
• Trigger GET /oauth2/authorize?response_type=code&client_id=third_party&redirect_uri=...&scope=FB_1;FB_4_5&state=test
• Capture the code from the redirect's Location header

D.3 — Token mint + assertions (1-2h)

• POST /oauth2/token with grant_type=authorization_code + the code + third_party Basic auth → assert 200 + response JSON contains access_token, token_type=Bearer, scope, resourceURI, authorizationURI, customerResourceURI (C4's additionalParameters)
• POST /oauth2/introspect with the access token + Basic auth (resource-server client) → assert claims include the same three URIs + authorization_id + resource_subscription_id + customer_subscription_id (or whichever subset matches the granted scope)
• GET /espi/1_1/resource/Authorization/{id} on DC with Authorization: Bearer <token> → assert 200 (or whatever the canonical "use the token" smoke is)

D.4 — Negative paths (optional, defer if scope tightens)

• Back-channel down at token mint → asserts error=server_error
• Code replay (second /token call with same code) → asserts error=invalid_grant
• Token used after revocation → asserts error=invalid_token on resource endpoint

D.5 — CI integration (1h)

• Verify the test class is picked up by Failsafe (likely needs *IntegrationTest naming)
• Verify TestContainers Docker is available in CI runner (already is for other modules)
• Add to mvn verify -Pintegration-tests invocation in ci.yml if not already covered

Effort estimate

1 working day end-to-end, possibly stretching to 1.5 if dual-context coexistence in one JVM is finicky. D.4 is optional polish.

Open design questions

1. subscription_id semantics. Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122 Step 6 says "asserts the principal carries subscription_id." PR C4 produces resource_subscription_id and customer_subscription_id (granular per ESPI Function Block grant). Do we add a single combined subscription_id claim for the original intent, or is the granular form acceptable per Phase 2's consumer (Remediation: ESPI REST controller modernization (post-#116) #119)?

2. Test location. New test in openespi-datacustodian/src/test/java/.../integration/ (lives with DC where the resource server is) or a new top-level test module (overkill for one class)?

3. Dual-context strategy. Single JVM with both Spring contexts (faster, simpler to write) vs. two JVMs (closer to production, more reliable but harder to set up). Recommendation: single JVM unless we hit context-conflict pain.

4. Database isolation. Single TestContainers MySQL with both schemas vs. two containers. Recommendation: single.

5. Which DC resource endpoint does the test exercise after token mint? Need a pre-existing canonical "happy path" endpoint that works on the current DC. Candidate: /espi/1_1/resource/Authorization/{id} since C4 surfaces the canonical Authorization URI.

Risks

• Dual-context port juggling could be flaky. Mitigation: use Spring's @DynamicPropertySource carefully, validate both apps are listening before issuing requests.
• OAuth2AuthorizationConsent pre-seeding doesn't exercise all of C4.1's enricher logic since we're skipping the C3 /continue path. Acceptable tradeoff — that's covered by unit tests in GrantContextEnrichingAuthorizationServiceTest.
• MockMvc vs. real HTTP for AS calls. The back-channel + introspection MUST be real HTTP (those are the inter-module calls). The customer-side auth-code flow CAN be MockMvc since it's all within AS's process — simpler and faster.
• The pre-existing H2 DATETIME issue doesn't affect this test (using MySQL via TestContainers).

Out of scope for this issue

• Customer-UI walkthrough — C2a/C2b/C3 are validated by their own unit tests + the deferred browser E2E in TP bring-up: missing JAXB Atom marshaller, narrow component scan, and broader OAuth2-client wiring gaps #146.
• Refresh-token flow.
• Token revocation flow.
• Multiple-customer / multiple-grant scenarios.
• The Phase 2 subscription-scoping work in Remediation: ESPI REST controller modernization (post-#116) #119 — that's the next consumer of this test's contract.

Acceptance

• Test passes locally and in CI
• /oauth2/token response JSON has resourceURI, authorizationURI, customerResourceURI
• /oauth2/introspect response includes the same URI claims + subscription IDs
• DC accepts the access token on a resource endpoint
• Test runs in <60s wall-clock (TestContainers spin-up acceptable)
• Test is robust enough that flaky-runs don't get green-merged accidentally
• Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122 is closeable (this is its missing acceptance test)

Dependencies

• PR feat(#122 PR C4): AS-side back-channel call + token-response augmentation #147 (PR C4) merged — provides the token-response augmentation this test asserts on
• DC has a working resource endpoint to call — see open question Complete Spring Boot 3.5 Migration with Legacy Code Removal and Data Security #5
• Optional: design alignment on subscription_id claim shape — see open question Bump commons-io:commons-io from 2.4 to 2.14.0 in /openespi-datacustodian #1

Related

• Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122 — the umbrella Phase 2.0 issue this closes
• Remediation: ESPI REST controller modernization (post-#116) #119 — Phase 2 subscription scoping, depends on this test's contract
• Complete #123 schema-repair sync: align AS V1 schema with application code column names #145 — AS V1 schema repair, independent
• TP bring-up: missing JAXB Atom marshaller, narrow component scan, and broader OAuth2-client wiring gaps #146 — TP bring-up, independent (browser E2E is TP's territory)