sergehuber opened a new pull request, #762: URL: https://github.com/apache/unomi/pull/762
### Stacked PR (merge order) | Role | Branch | |------|--------| | **Base (merge into)** | `UNOMI-139-platform` ([#760](https://github.com/apache/unomi/pull/760)) | | **Head (this PR)** | `UNOMI-904-v2-api-compatibility` | Merge [#760](https://github.com/apache/unomi/pull/760) first (multi-tenant platform). This PR adds V2 compatibility on top of that line. --- **JIRA:** [UNOMI-904](https://issues.apache.org/jira/browse/UNOMI-904) — *V2 API Compatibility mode* (sub-task of [UNOMI-875](https://issues.apache.org/jira/browse/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 - [x] I hereby declare this contribution to be licenced under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
