#Session Security

5 min read

#Overview

When you sign in to the AiDial portal, Zitadel authenticates you through OIDC and the portal resolves your role, tenant, and project scope from aidial_api. The portal stores that context in a next-auth JWT session cookie. The browser-facing session only exposes the fields needed by the user interface; the access token is not returned through useSession() or browser JavaScript.

Browser code must not send X-API-Key. API keys are for trusted server-side integrations, not portal sessions. Browser requests go to portal pages or app/api/ route handlers, and the portal server forwards bearer tokens to aidial_api through the shared lib/aidial-api/ transport.

Page access and data access are checked server-side. Middleware covers non-API portal routes, while every app/api/** route handler must enforce its own auth, RBAC, CSRF, and tenant/project scope checks. Out-of-scope access resolves to non-enumerating denied states such as 404, /not-found, or /access-denied. Navigation visibility is only a convenience and is not a security boundary.

#Session Expiry

The portal registers sessions with aidial_api during sign-in, polls session state after hydration, and touches the session on user activity. The effective lifecycle policy comes from the backend session endpoints and includes idle timeout, absolute timeout, and the concurrent-session limit.

Your session can expire or be invalidated under these conditions:

  • Inactivity timeout — If you have not interacted with the portal for the effective idle period, your session can expire and you will be prompted to sign in again.
  • Absolute timeout — Regardless of activity, your session can expire after the effective maximum duration.
  • Concurrent-session eviction — If an older session is revoked because of the active-session limit, that browser is redirected to the access-denied state.
  • Manual revocation — If you or an authorised administrator revoke a session, that session is treated as no longer valid.

SessionMonitor calls GET /api/auth/session-state and redirects the browser when the backend reports a terminal lifecycle state. It also posts POST /api/auth/session-touch with the portal CSRF token on activity, using the backend debounce window to avoid excessive requests. If session validation is temporarily unavailable, the portal stays authenticated and shows a non-blocking degraded-state warning instead of forcing an immediate sign-out.

#Signing Out

All portal users can sign out at any time using the sign-out option in the portal.

The sign-out button posts to POST /api/auth/signout with the portal CSRF token. The route clears the current browser's session cookie, any observed chunked session-cookie names, and the CSRF cookie. It records a sign-out lifecycle audit event when the session context is available and returns Zitadel's OIDC end-session URL when an ID token is present. The client then redirects to that URL. If the identity-provider logout URL is unavailable, the current browser is still signed out locally.

Recovery links from session-ended states use GET /api/auth/force-signout to clear local session and CSRF cookies before returning to a safe sign-in path. When requested and an ID token is available, that recovery route can also hand off to Zitadel's OIDC end-session URL.

Signing out affects the current browser session. To end sessions on other devices, use the session revocation controls described below.

#Session Management in Settings

Customer roles (client_admin, client_manager, and client_staff) have access to the Active Sessions section in Settings at /settings?section=active-sessions:

  • View active sessions — See a list of your currently active sessions, including information about when and where each session was created.
  • Revoke individual sessions — End a specific non-current session (for example, a session left open on another device).
  • Sign out other devices — Revoke all sessions except your current one.

These features help you maintain control over your account security, especially if you suspect unauthorised access.

The current session is not revocable from the Settings panel; use the normal sign-out flow for the current browser.

#Session Revocation by Administrators

Client administrators (client_admin) can also view and revoke sessions for other users within their organisation from the Team surface. The Team table exposes Manage sessions only for client administrators, which opens /team/[userId]/sessions.

Revocation requests are CSRF-protected, rate-limited, and verified server-side. The team-management route verifies that the target session belongs to the target user before revoking it. Administrators cannot revoke their own sessions through the team-management route; they must use the normal sign-out or own-session controls.

#Partner Roles

Partner roles (partner_admin and partner_user) can sign out of the portal using the standard sign-out option. Partner roles do not have access to the Settings session-management surface. Partner roles cannot view active session lists, revoke individual sessions, or sign out other devices from the portal.

#Required Runtime Configuration

Session security depends on these required runtime environment variables. The portal code treats them as required and does not define fallback defaults:

  • NEXTAUTH_SECRET
  • NEXTAUTH_URL
  • AIDIAL_API_BASE_URL
  • AIDIAL_API_TIMEOUT_MS
  • ZITADEL_ISSUER
  • ZITADEL_CLIENT_ID
  • ZITADEL_CLIENT_SECRET

#Session Security Best Practices

  • Sign out when finished — Always sign out when you are done using the portal, especially on shared or public computers.
  • Review active sessions regularly — If you have session management access, periodically review your active sessions and revoke any you do not recognise.
  • Report suspicious activity — If you notice unfamiliar sessions or suspect unauthorised access, revoke them immediately and contact your administrator.
  • Enable MFA — Multi-factor authentication adds an extra layer of protection. Even if your password is compromised, MFA helps prevent unauthorised sign-in. See Multi-Factor Authentication.

#Next Steps