Console Authentication Flow
The authentication flow for the web console is primarily handled by thepalyrad daemon’s admin HTTP transport layer. Access to the console requires an admin:* principal crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#31-35.
1. Login & Session Issuance
Theconsole_login_handler processes login requests. It validates the provided principal and device ID, then verifies the Authorization bearer token if the daemon is configured to require authentication crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-88. Upon successful validation, the daemon:
- Mints a new session token and a CSRF token crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#101-101.
- Sets a
Set-Cookieheader containing the session token. The cookie is markedSecureif the request used TLS crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#103-106. - Returns a
ConsoleSessionResponsecontaining thecsrf_token,principal, and expiration timestamps crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#107-110.
2. Desktop Handoff
To support moving from the Desktop app to a full browser window without re-authenticating, Palyra uses a “handoff token” mechanism:- Token Generation: The
console_browser_handoff_handlercreates a short-lived (60s)ConsoleBrowserHandoffrecord linked to the current session’s context crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159. - Consumption: The browser navigates to a bootstrap URL with the token. The
console_browser_bootstrap_handlervalidates the token, issues a standard session cookie, and redirects the user to the console UI crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#161-175.
Web Console Auth Sequence
This diagram illustrates the transition from an unauthenticated state to a session established via Desktop Handoff. Sources: crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-175, apps/web/src/App.test.tsx#69-107ConsoleApiClient Internals
TheConsoleApiClient in apps/web/src/consoleApi.ts is the central gateway for all frontend communication with the daemon. It manages session state and enforces security protocols.
CSRF Protection
The client implements a “fail-closed” CSRF strategy for mutating requests (POST, PUT, DELETE, PATCH):- Token Storage: The CSRF token is retrieved during
login()orgetSession()and stored in memory apps/web/src/consoleApi.test.ts#44-72. - Enforcement: For mutating methods, the client attaches the token to the
x-palyra-csrf-tokenheader apps/web/src/consoleApi.test.ts#86-89. If a mutating request is attempted without a token, the client throws a “Missing CSRF token” error before the request is even dispatched apps/web/src/consoleApi.test.ts#92-106.
Request Lifecycle
The client uses the browserfetch API. It includes credentials: "include" on all requests to ensure the session cookie is transmitted apps/web/src/consoleApi.test.ts#89-89.
| Feature | Implementation |
|---|---|
| Session Refresh | getSession() retries on 429 (rate limit) before falling back to login apps/web/src/App.test.tsx#38-67. |
| Timeout | Handled via AbortController (defaults vary by endpoint). |
| Error Handling | Throws ControlPlaneApiError containing category and retryability info apps/web/src/consoleApi.test.ts#3-8. |
Model Provider Auth (OpenAI/Anthropic)
Palyra supports authenticating with LLM providers via API Keys or OAuth. These credentials are never stored in the clear in the main configuration; instead, they are placed in the Vault.API Key Flow
When an operator adds an OpenAI or Anthropic API key:- Validation: The daemon performs a “live probe” against the provider’s models endpoint (e.g.,
/v1/modelsfor OpenAI) to verify the key before saving crates/palyra-daemon/src/openai_surface.rs#34-40. - Vault Storage: The key is stored in the
Vaultusing a scoped reference (e.g.,openai/api_key/[profile_id]) crates/palyra-daemon/src/openai_surface.rs#42-48. - Profile Creation: An
AuthProfileViewis created containing the vault reference, not the raw key crates/palyra-daemon/src/openai_surface.rs#49-60.
OpenAI OAuth Callback
For OpenAI OAuth, the daemon manages a multi-step bootstrap:- Bootstrap: The operator starts the flow, and the daemon returns a
bootstrap_urlto the OpenAI authorization server crates/palyra-daemon/src/openai_surface.rs#144-188. - Callback: OpenAI redirects to
console/v1/auth/providers/openai/callbackcrates/palyra-daemon/src/openai_surface.rs#15-15. - State Polling: The Web UI opens a popup and polls the daemon for the completion of the OAuth exchange apps/web/src/console/hooks/useAuthDomain.ts#15-17.
Provider Auth Code Entities
This diagram maps the UI concepts to the backend implementation functions. Sources: apps/web/src/console/sections/AuthSection.tsx#62-111, crates/palyra-daemon/src/openai_surface.rs#18-78, crates/palyra-daemon/tests/openai_auth_surface.rs#29-105AuthSection UI
TheAuthSection provides the operator interface for managing identities and provider connections.
Key Components
- Profile Inventory: A
WorkspaceTabledisplaying all configured profiles, their provider kind, scope (global vs. agent-specific), and current health state apps/web/src/console/sections/AuthSection.tsx#158-185. - Health Monitoring: Summarizes profiles into “Healthy”, “Expiring”, “Expired”, or “Missing” based on background probes apps/web/src/console/sections/AuthSection.tsx#120-131.
- Connection Forms: Contains the
AuthApiKeyDraftandAuthOAuthDraftforms for adding new credentials apps/web/src/console/hooks/useAuthDomain.ts#28-46.
Security Posture
The UI enforces redaction. Sensitive values like API keys or vault references are wrapped inWorkspaceRedactedValue components or kept only in the daemon’s memory until explicitly requested via a “reveal” action apps/web/src/console/sections/AuthSection.tsx#19-20, crates/palyra-daemon/tests/openai_auth_surface.rs#101-104.
Sources: apps/web/src/console/sections/AuthSection.tsx#84-144, apps/web/src/console/hooks/useAuthDomain.ts#48-68