[
https://issues.apache.org/jira/browse/UNOMI-1001?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber updated UNOMI-1001:
-------------------------------
Description:
h3. Summary
Single-tenant compatibility mode helps existing installations move to 4.0
without changes. In 3.0, a trusted server that sent the X-Unomi-Peer header
could:
* send protected events, such as login and updateProperties,
* set event ids,
* merge profiles on login, choose the profile id in a request, and update other
profiles' properties, segments, scores and consents.
In 4.0 compatibility mode, the header is still checked before an event is
accepted. But the server is then treated like a normal visitor, so the features
above stop working. The documentation of the mode says it behaves "like V2".
The goal of this ticket is that a server that worked with 3.0 keeps working in
compatibility mode with no change on its side, and that the configuration makes
it easy to run this safely.
h3. Decided approach
Restore the 3.0 behaviour for servers that pass the X-Unomi-Peer check, with
these limits:
* Only when compatibility mode is on, and only on public endpoints. The header
gives nothing on admin endpoints, and nothing in normal mode.
* Only when both the key and the caller's IP address match a configured
provider.
* Protected events only for the provider's allowed event types.
* Only the abilities 3.0 gave such a server, never administrator rights. Each
provider may list the abilities it gets; the default is the 3.0 set, so
existing clients need no change.
* The checks from UNOMI-975 and UNOMI-978 stay as they are for every other
caller.
Configuration that keeps this safe:
* Compatibility mode stays off by default.
* A provider whose key is empty, too short, or equal to the example value from
the shipped configuration is disabled, and Unomi logs a clear error at startup
that says how to fix it. A clearly named setting may allow the example value
during a transition, with a warning at every start.
* The caller IP is the direct connection address by default. Operators can list
trusted reverse proxies; forwarded headers are only used when the direct
address is one of them.
* Keys are compared in constant time and never written in full to the logs.
Each trusted request is logged at debug level with the provider id.
* The compatibility mode page documents every setting, gives a safe example,
and explains the reverse proxy case.
h3. How to test
Manual check: in compatibility mode, send requests from a configured
third-party server. Check that profile merge on login, a request with a
profileId, and an event with an itemId work as they did in 3.0.
Automated tests to add in the compatibility mode integration tests:
* With a valid provider: protected events, event ids, profile merge on login, a
request with a profileId, and updates of another profile all work.
* A visitor with no key still gets none of these features.
* Right key from an allowed IP works; right key from another IP is refused;
wrong key is refused.
* An event type that is not allowed for the provider is refused.
* A provider limited to some abilities gets only those.
* Empty, short and example keys disable the provider at startup with a clear
error; the transition setting allows the example key and logs a warning.
* Forwarded headers are ignored unless the direct address is a trusted proxy,
and used when it is.
* The header gives nothing on admin endpoints, and nothing in normal mode.
* The existing tests for UNOMI-975 and UNOMI-978 still pass.
was:
h3. Summary
Single-tenant compatibility mode helps existing installations move to 4.0
without changes. In 3.0, a trusted server that sent the X-Unomi-Peer header
could:
* merge profiles on login,
* choose the profile id in a request,
* set event ids,
* update other profiles' properties, segments, scores and consents.
In 4.0 compatibility mode, the header is still checked before an event is
accepted. But the server is then treated like a normal visitor, so all of the
features above stop working. The documentation of the mode says it behaves
"like V2".
The goal of this ticket is that a server that worked with 3.0 keeps working in
compatibility mode, or that the documentation says clearly what changes.
h3. Ways to explore
* Preferred: document that 3.0 third-party servers should move to a tenant
private API key, which already provides these features. Update the
compatibility mode page.
* If trust based on X-Unomi-Peer is restored, keep it narrow:
** only in compatibility mode, and only on public endpoints,
** only when both the key and the caller's IP address match,
** only the abilities that 3.0 gave a third-party server, for its allowed event
types, never administrator rights,
** only for a key the operator has set, never the example value from the
shipped configuration,
** without changing the checks from UNOMI-975 and UNOMI-978 in normal mode.
* Document how the caller IP is seen behind a reverse proxy.
h3. How to test
Manual check: in compatibility mode, send requests from a configured
third-party server. Check that profile merge on login, a request with a
profileId, and an event with an itemId work as they did in 3.0, or that the
documented new way works.
Automated tests to add in the compatibility mode integration tests:
* With the documented way (private API key, or X-Unomi-Peer if trust is
restored): profile merge on login, a request with a profileId, an event with an
itemId, and an update of another profile's properties all work.
* A visitor with no key still gets none of these features.
If trust based on X-Unomi-Peer is restored, also add one test per limit:
* right key from an allowed IP works; right key from another IP is refused;
wrong key is refused,
* the example key from the shipped configuration is refused,
* an event type that is not allowed for the server is refused,
* the header gives nothing on admin endpoints, and nothing in normal mode,
* the existing tests for UNOMI-975 and UNOMI-978 still pass.
> In compatibility mode, 3.0 third-party servers lose features
> ------------------------------------------------------------
>
> Key: UNOMI-1001
> URL: https://issues.apache.org/jira/browse/UNOMI-1001
> Project: Apache Unomi
> Issue Type: Bug
> Affects Versions: unomi-4.0.0
> Reporter: Serge Huber
> Priority: Blocker
> Fix For: unomi-4.0.0
>
>
> h3. Summary
> Single-tenant compatibility mode helps existing installations move to 4.0
> without changes. In 3.0, a trusted server that sent the X-Unomi-Peer header
> could:
> * send protected events, such as login and updateProperties,
> * set event ids,
> * merge profiles on login, choose the profile id in a request, and update
> other profiles' properties, segments, scores and consents.
> In 4.0 compatibility mode, the header is still checked before an event is
> accepted. But the server is then treated like a normal visitor, so the
> features above stop working. The documentation of the mode says it behaves
> "like V2".
> The goal of this ticket is that a server that worked with 3.0 keeps working
> in compatibility mode with no change on its side, and that the configuration
> makes it easy to run this safely.
> h3. Decided approach
> Restore the 3.0 behaviour for servers that pass the X-Unomi-Peer check, with
> these limits:
> * Only when compatibility mode is on, and only on public endpoints. The
> header gives nothing on admin endpoints, and nothing in normal mode.
> * Only when both the key and the caller's IP address match a configured
> provider.
> * Protected events only for the provider's allowed event types.
> * Only the abilities 3.0 gave such a server, never administrator rights. Each
> provider may list the abilities it gets; the default is the 3.0 set, so
> existing clients need no change.
> * The checks from UNOMI-975 and UNOMI-978 stay as they are for every other
> caller.
> Configuration that keeps this safe:
> * Compatibility mode stays off by default.
> * A provider whose key is empty, too short, or equal to the example value
> from the shipped configuration is disabled, and Unomi logs a clear error at
> startup that says how to fix it. A clearly named setting may allow the
> example value during a transition, with a warning at every start.
> * The caller IP is the direct connection address by default. Operators can
> list trusted reverse proxies; forwarded headers are only used when the direct
> address is one of them.
> * Keys are compared in constant time and never written in full to the logs.
> Each trusted request is logged at debug level with the provider id.
> * The compatibility mode page documents every setting, gives a safe example,
> and explains the reverse proxy case.
> h3. How to test
> Manual check: in compatibility mode, send requests from a configured
> third-party server. Check that profile merge on login, a request with a
> profileId, and an event with an itemId work as they did in 3.0.
> Automated tests to add in the compatibility mode integration tests:
> * With a valid provider: protected events, event ids, profile merge on login,
> a request with a profileId, and updates of another profile all work.
> * A visitor with no key still gets none of these features.
> * Right key from an allowed IP works; right key from another IP is refused;
> wrong key is refused.
> * An event type that is not allowed for the provider is refused.
> * A provider limited to some abilities gets only those.
> * Empty, short and example keys disable the provider at startup with a clear
> error; the transition setting allows the example key and logs a warning.
> * Forwarded headers are ignored unless the direct address is a trusted proxy,
> and used when it is.
> * The header gives nothing on admin endpoints, and nothing in normal mode.
> * The existing tests for UNOMI-975 and UNOMI-978 still pass.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
