Access and Onboarding¶
Landing and Sign-In Entry¶
Use the landing page to start authentication. The primary action calls the portal login flow and returns users to the customer portal after authentication.
Sign-Up Behavior¶
When users select Sign up from customer login, they are routed to the customer portal registration page (/register) instead of Keycloak's default registration screen.
The page supports two onboarding paths:
- Self Registration: customer submits profile details, receives email verification and password setup flow
- Onboarded by CFA: company/CFA admin creates or links the customer, then the customer receives onboarding email actions
Note
A customer can exist without a CFA link and can later be linked to one or more CFAs.
Customers are importers or exporters that may work with one or more clearing agents. After onboarding, a linked customer can exchange messages, receive invoices/contracts, track shipments, rate completed services, and raise complaints.
Access Scope and Role Guard¶
Customer users are constrained to customer workflows only. If an active SSO session belongs to a user without customer-portal access, the app forces re-login so the user can switch account.
Session Basics¶
- the app checks SSO status at load
- token refresh runs automatically in the background
- expired/invalid refresh falls back to login
- registered passkeys can be used from the Keycloak login page as a passwordless sign-in option
Common Access Issues¶
| Symptom | Likely cause | Action |
|---|---|---|
| redirected back to login | user lacks customer-portal role in active SSO session | sign out and sign in with customer-authorized account |
| sign-up submission fails | validation error or duplicate email | correct input and retry, or use password-reset/verify-email flows for existing accounts |
| blank/blocked after auth | stale SSO callback params or expired session | refresh browser and retry login |
| passkey registration does not open browser prompt | unsupported browser/device or interrupted Keycloak required action | retry over HTTPS from a passkey-capable browser |