Casdoor Public API
Relevant source files
The following files were used as context for generating this wiki page:
The Casdoor Public API is a comprehensive RESTful interface that facilitates Identity and Access Management (IAM) and Single Sign-On (SSO) capabilities. It provides endpoints for managing users, organizations, applications, and permissions, while supporting multiple standard protocols including OAuth 2.1, OIDC, SAML, and CAS.
Sources: README.md:2, swagger/swagger.yml:1-10
API Architecture and Protocols
Casdoor acts as a centralized authentication server. Its API is structured around the ApiController for general administrative and user operations, and the RootController for protocol-specific discovery and validation endpoints.
Supported Protocols
The API architecture supports several industry-standard protocols:
- OIDC/OAuth 2.1: Discovery and token management.
- SAML: XML-based identity provider services.
- CAS: Service and proxy validation.
- SCIM: System for Cross-domain Identity Management.
Sources: routers/router.go:27-46, swagger/swagger.yml:15-104
Request Authentication
Most administrative APIs require an AccessToken provided in the Authorization header as a Bearer token.
The diagram shows the high-level authentication flow for API requests.
Sources: swagger/swagger.yml:1467-1471, idp/casdoor.go:103-110
Authentication and Authorization Endpoints
These endpoints manage the core identity lifecycle, from sign-up and login to token introspection and MFA setup.
Core Auth Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/signup | POST | Register a new user account. |
/api/login | POST | Authenticate a user and initiate a session. |
/api/login/oauth/access_token | POST | Exchange an authorization code for an access token. |
/api/login/oauth/introspect | POST | Check the validity and metadata of a token. |
/api/mfa/setup/initiate | POST | Start the Multi-Factor Authentication setup process. |
Sources: swagger/swagger.yml:1044-1135, routers/router.go:42-53
OAuth 2.0 / OIDC Flow
The following sequence illustrates a standard authorization code exchange using the Casdoor API.
The sequence diagram details the standard OAuth 2.0 flow implemented by the API.
Sources: swagger/swagger.json:1108-1150, idp/casdoor.go:57-86
Resource Management APIs
Casdoor provides a vast array of CRUD (Create, Read, Update, Delete) operations for managing IAM entities.
Organization and Application Management
Organizations act as the top-level container for users and applications.
| Feature | Create Endpoint | Read Endpoint | Update Endpoint |
|---|---|---|---|
| Organization | /api/add-organization | /api/get-organization | /api/update-organization |
| Application | /api/add-application | /api/get-application | /api/update-application |
| Group | /api/add-group | /api/get-group | /api/update-group |
Sources: swagger/swagger.yml:130-155, routers/router.go:61-75
User and Permission Management
Casdoor integrates Casbin for fine-grained access control.
The class diagram shows the relationship between users, roles, and permissions as defined in the API data structures.
Sources: swagger/swagger.yml:1330-1430, swagger/swagger.json:1165-1198
Data Models
The API uses standardized JSON objects for requests and responses. Key structures include:
User Object (object.User)
Contains comprehensive profile information, third-party ID links, and security settings.
owner: The organization name.name: Unique username within the organization.id: UUID.isOnline: Current session status.mfaEmailEnabled/mfaPhoneEnabled: MFA configurations.
Sources: swagger/swagger.yml:1330-1420
Response Wrapper (controllers.Response)
Most API endpoints return a consistent response format.
{
"status": "ok",
"msg": "success",
"data": "...",
"data2": "...",
"data3": "..."
}
Sources: swagger/swagger.yml:955-985
System and Diagnostic APIs
For monitoring and maintenance, the API exposes several diagnostic endpoints.
- Health Check:
GET /api/healthreturns the live status of the system. - System Info:
GET /api/get-system-infoprovides CPU and memory usage statistics. - Prometheus Metrics:
GET /api/metricsexports metrics for monitoring systems. - Version Info:
GET /api/get-version-inforeturns the release version and commit ID.
Sources: swagger/swagger.yml:857-867, routers/router.go:174-178
Conclusion
The Casdoor Public API provides a robust and protocol-agnostic framework for identity management. By strictly adhering to REST principles and supporting multiple SSO standards, it allows developers to integrate complex authentication and authorization logic into their applications with minimal overhead.