UNOMI-904: V2 API compatibility mode

[sergehuber]

Stacked PR (merge order)

Role	Branch
Base (merge into)	UNOMI-139-platform (#760)
Head (this PR)	UNOMI-904-v2-api-compatibility

Merge #760 first (multi-tenant platform). This PR adds V2 compatibility on top of that line.

---

JIRA: UNOMI-904 — V2 API Compatibility mode (sub-task of UNOMI-875)

Problem

Unomi 3.x uses tenant-scoped API keys for REST access. Existing V2 clients expect:

• Public endpoints (e.g. /cxs/context.json) with no authentication
• Private endpoints with system administrator credentials (e.g. Karaf karaf/karaf)
• Protected events validated via source IP and X-Unomi-Peer, using legacy third-party provider configuration

Without a compatibility path, every client must be rewritten before a V3 rollout—high risk, no incremental migration, and no way to validate V3 with production-like V2 traffic.

Solution

This PR introduces an optional V2 compatibility mode (off by default) on the REST layer:

1. Configuration — OSGi org.apache.unomi.rest.authentication.cfg, Karaf system properties, and environment variables (UNOMI_REST_AUTHENTICATION_V2COMPATIBILITYMODEENABLED, UNOMI_REST_AUTHENTICATION_V2COMPATIBILITYDEFAULTTENANTID). Mode can be toggled at runtime via Configuration Admin without restarting bundles.

2. Authentication behaviour (when enabled) — AuthenticationFilter + DefaultRestAuthenticationConfig:

   • Public paths — no API key; requests run under a configured default tenant
   • Private paths — JAAS system-admin authentication (V2-style), then default tenant context for data operations
   • Protected events — V2ThirdPartyConfigService reads legacy org.apache.unomi.thirdparty settings (provider key, allowed IPs, allowed event types) and validates IP + X-Unomi-Peer like V2

3. Packaging — REST auth config is deployed from the unomi-rest Karaf feature; defaults are documented in the cfg file and overridable in custom.system.properties.

Mapping to UNOMI-904 acceptance criteria

Criterion	Status in this PR
V2 clients can use V3 without client code changes (auth patterns)	✅ Public / private / protected-event paths implemented
Public endpoints work without authentication	✅
Private endpoints work with system administrator authentication	✅
Protected events work with IP + X-Unomi-Peer	✅ via V2ThirdPartyConfigService
Mode enabled/disabled via configuration	✅ default off; runtime updates supported
Default tenant for all operations in compatibility mode	✅ v2.compatibilitymode.defaultTenantId
Supports gradual migration (test V3, migrate apps over time)	✅ operational goal; mode is temporary by design

Broader REST surface (profiles, segments, rules, schemas) continues to use the same CXS endpoints; with compatibility mode on, V2 auth rules apply before tenant API-key enforcement. Dedicated IT coverage focuses on context, configuration persistence, default tenant, and protected events.

Configuration (summary)

Setting	Default	Purpose
v2.compatibilitymode.enabled	false	Enable V2 compatibility mode
v2.compatibilitymode.defaultTenantId	default	Tenant used for all operations in V2 mode (should match migration target tenant)

Third-party providers (protected events): thirdparty.{name}.key, .ipAddresses, .allowedEvents in org.apache.unomi.thirdparty.cfg (unchanged V2 layout).

Tests

• V2CompatibilityModeIT — registered in AllITs; Pax Exam / Karaf integration tests:
  • Switch V2 mode on/off and verify public vs private behaviour
  • Protected events (view event + third-party config)
  • Default tenant resolution
  • Configuration persistence via Configuration Admin
• Full integration test suite run locally with OpenSearch (same harness as other platform ITs).

Licence

• I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.