Your account and session
Deckgauge doesn't manage passwords itself — every identity is a Keycloak account. This page covers signing in, the user menu, what happens when your session expires, and the light/dark toggle.
The avatar menu in the top-right corner of the app shell.
What it does, and where the data comes from
Accounts live in Keycloak, not in Deckgauge's own database. The first time a Keycloak-issued JWT reaches the API, the auth middleware verifies it against Keycloak's signing keys and upserts a local User row keyed on the token's sub claim, filling in email and name from the token (apps/api/src/users/user.service.ts, upsertFromKeycloak). Every later request resolves to that same local user — nothing about your profile is edited from inside Deckgauge.
How to sign in and manage your session
- Continue with Keycloak — the login screen's primary button starts the standard OIDC sign-in flow against your realm (
apps/web/app/login/page.tsx). - Create an account — a second button on the same screen, and on the session-expired overlay, sends you to Keycloak's own self-registration form instead of the login form. It only works if your realm allows self-registration (see Access & security for how to turn that off).
- User menu — click your avatar (top right) to see your signed-in email and Sign out.
- Sign out — this clears more than Deckgauge's own session. It ends your Keycloak SSO session and sends your browser to Keycloak's logout endpoint, so the next sign-in shows the login/registration screen again instead of silently re-authenticating the same account.
- Theme toggle — the sun/moon icon flips the app between light and dark. It's a pure client-side preference: no account setting, no server round trip.
Under the hood
Deckgauge refreshes your Keycloak access token in the background before it expires, using the refresh token NextAuth already holds. If that refresh fails — the refresh token itself expired or was revoked in Keycloak — the next board API call that comes back unauthorized trips the session-expired overlay: a full-screen prompt that blocks the app until you sign in again. It offers the same two choices as the login screen, "Continue with Keycloak" and "Create an account", and once you're back in, whatever you were doing resumes.
The theme choice is stored in your browser's localStorage. In private/incognito windows where storage is blocked, the toggle still works for the current tab — it won't be remembered next time.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| The session-expired overlay appears often, even mid-session | Your Keycloak access-token lifespan is short relative to how long you leave a tab open, or refresh tokens are expiring | Ask your admin to review the realm's token lifespans in the Keycloak admin console, or sign in again — it's a one-click recovery |
| Signing out doesn't fully log you out — the next sign-in skips straight past the login screen | Keycloak still has an active SSO session in your browser | Use Sign out from the user menu (it performs the full logout, not a tab close), or clear cookies for your Keycloak domain |
| Theme reverts to light on every page load | The browser is blocking localStorage (private/incognito mode, or storage disabled) | Allow storage for the site, or accept the theme as session-only in that mode |
| "Create an account" doesn't show a registration form | Self-registration is disabled for this realm | Ask an admin to enable it in Keycloak, or have them add your account directly — see Access & security |
Related
- Access & security — board roles, self-registration, and how the JWT maps to permissions.
- Keycloak setup — configuring the identity provider itself.
- Workspace settings — what else lives under Settings.
Last updated