Authentication and Session Management
Authentication in Palyra is handled primarily by thepalyra-auth crate, which manages credentials, profiles, and session lifecycles.
Auth Profiles and Registry
TheAuthProfileRegistry is the central authority for managing authentication profiles. A profile contains credentials (API keys or OAuth tokens) scoped to either a global level or a specific agent crates/palyra-auth/src/lib.rs#10-21.
- AuthCredential: Supports
ApiKey(stored via vault reference) andOauth(access/refresh tokens) crates/palyra-auth/src/models.rs#10-16. - AuthProfileScope: Defines whether a credential is
Globalor tied to a specificAgentcrates/palyra-auth/src/models.rs#10-16.
Console Sessions and CSRF Protection
The Web Console uses a session-based authentication model. When a user logs in, the daemon issues aConsoleSession which includes a principal and a csrf_token crates/palyra-control-plane/src/models.rs#8-16.
- CSRF Protection: Every mutating request from the web console must include the
x-palyra-csrf-tokenheader apps/web/src/App.config-access-support.test.tsx#55-56. - Principal Binding: Admin operations are restricted to principals bound via the
PALYRA_ADMIN_BOUND_PRINCIPALenvironment variable crates/palyra-daemon/tests/openai_auth_surface.rs#35-36.
OAuth2 and OpenAI Integration
Palyra implements a specialized OAuth2 flow for OpenAI, allowing users to authenticate via the OpenAI dashboard and refresh tokens automatically.OAuth Refresh Mechanism
Thepalyra-auth crate provides an OAuthRefreshAdapter to handle background token rotation crates/palyra-auth/src/refresh.rs#17-20.
- Backoff Policy: Uses
ProviderBackoffPolicyto handle rate limits and provider downtime during refresh attempts crates/palyra-auth/src/refresh.rs#18-19. - Vault Integration: Refresh tokens are never stored in plain text; they are persisted as vault references crates/palyra-daemon/tests/openai_auth_surface.rs#92-96.
OpenAI Auth Surface
The daemon exposes specific endpoints for OpenAI integration:- API Key Flow: Allows manual entry of
sk-...keys, which are immediately validated againsthttps://api.openai.com/v1/modelscrates/palyra-daemon/src/openai_auth.rs#189-195. - OAuth Flow: Implements PKCE (Proof Key for Code Exchange) with
generate_pkce_verifierandpkce_challengecrates/palyra-daemon/src/openai_auth.rs#99-107.
Access Control and RBAC
Palyra implements a robust Access Control system via theAccessRegistry, supporting Feature Flags, API Tokens, and Workspace-level RBAC.
Access Registry
TheAccessRegistry is persisted in access_registry.json and manages the following entities crates/palyra-daemon/src/access_control.rs#13-22:
- Feature Flags: Controls access to subsystems like
compat_api,rbac, andapi_tokens. - API Tokens: Used for programmatic access (e.g., OpenAI-compatible endpoints). Tokens have a
token_hash_sha256for secure verification crates/palyra-daemon/src/access_control.rs#151-173.
Role-Based Access Control (RBAC)
The system defines three primaryWorkspaceRole levels crates/palyra-daemon/src/access_control.rs#76-80:
| Role | Permissions |
|---|---|
| Owner | Full access including trust.operate, rollout.manage, and workspace.manage. |
| Admin | api_tokens.manage, membership.manage, and sharing.manage. |
| Operator | sessions.use, memory.use, routines.use, and observability.read. |
Principal Binding
Requests are authorized based on theprincipal string.
- Compat API: Uses
authorize_compat_api_tokento verify theAuthorization: Bearertoken against the registry crates/palyra-daemon/src/transport/http/handlers/compat.rs#110. - Rate Limiting: Enforced per-token via
enforce_compat_rate_limitcrates/palyra-daemon/src/transport/http/handlers/compat.rs#111.
Secrets Management
Secrets (API keys, OAuth tokens) are managed via theVault and the palyra secrets CLI.
- Storage: Secrets are stored in the vault with a specific
VaultScope(Global or Agent) crates/palyra-cli/src/commands/secrets.rs#66-67. - Redaction: The system implements “Default Redaction.” Secrets are masked in the UI unless an “Explicit Reveal” is triggered by the operator apps/web/src/App.config-access-support.test.tsx#137-142.
- Auditing: The
SecretsCommand::Auditfunction scans configurations for unresolved secret references and potential leaks crates/palyra-cli/src/commands/secrets.rs#147-155.