Public Webforms: Deep-link handling and security - #1792
Draft
nospame wants to merge 12 commits into
Draft
Conversation
When a request carries the `CommCare-Public-Session: true` header and a `public_form_session_key` cookie, the session auth filter now produces a typed PublicSessionCredential instead of the Django sessionid string, and HqUserDetailsService sends it to HQ's session_details endpoint as `publicSessionKey` rather than `sessionId`. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
HQ's session_details response marks a public web apps session (one-time link) with a JSON `public` field. Add a boolean publicSession field mapped via @JsonProperty("public"). Uses a primitive boolean so a missing field defaults to false, which matters because the bean is @JsonIgnoreProperties(ignoreUnknown = true) and would otherwise silently drop it. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
When HqUserDetailsBean.publicSession is true, isAuthorized() no longer requires the request's username to equal the bean's username. Public web apps sessions authenticate via a single-use key that HQ validates server-to-server, and their username is a synthetic per-session string (not a real account), so echoing it is not a meaningful membership control. The requested domain is still required to be the session's domain (domains.contains(domain)). This keeps a session key from being replayed against a different domain. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
For a public web apps session, formplayer's outbound calls to HQ must send the `public_form_session_key` cookie together with the `CommCare-Public-Session: true` header, and must NOT send the Django `sessionid`. - New `PublicFormSessionAuth` (an `HqAuth`) emits exactly that cookie+header pair and nothing else; its key is guarded and never logged. - `UserRestoreAspect.getHqAuth` now selects the credential for the request: if the authenticated user is a public session it returns a `PublicFormSessionAuth` built from the session key, otherwise the existing `DjangoAuth`/null. Gated on the HMAC-authenticated `public` field (`isPublicSession()`), never on the client-supplied header; the public credential is preferred when both signals are present. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A public web apps session authenticates with the public_form_session_key cookie, not the Django sessionid, so the required sessionid @CookieValue on MenuController.navigateToEndpoint (get_endpoint) rejected it at request binding (400) before the handler. Relax that cookie to required=false, as answer/submit-all already do. A cookie-less non-public request is still rejected upstream by the session auth request matcher. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add a default-deny route allowlist for public web apps sessions, enforced in the Spring Security authorization layer. getPublicSessionAuthManager grants a request if it is authenticated AND either the principal is not a public session or the path is one of specified form-navigation routes. Every other route is denied with the app's standard 403 before any controller or aspect runs. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
For a public web apps session, HQ's session_details response carries the app id and session endpoint that the one-time link is bound to. Add publicAppId (@JsonProperty "commcare_app_id") and publicEndpointId (@JsonProperty "endpoint_id") to the bean. Reference types, so they default to null for non-public responses that omit them. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Both app_id and endpoint_id in a get_endpoint request are client-supplied, so a valid public session key could otherwise open any app/form in the domain. PublicSessionLockAspect, for a public session, replaces the request's app_id and endpoint_id with the HMAC-authenticated values HQ returned (HqUserDetailsBean.publicAppId/publicEndpointId) and clears endpoint args, confining the session to its one designated form. It fails closed if HQ did not supply those authoritative values rather than trusting the client. Runs before AppInstallAspect (which keys the sandbox DB off the request's app_id), so storage, the MenuSession build, and endpoint navigation all use the authoritative app. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The lock aspect silently returned if the first handler arg was not an InstallRequestBean, which for a public session would let the request proceed without pinning it to the authoritative app/endpoint. Unreachable today (every allowlisted @appinstall route takes a SessionNavigationBean), but preserves the fail-closed contract for any future allowlisted route with a different request bean. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A public web apps session is a one-time deep link into a single endpoint, so endpoint navigation is intrinsic to it. For public sessions, bypass thegate via a new RequestUtils.isPublicSession() predicate. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A public session's username is never validated (isAuthorized skips it), and configureRestoreFactory took username/restoreAs/restoreAsCaseId straight from the client request bean. Instead, configure the restore for a public session from the HMAC-authenticated principal only, ignoring all client-supplied identity fields. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
3 tasks
nospame
changed the base branch from
ejp/public-webforms-auth
to
ejp/public-webforms-base
July 28, 2026 17:52
Verify ownership at the single load chokepoint, FormSessionFactory: a public session may only build a live session whose stored username and domain match its HMAC-authenticated principal; otherwise throw FormNotFoundException. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
nospame
force-pushed
the
ejp/public-webforms-confinement
branch
from
July 28, 2026 17:55
3207aa0 to
eecb372
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
1 participant
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.
Product Description
Public Web Apps Sessions let someone open a one-time link and fill a single, pre-designated form
without an HQ account. This PR is where that behavior is confined: a public session can reach only
the form-entry routes it needs, and is locked to the exact app, endpoint, and identity HQ bound the
link to — it cannot navigate to any other app or form.
Technical Summary
SAAS-19928, SAAS-19929, SAAS-19930
WebSecurityConfig:restrictPublicSession(...)default-deny allowlist on/validate_formandanyRequest. A public session may reach onlyget_endpoint+ the in-form actions;new-formand
validate_formare denied.get_endpoint/new-repeat:sessionidcookie binding relaxed torequired=false(publicsessions carry no Django cookie).
HqUserDetailsBean: HQ-authoritativeapp_build_id+endpoint_id.PublicSessionLockAspect(ordered ahead of all other aspects): overrides client-supplied app,endpoint, endpoint args, and identity with HQ's values; fails closed if they're missing.
UserRestoreAspect#configureRestoreFactory: a public session restores strictly as itsHQ-authenticated user (no client username / restore-as / case id).
MenuSessionRunnerService: public sessions use endpoint navigation without theSESSION_ENDPOINTStoggle - rather than building out a new method of navigation orrequiring the toggle to be enabled in HQ.
Code and PR description written or co-written by AI and edited by human. Review by commit.
Safety Assurance
Safety story
The core safety property is default-deny:
restrictPublicSessiononly ever removes access, andonly when the principal is a public session — regular sessions get exactly their prior decision. The
lock aspect and restore pinning both fail closed on missing authoritative values, and a public
session restores under its own synthetic user, so no real user's sandbox or identity is touched.
Aspect ordering (a subtle correctness requirement) is guarded by a dedicated weaving test after a
real ordering bug was caught there. Still inert in production until HQ issues links.
Automated test coverage
SessionAuthTests— allowlist: allowed routes not 403,new-form/validate_formdenied, regularsessions unaffected.
PublicSessionLockAspectTest— app/endpoint/identity override + fail-closed cases.PublicSessionLockAspectWeavingTest— proves the aspect actually weaves and is correctly ordered.EndpointLaunchTest— public launch without theSESSION_ENDPOINTStoggle.HqUserDetailsTests+ test harness (@WithHqUserpublic flag).QA Plan
Public Webforms will get end-to-end QA before its release.
Special deploy instructions
session_detailsreturningapp_build_id+endpoint_idfor public sessions. Safe to deploy formplayer first (feature stays dark until HQ issues links), but
the feature must not be enabled on HQ until this is deployed.
Rollback instructions
Review