UNOMI-904: V2 API compatibility mode#762
Merged
Merged
Conversation
1 task
sergehuber
force-pushed
the
UNOMI-139-platform
branch
from
4c5828e to
d2093d1
Compare
sergehuber
force-pushed
the
UNOMI-904-v2-api-compatibility
branch
from
2419ae7 to
a7c5f92
Compare
sergehuber
force-pushed
the
UNOMI-139-platform
branch
from
d2093d1 to
6f3f768
Compare
sergehuber
force-pushed
the
UNOMI-904-v2-api-compatibility
branch
from
a7c5f92 to
39595c8
Compare
sergehuber
force-pushed
the
UNOMI-139-platform
branch
from
6f3f768 to
c36e1fd
Compare
sergehuber
force-pushed
the
UNOMI-904-v2-api-compatibility
branch
from
39595c8 to
3bc0172
Compare
sergehuber
force-pushed
the
UNOMI-904-v2-api-compatibility
branch
from
3bc0172 to
219abb7
Compare
Introduce the Unomi 3.1 platform core: tenant-scoped execution, unified multi-type caching, cluster-aware scheduling, and 3.1.0 migration tooling. REST layers use V3 tenant resolution and role-based auth. UNOMI-139 — Multi-tenancy - Tenant model and APIs (Tenant, TenantService, API keys, security and audit hooks, quotas, lifecycle listeners) - ExecutionContextManager and tenant propagation across services, persistence (Elasticsearch/OpenSearch), GraphQL, and REST - Tenant-scoped items and definitions (system tenant vs tenant overrides) UNOMI-880 — Unified multi-tenant caching - MultiTypeCacheService, CacheableTypeConfig, and shared cache lifecycle (refresh, statistics, predefined item bundling) - Migrate DefinitionsService and SegmentService onto the unified cache; remove superseded ad-hoc cache listeners UNOMI-878 — Cluster-aware task scheduling - SchedulerService with persistent and in-memory tasks, TaskExecutor registration, and cluster-aware execution - Integrate periodic work (cache refresh, cluster heartbeat, router jobs, rule refresh) via the new scheduler API UNOMI-884 — Migration to V3 - 3.1.0 migration Groovy scripts and Elasticsearch request bodies (tenant document IDs, system item ID fixes, tenant initialization, legacy queryBuilder updates) - MigrationUtils extensions and MigrationUtilsTest Integration tests updated for platform behaviour (including migration and ScopeIT). Verified locally with OpenSearch integration tests.
Let V2 client applications run on the V3 multi-tenant platform without rewriting authentication first: compatibility mode can be toggled at runtime, legacy third-party API keys and IP/X-Unomi-Peer checks apply for protected events, and public endpoints such as /context.json stay usable without tenant API keys while V3 tenant auth remains the default when the mode is off. - V2ThirdPartyConfigService wired to org.apache.unomi.thirdparty.cfg - REST authentication filter and config for V2 compatibility routing - Event collector allowlist checks in RestServiceUtilsImpl - Karaf packaging for org.apache.unomi.rest.authentication.cfg - V2CompatibilityModeIT in the integration test suite
testV2CompatibilityModeWithProtectedEvents loads events/viewEvent.json; resource was missing after V peel (Appendix J peel-fix).
- Fix ordering-dependent data loss in V2ThirdPartyConfigService.modified() by using a two-pass approach: collect raw properties first, then build ProviderConfig objects (OSGi ConfigAdmin property order is undefined) - Mask X-Unomi-Peer secret in debug logs (RestServiceUtilsImpl, V2ThirdPartyConfigService) using a maskSecret() helper - Add @Designate annotation to DefaultRestAuthenticationConfig so OSGi metatype descriptors are generated correctly by bnd - Trim and blank-check v2CompatibilityDefaultTenantId in DefaultRestAuthenticationConfig, falling back to "default" if blank - Replace null checks with StringUtils.isNotBlank() for defaultTenantId in AuthenticationFilter.handleV2CompatibilityMode() (both public-path and JAAS sections) - Wrap CloseableHttpClient/CloseableHttpResponse pairs in try-with-resources in V2CompatibilityModeIT to avoid connection pool leaks - Fix misleading test comments: V3 API keys in V2 mode are ignored, not rejected — requests return 200 with 0 processed events
…duplication Move the maskSecret() helper from V2ThirdPartyConfigService and RestServiceUtilsImpl into a new SecurityUtils class in services-common, which is already the home for security utilities like IPValidationUtils. Add unit tests covering null, empty, short, boundary, and typical 32-char shared-secret inputs.
The main fix is that private endpoints with JAAS auth were always returning 401 in V2 mode — the JAAS subject had no TenantPrincipal, so resolveTenantId() couldn't find the tenant. We now build a merged subject with a TenantPrincipal for the default tenant before handing off to downstream processing. Two smaller filter bugs are fixed alongside: a blank defaultTenantId on a public path would silently fall through to the private-endpoint handler, and a null security context after JAAS was ignored rather than denied. The default tenant is now checked for existence before use, and V2ThirdPartyConfigService logs a clear warning when falling back to the well-known default key. On the test side, session and profile IDs are now per-test UUIDs, three negative cases cover the main rejection branches (unknown key, wrong IP, wrong event type), PatchIT polls for sendMailAction instead of asserting immediately, and GraphQLListIT refreshes Profile persistence before querying list membership.
sergehuber
force-pushed
the
UNOMI-904-v2-api-compatibility
branch
from
a4d2d2d to
ad94a66
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked PR (merge order)
UNOMI-139-platform(#760)UNOMI-904-v2-api-compatibilityMerge #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:
/cxs/context.json) with no authenticationkaraf/karaf)X-Unomi-Peer, using legacy third-party provider configurationWithout 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:
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.Authentication behaviour (when enabled) —
AuthenticationFilter+DefaultRestAuthenticationConfig:V2ThirdPartyConfigServicereads legacyorg.apache.unomi.thirdpartysettings (provider key, allowed IPs, allowed event types) and validates IP +X-Unomi-Peerlike V2Packaging — REST auth config is deployed from the
unomi-restKaraf feature; defaults are documented in the cfg file and overridable incustom.system.properties.Mapping to UNOMI-904 acceptance criteria
X-Unomi-PeerV2ThirdPartyConfigServicev2.compatibilitymode.defaultTenantIdBroader 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)
v2.compatibilitymode.enabledfalsev2.compatibilitymode.defaultTenantIddefaultThird-party providers (protected events):
thirdparty.{name}.key,.ipAddresses,.allowedEventsinorg.apache.unomi.thirdparty.cfg(unchanged V2 layout).Tests
V2CompatibilityModeIT— registered inAllITs; Pax Exam / Karaf integration tests:viewevent + third-party config)Licence