84 lines
6.2 KiB
Markdown
84 lines
6.2 KiB
Markdown
# ZitPlane — Account and Login User Guide
|
|
|
|
**Documentation baseline:** 2026-11-22, source through P04 `40af500`.
|
|
**Current availability:** Account Portal source exists but is **NOT built, integrated, tested or publicly deployed**. URLs and button outcomes below describe the reviewed **intended behavior of current source**. Do not treat this guide as proof the site is accessible today.
|
|
|
|
## Who uses which interface?
|
|
|
|
| Interface | URL / current status | Purpose |
|
|
| --- | --- | --- |
|
|
| ZITADEL identity/login (official prebuilt in P02 dev Compose) | Intended `http://localhost:8080/ui/v2/login/` in local development, not live-tested | Sign in/registration/challenge and account recovery according to ZITADEL policies |
|
|
| ZITADEL management Console | Intended `http://localhost:8080/ui/console` locally, not live-tested | Identity administration and, if enabled, user self-service |
|
|
| ZitPlane Account Portal | Intended `http://localhost:3001` *after* future OIDC setup/build, not running yet | Read-only account profile and security navigation |
|
|
| Production login / account domain | `https://auth.vib.tools`, `https://account.vib.tools` are **planned only** | No production deployment, TLS or routing yet |
|
|
|
|
## Sign in to Account Portal
|
|
|
|
**Page:** `/signin` — `users/ui/src/app/signin/page.tsx`
|
|
|
|
1. Open the future Account Portal URL after its deployment and configuration.
|
|
2. Choose **Continue with ZITADEL**. The form starts Auth.js sign-in with ZITADEL OIDC. Your browser is sent to the central ZITADEL login service.
|
|
3. Authenticate using the identity methods available to your organization (password, MFA, passkey or external IdP as configured there).
|
|
4. On successful OIDC callback, the portal is intended to redirect to `/account`. Unauthenticated or expired users should return to `/signin`.
|
|
5. **Back to account home** links to `/`; that route redirects to `/account`. If not signed in, the protected layout redirects back to `/signin`.
|
|
|
|
**Signup and Forgot Password:** The Account Portal's `/signin` page has **no local registration/reset form**. Those flows belong to the official ZITADEL Login V2 service, where availability and labels depend on ZITADEL policy. ZitPlane imported the source but has not modified or tested those flows.
|
|
|
|
## Account Center: overview
|
|
|
|
**Page:** `/account` — guarded by server-side account layout.
|
|
- **Overview** sidebar link: returns here.
|
|
- Greeting: displays name from your OIDC session; falls back to email and then `there`.
|
|
- **Personal information** card -> **View profile** opens `/account/profile`.
|
|
- **Password & security** card -> **Security options** opens `/account/security`.
|
|
- **Review account details** text link -> `/account/profile`.
|
|
- Informational block explains one central identity can serve multiple apps; billing/product access is not controlled from this portal.
|
|
|
|
## Personal information
|
|
|
|
**Page:** `/account/profile`
|
|
- **Profile** sidebar link: opens this page.
|
|
- **Display name:** OIDC name claim if present, otherwise “Not provided”.
|
|
- **Email address:** OIDC email claim if present; read-only.
|
|
- **ZITADEL User ID:** immutable provider subject saved in the session; read-only. This is not an email address.
|
|
- **Open ZITADEL account settings:** links to the configured issuer `/ui/console/users/me`; actual availability requires the ZITADEL Console/policies and is **unverified**.
|
|
- **No Save/Edit/Delete buttons:** profile editing via a custom portal API is not implemented.
|
|
|
|
## Security settings
|
|
|
|
**Page:** `/account/security`
|
|
- **Security** sidebar link: opens this page.
|
|
- **Password:** descriptive row, not a local password editor.
|
|
- **Multi-factor authentication:** descriptive row, not an MFA enrollment/disable button.
|
|
- **Passkeys and security keys:** descriptive row, not a local passkey editor.
|
|
- **Open central security settings:** takes user to the same issuer-derived ZITADEL self-service location. Available controls depend on ZITADEL version, org policy and permissions.
|
|
- **No in-portal device sessions/revocation interface** exists at P04.
|
|
|
|
## Navigation, indicator and sign out
|
|
|
|
- **ZitPlane / Account Center** brand: navigates to `/account`.
|
|
- Sidebar: **Overview**, **Profile**, **Security** navigation.
|
|
- Identity tile: displays first character of name/email, name and email or generic fallback.
|
|
- **Signed in** status indicator: derived from the authenticated layout; do not treat it as an independent security-status check.
|
|
- **Sign out of portal:** submits Auth.js server action, clears the **portal-local** session and returns to `/signin`. **It does not promise global sign-out** from ZITADEL or other SaaS apps.
|
|
- Footer explains this portal's identity purpose.
|
|
- On narrow screens, navigation becomes a horizontal row and identity tile is hidden for space; sign-out remains accessible.
|
|
- Light/dark appearance follows operating system preference via CSS `prefers-color-scheme`; no manual theme switch button exists.
|
|
|
|
## Account API (for authorized integrations, not a user button)
|
|
|
|
`GET /api/account/me` is a protected, **read-only** endpoint in the Account Portal source:
|
|
- After a valid session: intended JSON `{ "user": { "id": "...", "name": "...", "email": "..." } }`, with nullable name/email and private/no-store.
|
|
- Without valid user ID: intended HTTP 401 `Unauthorized`.
|
|
- No endpoint to change password, update user fields or access administrative information is implemented in P04.
|
|
|
|
The behavior above has **not** been E2E verified. Do not rely on it in production before Gitea CI/staging acceptance.
|
|
|
|
## What to expect from official Login V2
|
|
|
|
Imported Login V2 source contains registration, password, verification, MFA/OTP, passkey, identity-provider, device and logout routes under `auth/ui/v2/apps/login/src/app/`. ZitPlane has **not** verified their external URL mappings, exact labels, working buttons or policy-dependent availability; do not infer enabled features from source folders. They are separate from this Account Portal.
|
|
|
|
## If a page does not open
|
|
|
|
This is expected until environment, OIDC client, dependencies, Docker integration, proxy and domains are configured in future approved phases. Consult [SETUP-GUIDE.md](SETUP-GUIDE.md), [FEATURES-STATUS.md](FEATURES-STATUS.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md). Do not share passwords or screenshots containing tokens.
|