Invitation-Based Signup Architecture
Status: Draft for Review System: Angular + Spring Boot 4.0.5 (Java 25) + Auth0 Date: July 2026 Driver: Invite-only onboarding — new users may only create an Auth0 account through a token issued by an existing organization, never through self-service signup Author: Nimash
Table of Contents
- Problem & Design
- System Actors
- Invite Token Lifecycle
- Invitation Signup Flow
- Forced Token Refresh Sub-Flow
- Security Controls & Attack Scenarios
- Error Codes
- Known Gaps & Production Readiness
- Appendix — Spring Security Component Map
1. Problem & Design
Auth0’s hosted Universal Login normally lets anyone reach a signup form. This system requires the opposite: every user belongs to exactly one organization, and only that organization can create the account for them. There is no self-service path — an account is only created by redeeming a single-use invite token bound to a specific (firstName, lastName, email).
Core principle: the invite token, not the Auth0 session, is the credential that authorizes account creation. Auth0 still runs the actual signup screen; the BFF gates access to it, steers it toward the invited identity, verifies afterward that Auth0 created that identity (not a substituted one), and binds the new Auth0 user to a skyledge user/organization ID via app_metadata.
This flow reuses the OAuth2 Authorization Code + PKCE + state + session-cookie machinery documented in cookie-based-authentication-implemantation/architecture.md — not re-derived here. What’s new is everything downstream of “Auth0 authenticated someone”: was this signup allowed, and is the resulting account the one that was invited.
| Property | Description |
|---|---|
| Invite as bearer credential | Possessing the token authorizes reaching Auth0’s signup screen for that identity. |
| Two-phase consumption | Marked BEING_CONSUMED before redirecting to Auth0; deleted only after the signed-up email is confirmed to match. Bounds the reuse window. |
| Post-hoc identity verification | login_hint only pre-fills Auth0’s form — not enforced. The BFF re-checks the ID token’s email claim against the invited email and rejects on mismatch. |
| Claim propagation via forced refresh | The first access token is minted before app_metadata is written, so it lacks skyledgeUserId/skyledgeOrganizationId. The BFF forces an immediate refresh-token grant so the next token (assumed re-minted with those claims by an Auth0 Action) carries them, and fails loudly if it doesn’t. |
2. System Actors
Signup adds a third SecurityFilterChain (@Order(0)) to the same Spring Boot process as the plain login flow, plus a Postgres invite table and a second Auth0 tenant used only for the Management API.
| Actor | Role | Trust |
|---|---|---|
Angular SPA :4200 |
Full-navigates to /bff/invite/accept?token=…; otherwise identical to login (waits for redirect, calls /me). |
Partial |
| Browser | Follows the BFF ↔ Auth0 redirect round trip; carries the provisional SESSION cookie. |
Untrusted |
Spring Boot :8080 — Chain 0 (/bff/invite/**, /bff/signup/callback) |
InviteTokenConsumer (gate filter), CustomAuth0SignupRequestBuilder (authorization request resolver), BffSignupCallbackReceiver (success handler), Auth0FailureErrorResponseGenerator (shared failure handler). @Order(0) — evaluated before the login chain. |
Fully trusted |
PostgreSQL invited_users |
One row per outstanding invite: token (PK), firstName, lastName, email, tokenStatus. Deleted on completion — no redemption history. |
Trusted |
Auth0 login tenant (auth.skyledge.com) |
Hosts Universal Login in signup mode (screen_hint=signup), issues tokens. An Auth0 Action external to this codebase is assumed to inject skyledgeUserId/skyledgeOrganizationId claims from app_metadata. |
Trusted IdP |
Auth0 Management API tenant (control-rooms.auth0.com) |
Separate tenant, reached via Auth0ManagementClient (M2M client-credentials). Only job: PATCH the new user’s app_metadata. Isolated from the login tenant’s trust boundary. |
Trusted, distinct boundary |
3. Invite Token Lifecycle
NOT_CONSUMED_YET ──(InviteTokenConsumer gate)──▶ BEING_CONSUMED ──(BffSignupCallbackReceiver, verified success)──▶ [row deleted]| State | Set by |
|---|---|
NOT_CONSUMED_YET |
InvitedUserStore.seedDemoInviteIfEmpty() — demo-only seed, hardcoded token "fake-token" (front end hardcodes the same value). |
BEING_CONSUMED |
InviteTokenConsumer via InvitedUserStore.markTokenAsConsuming(), on first valid hit of /bff/invite/accept — before redirecting to Auth0. Implemented as a single conditional UPDATE ... WHERE token = ? AND token_status = 'NOT_CONSUMED_YET' (InvitedUserRepository.updateTokenStatusIfCurrentStatus), so concurrent requests can’t both win the transition — only one gets rows-affected > 0. |
| (deleted) | BffSignupCallbackReceiver via InvitedUserStore.deleteUserInvitationBy() (bare DELETE, atomic by construction) — only after the email-match check passes. |
No path back from BEING_CONSUMED to NOT_CONSUMED_YET — an abandoned or failed signup permanently locks that invite (see §8).
retrieveTokenAndCalculateStatus() distinguishes “unknown token” (empty Optional) from “already claimed” (BEING_CONSUMED) so the gate can return 404 vs 410 respectively.
4. Invitation Signup Flow
Actors: Angular → Browser → Spring Boot Chain 0 → Auth0 login tenant → Auth0 Management API
-
Angular → Browser — full navigation:
window.location.href = '/bff/invite/accept?token=…'. -
Gate —
InviteTokenConsumer(addFilterBefore(..., OAuth2AuthorizationRequestRedirectFilter.class), runs ahead of Spring’s own OAuth2 filters):- No
tokenparam →400(code01) - Unknown token →
404(code02) - Already
BEING_CONSUMED→410(code04) NOT_CONSUMED_YET→ attempts the atomic transition; loses the race →409(code03); wins → continues down the chain.
- No
-
Authorize redirect —
CustomAuth0SignupRequestBuilder(customOAuth2AuthorizationRequestResolverfor base URI/bff/invite/accept):- Re-reads the invite (defensive fallback; expects status already
BEING_CONSUMED). - Delegates to
DefaultOAuth2AuthorizationRequestResolverfor a separate client registrationauth0-signup(same Auth0 app/client-id/secret asauth0login, differentredirect-uri:/bff/signup/callback) — generates PKCE (withPkce(), S256) andstate, stored inHttpSessionOAuth2AuthorizationRequestRepository. - Stashes
PendingSignupData(token, firstName, lastName, email)in the HTTP session viaPendingSignupSessionStore, for the callback handler to read back. - Adds to the
/authorizecall:screen_hint=signup(forces Auth0’s signup form),login_hint=<email>(pre-fill only, not enforced),ext-first_name/ext-last_name(consumed by an assumed Auth0 Action),audience(forces a signed JWT access token). - Responds 302 to Auth0.
- Re-reads the invite (defensive fallback; expects status already
-
Browser → Auth0 — hosted signup form (pre-filled), user sets password, Auth0 creates the account, redirects to
/bff/signup/callback?code=…&state=…. -
Code exchange —
OAuth2LoginAuthenticationFilter(stock Spring Security, mechanically identical to login): validates/consumesstate, exchanges the code server-to-server (client_secret+code_verifier), validates the ID token (NimbusJwtDecoder, RS256/JWKS). Spring provisionally establishes the session-backedSecurityContext+OAuth2AuthorizedClientbefore any signup-specific check runs. Pipeline-level failures (badstate/PKCE,invalid_grant, etc.) go toAuth0FailureErrorResponseGenerator— §7. -
Verify, claim, provision —
BffSignupCallbackReceiver(customAuthenticationSuccessHandler; every failure branch callsreject(), which invalidates the provisional session before returning an error):- Load
PendingSignupDatafrom session — missing →400(code05). - Extract ID token — missing →
400(code06). - Verify
idToken.getEmail()equals the invited email — mismatch →409(code08) (invite not yet deleted at this point). - Claim the invite:
deleteUserInvitationBy(token)—0rows (raced by a concurrent completion) →409(code09). - Provision:
Auth0ManagementClient.updateAppMetadata()writesskyledgeUserId/skyledgeOrganizationId(random UUIDs in the current demo, not sourced from the invite record) against the Management API tenant. - Force claim propagation — §5.
- Clear the pending-signup session attribute, redirect to Angular.
- Load
5. Forced Token Refresh Sub-Flow
The first access token is minted before app_metadata exists, so it lacks the custom claims (assuming an Auth0 Action injects them from app_metadata at issuance). AccessTokenRefresher.forceRefreshingAccessTokenWhileOldOneIsStillValid() forces a refresh immediately rather than waiting for expiry:
BffSignupCallbackReceiver └─ save access token with expiresAt backdated -1s (lies to Spring's bookkeeping only, not Auth0) └─ OAuth2AuthorizedClientManager.authorize() └─ POST /oauth/token { grant_type=refresh_token, client_id, client_secret, refresh_token } (real Auth0 round trip) └─ new access token, expected to carry skyledgeUserId / skyledgeOrganizationId └─ decode + assert both claims present — else throwOnly the signup path needs this; a returning user’s app_metadata was already set on a prior signup, so their first-ever token already carries the claims.
6. Security Controls & Attack Scenarios
| Threat | Severity | Control |
|---|---|---|
| Unauthorized self-signup | HIGH | screen_hint=signup is only ever attached by CustomAuth0SignupRequestBuilder, reachable only through a valid, unclaimed invite. (Auth0 tenant must also disable direct public signup — outside this codebase.) |
| Invite reuse (sequential) | HIGH | deleteUserInvitationBy() — second attempt finds no row → 409 (code 09). |
| Invite reuse (concurrent) | — | Closed by the atomic conditional UPDATE in markTokenAsConsuming() (§3) — only one concurrent request can transition NOT_CONSUMED_YET → BEING_CONSUMED; the final DELETE is atomic regardless. |
| Identity substitution | HIGH | Post-callback idToken.getEmail() vs. invited email check, before any provisioning happens. |
| Stale authorization claims | HIGH | Forced refresh + claim-presence assertion in AccessTokenRefresher — throws rather than proceeding without org-scoping claims. |
| Management API misuse | MED | Auth0ManagementClient uses a distinct Auth0 tenant/M2M grant, isolated from the login tenant. |
| Half-authenticated session on rejection | MED | Every reject() path invalidates the provisional HTTP session before erroring. |
| Auth-code interception / login CSRF | HIGH | PKCE (S256) + state — identical mechanism to login; see cookie-based-authentication-implemantation/architecture.md §6–7 for the full walkthrough (not repeated here). |
Notable attack scenarios specific to this flow (generic OAuth2 code-interception/CSRF covered in the referenced doc):
- Invite email substitution — an attacker with someone else’s invite link could ignore
login_hintand sign up with their own email. Closed by the email-match check in step 6.3 above: the attacker’s Auth0 account may exist, but is never provisioned withskyledgeUserId/skyledgeOrganizationId, so it can’t call this app’s API. - Abandoned signup locks the invite — not an external attack, but a self-inflicted DoS: once
BEING_CONSUMED, there’s no path back toNOT_CONSUMED_YET. A closed tab or failed email check permanently locks that invite, including for its intended recipient. See §8.
7. Error Codes
Every rejection resolves via response.sendRedirect(frontendBaseUrl + "/error?code=<NN>") — no server-rendered page.
| Code | HTTP status (conceptual) | Meaning | Source |
|---|---|---|---|
01 INVITE_TOKEN_MISSING |
400 | No token query param on /bff/invite/accept |
InviteTokenConsumer |
02 INVITE_TOKEN_UNKNOWN |
404 | Token not found in invited_users |
InviteTokenConsumer |
03 INVITE_TOKEN_CONFLICT |
409 | Lost the gate-transition race (token flipped by another request) | InviteTokenConsumer |
04 INVITE_TOKEN_ALREADY_USED |
410 | Token already BEING_CONSUMED |
InviteTokenConsumer |
05 SIGNUP_CONTEXT_MISSING |
400 | No PendingSignupData in session at callback |
BffSignupCallbackReceiver |
06 ID_TOKEN_MISSING |
400 | No OIDC ID token on the authenticated principal | BffSignupCallbackReceiver |
07 ID_TOKEN_CLAIMS_EMPTY |
400 | ID token has no claims | BffSignupCallbackReceiver |
08 INVITE_EMAIL_MISMATCH |
409 | Signed-up email ≠ invited email | BffSignupCallbackReceiver |
09 INVITE_ALREADY_USED |
409 | Invite row already deleted by a concurrent completion | BffSignupCallbackReceiver |
10 OIDC_PIPELINE_FAILURE |
400/403/502/500 (varied) | Spring-Security-level OIDC failure (bad state/PKCE, code-exchange error, etc.) |
Auth0FailureErrorResponseGenerator |
99 UNCAUGHT_ERROR |
any uncaught 5xx | Catch-all — any unhandled exception that reaches /error |
FrontendErrorRedirectController |
Appendix — Spring Security Component Map
| Concern | Component |
|---|---|
| Invite-gate check | InviteTokenConsumer (addFilterBefore(..., OAuth2AuthorizationRequestRedirectFilter.class)) |
| Signup authorization request | CustomAuth0SignupRequestBuilder (authorizationEndpoint().authorizationRequestResolver(...)) |
| PKCE generation (delegated) | OAuth2AuthorizationRequestCustomizers.withPkce() |
| Pending OAuth2 request storage | HttpSessionOAuth2AuthorizationRequestRepository |
| Pending signup context storage | PendingSignupSessionStore |
| Callback handling, state validation, code exchange | OAuth2LoginAuthenticationFilter (redirectionEndpoint().baseUri("/bff/signup/callback")) |
| ID token validation | NimbusJwtDecoder via OidcIdTokenDecoderFactory |
| Signup verification, invite claim, provisioning | BffSignupCallbackReceiver (.oauth2Login().successHandler(...)) |
Auth0 app_metadata write |
Auth0ManagementClient (M2M client-credentials) |
| Forced claim-propagation refresh | AccessTokenRefresher (OAuth2AuthorizedClientManager/Repository) |
| Shared OIDC/OAuth2 failure handling | Auth0FailureErrorResponseGenerator (.oauth2Login().failureHandler(...)) |
| Error-code surfacing via redirect | FrontendErrorRedirectController |
Related: cookie-based-authentication-implemantation/architecture.md — plain login flow, token refresh flow, and the PKCE/state attack-scenario walkthroughs this document builds on.