User Authentication & RBAC
Relevant source files
The following files were used as context for generating this wiki page:
Onyx employs a modular and secure approach to User Authentication and Role-Based Access Control (RBAC), designed to support both Community and Enterprise Edition (EE) requirements. The system integrates multiple authentication protocols, including OAuth2 and SAML, while enforcing strict document-level permissions that synchronize with external data sources.
The architecture ensures that sensitive company data remains protected by filtering search results and chat interactions based on the specific access levels of the authenticated user. This includes support for multi-tenant environments in the Enterprise Edition, where task isolation and tenant-aware scheduling are critical.
Authentication Mechanisms
Onyx supports several authentication types to accommodate different deployment environments. The backend is typically configured via the AUTH_TYPE environment variable.
Supported Auth Providers
- Basic Authentication: Often used for development or simple deployments. Users can log in with a username (e.g.,
a@example.com) and password. - OAuth2: Integrated for third-party providers such as GitHub, Google, and Slack.
- SAML: Supported for enterprise identity providers.
- Multi-Provider Support: The system allows for multiple providers to be active simultaneously.
Sources: AGENTS.md, CLAUDE.md, CONTRIBUTING.md:204-210
Authentication Workflow
The following diagram illustrates the high-level authentication flow within the Onyx ecosystem:
This diagram shows the interaction between the frontend, backend, and external providers during a typical authentication event.
Sources: AGENTS.md, CONTRIBUTING.md:204-210
Role-Based Access Control (RBAC)
Onyx implements RBAC through defined user roles and granular permissions. Access control is enforced at multiple levels: API endpoints, UI components, and the document index.
Key Roles
| Role | Description |
|---|---|
| Admin | Full access to system settings, connectors, and user management. |
| Global Curator | Permissions to manage specific resources like personas or document sets across the organization. |
| Basic/Worker User | Standard access to chat and search functionality within allowed scopes. |
Sources: AGENTS.md, backend/tests/integration/README.md
Document-Level Permissions
A core feature of the Onyx RBAC system is the Access Control List (ACL) synchronization. When documents are indexed from external sources (e.g., Google Drive, Confluence), Onyx preserves and respects the original source permissions.
- Source Permission Sync: Connectors fetch ACL data along with document content.
- Onyx ACL Storage: Permissions are stored as metadata in PostgreSQL and the Vespa vector database.
- Query-time Filtering: When a user performs a search or chat, the system automatically appends a filter to ensure the user only sees documents they are authorized to access.
This flow demonstrates how source permissions are integrated into the search pipeline to ensure data privacy.
Sources: web/tests/e2e/chat/chat_message_rendering.spec.ts:40-50, AGENTS.md
Tool-Level Authentication
For advanced features like "Actions" (OpenAPI tools), Onyx supports specific OAuth configurations. This allows AI assistants to perform actions on behalf of a user using authenticated third-party APIs.
Configuration Parameters
When adding an OpenAPI action, administrators must configure the following OAuth details:
- Authorization URL: The endpoint to redirect the user for authorization.
- Token URL: The endpoint to exchange authorization codes for access tokens.
- Client ID & Client Secret: Credentials provided by the third-party application.
- Scopes: Specific permissions requested from the third-party API (e.g.,
repo,user).
Sources: web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts:13-20
Security Implementation Details
API Security
- FastAPI Authentication: Backend endpoints use dependency injection to verify users.
- Cookie-based Sessions: The
fastapiusersauthcookie is typically used for session management. - Strict Typing: Both Python and TypeScript codebases enforce strict typing to prevent common security vulnerabilities.
- Parameterized Queries: Used throughout the SQLAlchemy implementation to prevent SQL injection.
Sources: AGENTS.md, web/README.md:35-45
Connector Credentials
Connectors store sensitive credentials (API keys, tokens) in an encrypted format within the relational database. Configuration forms are dynamically generated based on the connector type (e.g., web, github, google_drive).
Sources: web/src/lib/connectors/connectors.tsx:75-150, AGENTS.md
Conclusion
The Authentication and RBAC systems in Onyx provide a robust framework for securing enterprise knowledge. By combining standard web authentication protocols with deep integration into source-specific ACLs, Onyx ensures that AI-driven insights are delivered securely and only to authorized personnel. This system is critical for maintaining compliance and data integrity across various third-party integrations.