Casdoor 接入契约：MCP、OAuth/OIDC、SAML、SCIM 和 API 怎样分工

Casdoor 的接入工作不应从“先把登录页接上”开始，而应从协议契约开始。一个企业里同时存在浏览器用户、内部服务、AI Agent、MCP 工具、遗留系统、目录同步和外部 SaaS。每个接入面都需要不同协议：OIDC 负责现代登录，SAML 负责企业联合身份，LDAP/CAS 处理遗留系统，SCIM 处理用户生命周期，REST API/SDK 处理管理自动化，MCP gateway 则把 Agent 工具调用纳入身份边界。

官方仓库 casdoor/casdoor 以 Go 为主，React 前端，Apache-2.0 许可证，默认分支 master。研究时最新 release 是 v3.121.0（2026-07-21）。go.mod 使用 Go 1.25.0 和 toolchain go1.25.8，并包含 Beego、Casbin、MCP Go SDK 等关键依赖。项目官方描述强调 Agent-first IAM、LLM MCP & agent gateway、auth server with web UI。

OIDC：默认给新应用

新建 Web、移动端和内部控制台，优先使用 OIDC。它提供标准 discovery、authorization code flow、ID token、access token、refresh token 和 claims。接入时不要只确认 callback 成功，还要确认 issuer、audience、redirect_uri、PKCE、scope、token 过期时间和 logout 行为。

OIDC_ISSUER=https://iam.example.com
OIDC_CLIENT_ID=internal-console
OIDC_REDIRECT_URI=https://console.example.com/auth/callback
OIDC_SCOPES="openid profile email groups"

SAML、CAS、LDAP：为了兼容，不是为了扩大复杂度

SAML 适合企业 IdP 或老牌 SaaS 集成；CAS 常见于校园和遗留 Java 系统；LDAP 常用于目录查询与旧系统认证。它们有价值，但不应把新系统也强行拖回旧协议。每新增一个协议入口，都要明确证书轮换、断言有效期、属性映射、组同步和注销语义。

SCIM：人员生命周期要自动化

手工创建和删除账号迟早会失败。SCIM 应承担用户、组、组织关系的同步任务。对于离职、转岗、供应商账号、临时项目组，SCIM 比人工后台操作更可靠。生产接入时要给 SCIM token 独立权限、独立轮换周期和独立审计，不要复用管理员 token。

MCP 与 Agent：工具授权必须显式

Casdoor 的 Agent-first IAM 定位让 MCP 工具接入成为重点。Agent 调用 MCP server 时，不应拿到一个“万能内部网络通行证”。工具应按 scope、组织、资源和动作授权：读取文档、查询订单、创建工单、修改配置、发起部署，风险完全不同。

{
  "agent": "research-bot",
  "org": "acme",
  "scopes": ["mcp:docs:read", "api:tickets:create"],
  "ttl": "15m",
  "policy": "deny-write-unless-approved"
}

REST API、SDK、Swagger：管理面不是业务面

Casdoor 提供 REST API、SDK 和 Swagger，适合内部平台做自动化，例如创建应用、查询用户、同步组织、读取 provider 配置。但管理 API 和业务 API 要分开授权，不能让业务服务拿到全局 IAM 管理权限。所有自动化调用都应写入审计，并对失败、重试、幂等和速率限制有明确策略。

契约结论

Casdoor 的强项是协议覆盖广，但协议越多越需要分工。OIDC 做新应用登录，SAML/LDAP/CAS 做兼容，SCIM 做生命周期，MCP 做 Agent 工具授权，REST/SDK 做管理自动化。这样接入，身份系统才不会变成一个“什么都能接、什么都说不清”的黑盒。