Enterprise SSO & SCIM
Relevant source files
The following files were used as context for generating this wiki page:
The Enterprise Edition (EE) of Onyx provides robust identity management and authentication features designed for large-scale organizational deployments. This system encompasses Single Sign-On (SSO) through multiple protocols—specifically OAuth2 and SAML—and automated user provisioning via the System for Cross-domain Identity Management (SCIM). These features ensure that user access is both secure and synchronized with an organization's central identity provider (IdP).
Enterprise SSO & SCIM components are primarily located within the backend/ee/ directory, reflecting their status as Enterprise Edition offerings. The architecture supports multi-provider authentication, allowing organizations to integrate with various IdPs while maintaining a consistent user experience and security posture.
Authentication Architecture
Onyx supports a multi-provider authentication model, integrating traditional OAuth2 flows alongside enterprise-grade SAML implementations. This flexibility allows the platform to act as a Service Provider (SP) that communicates with various Identity Providers.
OAuth2 Integration
The OAuth2 implementation handles authorization and authentication through external providers. The system manages the exchange of authorization codes for access tokens and retrieves user profile information to establish sessions within Onyx.
The diagram above illustrates the standard OAuth2 authorization code flow used for enterprise user authentication.
Sources: backend/ee/onyx/server/oauth/api.py, AGENTS.md:121-128, CLAUDE.md:121-128
SAML Implementation
The SAML module allows Onyx to integrate with enterprise identity providers like Okta, Microsoft Entra ID (Azure AD), or OneLogin. It handles the parsing of SAML assertions, signature verification, and the mapping of SAML attributes to Onyx user properties.
| Component | Description |
|---|---|
| Metadata | XML-based configuration shared between Onyx and the IdP to establish trust. |
| Assertion Consumer Service (ACS) | The endpoint in Onyx that receives and processes SAML responses from the IdP. |
| NameID | The unique identifier for the user provided by the SAML assertion. |
| Signature Validation | Verification of the IdP's digital signature to ensure the integrity of the auth response. |
Sources: backend/ee/onyx/server/saml.py
System for Cross-domain Identity Management (SCIM)
Onyx implements SCIM 2.0 to automate user and group lifecycle management. This allows external directory services to automatically create, update, and deactivate users in Onyx based on changes in the central directory.
SCIM Endpoints and Operations
The SCIM API provides standard RESTful endpoints for managing Users and Groups. This implementation follows the SCIM 2.0 specification, supporting operations such as GET (retrieval), POST (creation), PUT (full update), PATCH (partial update), and DELETE (deactivation).
Flow of user provisioning data from an IdP to the Onyx relational database via SCIM.
User Provisioning Logic
When an IdP sends a SCIM request, Onyx updates its internal user records. This includes synchronizing email addresses, display names, and active status. The system is designed to handle multi-tenant environments where SCIM tokens are specific to a particular organization or workspace.
Sources: backend/ee/onyx/server/scim/api.py, AGENTS.md:55-58, CLAUDE.md:55-58
Security and Configuration
The Enterprise SSO & SCIM systems rely on strictly typed configurations and secure credential handling.
Identity Configuration
SSO configurations are typically handled through environment variables and database-stored settings. These include:
- OAuth Client IDs and Secrets: Credentials for OAuth providers.
- SAML Entity IDs and Certificates: XML metadata and public keys for SAML trust.
- SCIM API Keys: Bearer tokens used by the IdP to authenticate requests to the SCIM endpoint.
Role-Based Access Control (RBAC)
The authentication system integrates with Onyx's RBAC patterns. Upon successful authentication or provisioning, users are assigned roles that define their permissions within the platform. SAML assertions can also be mapped to specific groups within Onyx to manage document-level permissions.
Sources: AGENTS.md:179-185, CLAUDE.md:179-185, CONTRIBUTING.md:465-470
Conclusion
Enterprise SSO and SCIM are critical for integrating Onyx into existing corporate IT infrastructures. By supporting both OAuth2 and SAML for authentication, alongside SCIM for automated provisioning, Onyx ensures that user management is seamless, secure, and scalable. These systems work in tandem with the core background workers to maintain synchronized permissions and access controls across the entire platform.