Skip to content

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

  1. Problem & Design
  2. System Actors
  3. Invite Token Lifecycle
  4. Invitation Signup Flow
  5. Forced Token Refresh Sub-Flow
  6. Security Controls & Attack Scenarios
  7. Error Codes
  8. Known Gaps & Production Readiness
  9. 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

  1. Angular → Browser — full navigation: window.location.href = '/bff/invite/accept?token=…'.

  2. Gate — InviteTokenConsumer (addFilterBefore(..., OAuth2AuthorizationRequestRedirectFilter.class), runs ahead of Spring’s own OAuth2 filters):

    • No token param → 400 (code 01)
    • Unknown token → 404 (code 02)
    • Already BEING_CONSUMED → 410 (code 04)
    • NOT_CONSUMED_YET → attempts the atomic transition; loses the race → 409 (code 03); wins → continues down the chain.
  3. Authorize redirect — CustomAuth0SignupRequestBuilder (custom OAuth2AuthorizationRequestResolver for base URI /bff/invite/accept):

    • Re-reads the invite (defensive fallback; expects status already BEING_CONSUMED).
    • Delegates to DefaultOAuth2AuthorizationRequestResolver for a separate client registration auth0-signup (same Auth0 app/client-id/secret as auth0 login, different redirect-uri: /bff/signup/callback) — generates PKCE (withPkce(), S256) and state, stored in HttpSessionOAuth2AuthorizationRequestRepository.
    • Stashes PendingSignupData(token, firstName, lastName, email) in the HTTP session via PendingSignupSessionStore, for the callback handler to read back.
    • Adds to the /authorize call: 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.
  4. Browser → Auth0 — hosted signup form (pre-filled), user sets password, Auth0 creates the account, redirects to /bff/signup/callback?code=…&state=….

  5. Code exchange — OAuth2LoginAuthenticationFilter (stock Spring Security, mechanically identical to login): validates/consumes state, exchanges the code server-to-server (client_secret + code_verifier), validates the ID token (NimbusJwtDecoder, RS256/JWKS). Spring provisionally establishes the session-backed SecurityContext + OAuth2AuthorizedClient before any signup-specific check runs. Pipeline-level failures (bad state/PKCE, invalid_grant, etc.) go to Auth0FailureErrorResponseGenerator — §7.

  6. Verify, claim, provision — BffSignupCallbackReceiver (custom AuthenticationSuccessHandler; every failure branch calls reject(), which invalidates the provisional session before returning an error):

    1. Load PendingSignupData from session — missing → 400 (code 05).
    2. Extract ID token — missing → 400 (code 06).
    3. Verify idToken.getEmail() equals the invited email — mismatch → 409 (code 08) (invite not yet deleted at this point).
    4. Claim the invite: deleteUserInvitationBy(token) — 0 rows (raced by a concurrent completion) → 409 (code 09).
    5. Provision: Auth0ManagementClient.updateAppMetadata() writes skyledgeUserId/skyledgeOrganizationId (random UUIDs in the current demo, not sourced from the invite record) against the Management API tenant.
    6. Force claim propagation — §5.
    7. Clear the pending-signup session attribute, redirect to Angular.

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 throw

Only 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_hint and 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 with skyledgeUserId/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 to NOT_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.