Casdoor项目API接口详解与使用指南
概述
Casdoor是一个基于OAuth 2.0、OIDC、SAML和CAS协议的开源身份认证与单点登录(SSO)平台。本文将通过分析其Swagger API文档，详细介绍Casdoor提供的各类API接口功能和使用方法，帮助开发者更好地集成和使用Casdoor。
核心API分类
Casdoor的API按照功能可以分为以下几大类：
1. OIDC相关API
Casdoor实现了标准的OIDC协议，提供以下关键端点：
/.well-known/jwks：获取JWK(JSON Web Key)集合，用于验证JWT签名/.well-known/openid-configuration：OIDC发现端点，返回服务配置信息
这些端点遵循OIDC规范，使Casdoor可以无缝集成到支持OIDC的客户端应用中。
2. 用户管理API
用户管理是身份系统的核心功能，Casdoor提供完整的用户CRUD操作：
POST /api/add-user：添加新用户POST /api/delete-user：删除用户POST /api/update-user：更新用户信息POST /api/check-user-password：验证用户密码
用户对象包含标准属性如用户名、密码、邮箱、手机号等，也支持自定义属性。
3. 应用管理API
应用(Application)代表需要接入Casdoor进行认证的客户端：
POST /api/add-application：注册新应用POST /api/delete-application：删除应用GET /api/get-applications：获取应用列表
每个应用可以配置不同的认证协议(OAuth2.0/OIDC/SAML等)、回调地址和权限范围。
4. 组织与权限API
Casdoor支持多租户架构，主要API包括：
组织管理：
POST /api/add-organization：创建新组织POST /api/delete-organization：删除组织
权限管理：
POST /api/add-permission：定义权限规则POST /api/batch-enforce：批量检查权限(基于Casbin)
权限模型遵循RBAC(基于角色的访问控制)或ABAC(基于属性的访问控制)。
5. 认证流程API
POST /api/Callback：处理OAuth回调POST /api/login：用户名密码登录POST /api/logout：注销会话
特色功能API
除了核心身份认证功能外，Casdoor还提供了一些特色功能的API：
1. LDAP集成
POST /api/add-ldap：配置LDAP服务器连接POST /api/delete-ldap：移除LDAP配置
2. 支付与订阅
POST /api/add-payment：创建支付记录POST /api/add-subscription：添加订阅计划POST /api/buy-product：购买产品
3. Webhook支持
POST /api/add-webhook：配置WebhookPOST /api/delete-webhook：删除Webhook
API响应格式
Casdoor的API遵循统一的响应格式：
{
"status": "success/error",
"msg": "操作结果描述",
"data": {...} // 实际返回数据
}
最佳实践
-
认证流程：建议使用OIDC协议，先调用发现端点获取配置，再使用标准OAuth2.0流程
-
错误处理：检查响应中的status字段，处理错误时参考msg中的描述
-
权限控制：利用batch-enforce接口在业务逻辑中实现细粒度权限控制
-
用户同步：通过syncer API实现与其他用户系统的数据同步
总结
Casdoor通过这套完整的API体系，为开发者提供了灵活的身份认证与访问控制解决方案。无论是简单的用户名密码认证，还是复杂的多租户SAML集成，都能通过这些API实现。建议开发者根据实际需求，选择合适的API组合来构建安全可靠的身份认证系统。
