This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a commit to branch UNOMI-1009-1010-1012-docs-4.0
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/UNOMI-1009-1010-1012-docs-4.0
by this push:
new 79160dc31 UNOMI-1009 UNOMI-1012: Restore the compatibility-mode anchor
and fix shell examples
79160dc31 is described below
commit 79160dc31976eeb41d882297140b607c4a80d176
Author: Serge Huber <[email protected]>
AuthorDate: Mon Nov 2 11:30:41 2026 +0100
UNOMI-1009 UNOMI-1012: Restore the compatibility-mode anchor and fix shell
examples
- Asciidoctor keeps only the last of two stacked block ids, so the
_v2_compatibility_mode anchor used by many pages was lost. Keep it on the
heading and add _single_tenant_compatibility_mode as an inline anchor.
- 2.x/3.x sent credentialed CORS to every origin, but their SameSite=Lax
cookie
only reached same-site pages.
- Use the positional unomi:crud syntax in the tenant examples.
- Public context and event endpoints answer 401 without a key outside
single-tenant compatibility mode.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
manual/src/main/asciidoc/configuration.adoc | 10 +++++-----
manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc | 2 +-
manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc | 6 +++---
3 files changed, 9 insertions(+), 9 deletions(-)
diff --git a/manual/src/main/asciidoc/configuration.adoc
b/manual/src/main/asciidoc/configuration.adoc
index e7e1ce91e..a71a80b36 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -381,16 +381,16 @@ Using Karaf shell (requires admin access to Karaf
console). See <<_shell_command
[source,bash]
----
# Create a tenant (JSON properties)
-unomi:crud create tenant -d '{"itemId":"mytenant","name":"My
Company","description":"My Company tenant"}'
+unomi:crud create tenant '{"itemId":"mytenant","name":"My
Company","description":"My Company tenant"}'
# List tenants
unomi:crud list tenant
# View tenant details
-unomi:crud read tenant -i mytenant
+unomi:crud read tenant mytenant
# Delete a tenant
-unomi:crud delete tenant -i mytenant
+unomi:crud delete tenant mytenant
----
==== API Keys and Authentication
@@ -403,7 +403,7 @@ The API keys are generated when creating a tenant, but the
tenant resource only
[source,bash]
----
# Using Karaf shell (requires admin access) — metadata only
-unomi:crud read tenant -i mytenant
+unomi:crud read tenant mytenant
# Obtain plaintext (store immediately; it is not persisted)
curl -X POST "http://localhost:8181/cxs/tenants/mytenant/apikeys?type=PUBLIC"; \
@@ -442,7 +442,7 @@ curl -X POST
"http://localhost:8181/cxs/tenants/mytenant/apikeys?type=PUBLIC&val
}
# Using Karaf shell (requires admin access)
-unomi:crud create apikey -d
'{"tenantId":"mytenant","keyType":"PUBLIC","validityPeriod":30}'
+unomi:crud create apikey
'{"tenantId":"mytenant","keyType":"PUBLIC","validityPeriod":30}'
----
==== Accessing API Endpoints
diff --git a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
index f3815eea4..5fdaea3d5 100644
--- a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc
@@ -201,7 +201,7 @@ API paths stay the same between 3.0 and 4.0, and most
request/response payloads
[#_client_facing_hardening_4_0]
==== Client-facing hardening (4.0)
-`/cxs/context.json` and `/cxs/eventcollector` are reachable without
authentication, or with a tenant *public* API key. In 4.0 the identity fields
those endpoints accept are treated as claims to be checked rather than as
instructions.
+`/cxs/context.json` and `/cxs/eventcollector` need a tenant *public* API key
(or a tenant private key or administrator credentials); without one Unomi
answers `401`, unless <<_v2_compatibility_mode,single-tenant compatibility
mode>> is enabled. In 4.0 the identity fields those endpoints accept are
treated as claims to be checked rather than as instructions.
A caller is **trusted** when it holds a tenant private key or authenticates as
a system administrator (`ROLE_UNOMI_ADMIN` or `ROLE_UNOMI_TENANT_ADMIN`). A
tenant *public* API key is **not** trusted: it identifies the tenant, not the
visitor.
diff --git a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
index d6d7cf1ac..38f4eff9d 100644
--- a/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
+++ b/manual/src/main/asciidoc/migrations/v2-compatibility-mode.adoc
@@ -13,10 +13,9 @@
//
[#_v2_compatibility_mode]
-[#_single_tenant_compatibility_mode]
=== single-tenant compatibility mode
-This document explains how to use single-tenant compatibility mode in Apache
Unomi 4.0. The mode lets client applications
+[[_single_tenant_compatibility_mode]]This document explains how to use
single-tenant compatibility mode in Apache Unomi 4.0. The mode lets client
applications
written for Unomi 2.x or Unomi 3.x keep working without tenant API keys while
you move them to the 4.0 authentication model.
==== Overview
@@ -38,7 +37,8 @@ When single-tenant compatibility mode is enabled:
about 30 seconds, so public requests do not wait on each other or re-read it
from the database
every time. A change made on another node is picked up after about that time.
- **No authentication** is required for non-protected events (like Unomi 2 and
Unomi 3)
-- **The visitor cookie is limited to listed websites** (unlike Unomi 2.x and
3.x, which let pages on any origin use it).
+- **The visitor cookie is limited to listed websites** (unlike Unomi 2.x and
3.x, which sent credentialed CORS headers to every origin; their `SameSite=Lax`
cookie still
+ reached only pages on the same site).
A website on another origin, another subdomain included, must be listed in
`UNOMI_PUBLIC_CORS_ALLOWED_ORIGINS` or in the
`default` tenant's `publicCorsAllowedOrigins` property, for its requests to
use and receive the cookie, whether it calls
`context.json` or embeds `context.js` with a `<script>` tag. A plain
`<script>` tag (without a `crossorigin` attribute)
