Backend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Casdoor is an open-source, AI-first Identity and Access Management (IAM) and authentication server. Its backend is designed to support a wide array of protocols including OAuth 2.1, OIDC, SAML, CAS, LDAP, and SCIM. It functions as both an authentication provider and an AI MCP (Model Context Protocol) gateway, facilitating secure identity management and access control for modern applications.
The backend provides a comprehensive RESTful API that powers the web UI and external integrations. It handles complex workflows such as multi-factor authentication (MFA), user synchronization from external databases or directories, and event-driven notifications via webhooks.
Sources: README.md:1-5, swagger/swagger.yml:1-15
API Layer and Routing
The backend architecture is centered around a RESTful API organized into specialized controllers. These controllers handle requests for different entities like Users, Organizations, Applications, and Permissions. The API is documented using Swagger, providing a structured interface for frontend and third-party interactions.
API Categories and Endpoints
The API is categorized into functional groups, each managing a specific aspect of the IAM system:
| API Category | Description | Key Endpoints |
|---|---|---|
| Account API | Handles user profile and account details. | /api/get-account, /api/set-password |
| Login API | Manages authentication flows (OAuth, OIDC, SAML). | /api/login, /api/logout, /api/signup |
| User API | CRUD operations and specialized user management. | /api/get-users, /api/update-user, /api/add-user |
| Enforcer API | Interfaces with Casbin for policy enforcement. | /api/enforce, /api/batch-enforce, /api/get-policies |
| System API | Provides health checks and system telemetry. | /api/health, /api/get-system-info, /api/get-prometheus-info |
Sources: swagger/swagger.yml:25-1000
Request Flow
The following diagram illustrates the typical request flow from a client to the backend services.
Authentication and Protocol Support
Casdoor implements multiple industry-standard protocols. The backend handles the translation between these protocols and the internal data models.
OIDC and OAuth 2.0
The system provides OIDC discovery and JWKS endpoints for secure token verification. It supports various grant types including authorization_code, password, client_credentials, and refresh_token.
| Endpoint | Protocol | Purpose |
|---|---|---|
/.well-known/openid-configuration | OIDC | Discovery of provider capabilities. |
/.well-known/jwks | OIDC/OAuth | Public keys for JWT signature validation. |
/api/login/oauth/access_token | OAuth 2.0 | Token exchange. |
Sources: swagger/swagger.yml:15-100, web/src/ApplicationEditPage.js:520-560
SAML and CAS
For enterprise integrations, Casdoor supports SAML 2.0 with metadata export and POST binding capabilities. It also supports the CAS (Central Authentication Service) protocol.
Sources: web/src/ApplicationEditPage.js:630-700, README.md:1-5
Data Synchronization and External Integration
Casdoor features a "Syncer" system and LDAP integration to bridge the gap between Casdoor's internal user store and external data sources.
Syncer Architecture
Syncers allow the backend to periodically pull user data from external databases (MySQL, PostgreSQL, etc.) or platforms like Keycloak, Okta, and Google Workspace.
Webhooks
The backend includes an event-driven system where specific actions (e.g., signup, login, update-user) trigger POST requests to external URLs. This allows for real-time integration with third-party systems.
| Field | Type | Description |
|---|---|---|
events | []string | API paths or actions that trigger the webhook. |
method | string | HTTP method (POST, GET, PUT, DELETE). |
contentType | string | application/json or application/x-www-form-urlencoded. |
Sources: web/src/WebhookEditPage.js:150-220
System Monitoring and Telemetry
The backend exposes internal metrics and system information, often used for performance monitoring and debugging.
- System Info: Real-time CPU and Memory usage tracking.
- Prometheus Integration: Metrics endpoint (
/api/metrics) and detailed API latency/throughput data. - Audit Logs (Records): Every API request can be recorded as an audit entry, capturing the client IP, request URI, status code, and the object being modified.
Sources: web/src/SystemInfo.js:30-60, web/src/RecordListPage.js:25-100, swagger/swagger.yml:1100-1150
Summary
The Casdoor backend architecture is a modular IAM solution that prioritizes protocol flexibility and extensibility. By combining a rich RESTful API with specialized subsystems like Syncers for data migration and Webhooks for event handling, it provides a centralized platform for managing identities across diverse application landscapes. Integration with Casbin ensures that complex authorization logic is handled efficiently alongside core authentication tasks.
Sources: README.md, swagger/swagger.yml