Files

83 lines
6.2 KiB
Markdown
Raw Permalink Normal View History

# 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.