5.9 KiB

Raw Blame History

Casdoor 单点登录 (SSO) 接入与二次开发实战指南

本文档基于当前项目代码库整理，旨在指导团队利用 Casdoor 构建统一身份认证中心，并进行必要的二次开发。

1. 方案可行性评估

Casdoor 是一个基于 Go (Golang) 和 React 的 UI-first 身份与访问管理 (IAM) / 单点登录 (SSO) 平台。经过代码审计，确认本项目主要特性如下：

1.1 支持的核心协议

Casdoor 原生支持所有主流的身份认证协议，足以满足绝大多数新老系统的接入需求：

OIDC (OpenID Connect) & OAuth 2.0: 现代 Web 应用的首选，支持最为完善。
SAML 2.0: 用于对接传统的企业级软件（如 Salesforce, ShowPad 等）。
CAS: 支持传统的 CAS 协议集成（特别是针对 Java 生态的老旧系统）。
RESTful API: 提供完整的管理 API。

1.2 成功案例参考

Casdoor 官方维护了大量的集成插件，可作为“成功案例”参考：

开发工具: GitLab, Jenkins, Grafana, Harbor
办公协作: OwnCloud, NextCloud
框架集成: Spring Boot, Django, Synology NAS
提示：如果不确定某个应用如何接入，可以搜索 "Casdoor + [应用名]"，通常都有现成的指引。

2. 快速启动与环境部署

在进行开发之前，请确保本地环境已准备就绪。

2.1 依赖环境

Go: 后端开发需要 (建议版本 1.18+)
Node.js & Yarn: 前端开发需要 (web/ 目录)
Docker & Docker Compose: 快速与预构建运行

2.2 启动项目

当前工作区包含便捷的构建脚本，可以直接使用：

方式一：使用 Docker (推荐) 使用项目根目录下的 PowerShell 脚本：

./run-prebuilt.ps1

该脚本会利用 docker-compose.prebuilt.yml 启动服务。
默认访问地址: http://localhost:8000 (具体端口视配置而定)
默认超管账号: admin / 123

方式二：源码启动 (开发调试)

后端:
```
go run main.go
```
前端:
```
cd web
yarn install
yarn start
```

3. 业务系统接入指南 (单点登录)

这是使用 Casdoor 的核心场景。无论您的“其他项目”是 Java, Go, Python 还是 Node.js 编写，流程基本一致。推荐使用标准的 OIDC 协议。

步骤 1: 创建应用 (Application)

以管理员身份登录 Casdoor 控制台。
进入 "Applications" (应用) 菜单。
点击 "Add"，填写基本信息：
- Name: 您的业务系统名称 (e.g., CRM-System)
- Organization: 选择所属组织 (默认 built-in)
- Redirect URLs: 极为关键！填写业务系统的回调地址，例如 http://your-app.com/callback。
保存后，您将获得 Client ID 和 Client Secret。

步骤 2: 代码集成

在您的业务系统中，通过 OIDC 流程获取用户信息。

流程简述:

重定向: 用户未登录时，将浏览器重定向到 Casdoor 登录页： http://CASDOOR_HOST/login/oauth/authorize?client_id=<Client_ID>&response_type=code&redirect_uri=<Redirect_URL>&scope=read&state=<Random_String>
回调 (Callback): 用户登录成功后，Casdoor 会跳回您配置的 Redirect URL，并附带一个 code 参数。
换取 Token: 您的后端服务使用 code + Client ID + Client Secret 向 Casdoor 请求 access_token。
解析 Token: 使用 SDK 或 JWT 库解析 Token，即可获得用户信息 (User Profile)。

步骤 3: 使用 SDK (推荐)

为了简化开发，可以直接使用官方 SDK。本项目 go.mod 中已引用 github.com/casdoor/casdoor-go-sdk。其他语言 SDK 请参考官方文档：

Java: casdoor-java-sdk
Node.js: casdoor-nodejs-sdk
Python: casdoor-python-sdk

4. 二次开发与扩展指南

如果是为了满足特定业务需求（如：自定义登录页、特殊的注册逻辑、对接已有用户库），请参考以下指引。

4.1 项目结构概览

conf/app.conf: 全局配置文件（数据库连接、端口、默认语言等）。
main.go: 程序入口。
routers/router.go: (核心) 后端路由定义文件。如果要新增 API 接口，从此文件入手。
controllers/: 业务逻辑控制器。
- auth.go: 处理登录、注册、退出相关的核心逻辑。
- oidc_discovery.go: OIDC 协议发现相关逻辑。
object/: 数据模型层 (ORM)。
- user.go: 用户数据结构定义。
- application.go: 应用配置模型。
web/: 前端 React 项目目录。

4.2 常见开发场景

场景 A: 修改登录页面 UI

登录页面的源码位于 web/src/auth/ 目录下。

web/src/auth/LoginPage.js: 登录页主入口。
web/src/App.js: 前端路由配置。修改完成后，需重新编译前端 (cd web && yarn build)，生成的静态文件会被嵌入到 Go 二进制文件中（或通过 Nginx 代理）。

场景 B: 增加自定义 API

在 controllers/ 下新建您的控制器文件，例如 my_feature.go。

在 routers/router.go 中注册路由：

// 添加到 API 路由组
beego.Router("/api/my-feature", &controllers.MyFeatureController{}, "get:GetData")

重新运行 main.go。

场景 C: 对接新的第三方登录源 (IdP)

Casdoor 已内置支持 Google, GitHub, WeChat, DingTalk 等几十种源。如果需要开发私有的身份源：

参考 object/provider.go 定义新的 Provider 类型。
在 idp/ 目录下实现该 Provider 的认证接口（实现 OAuth2 或相关逻辑）。

5. 有用资源链接

官方文档: https://casdoor.org (详细的配置说明)
Rest API 文档: Swagger UI (Demo)
问题排查: 查看 go-sdk 源码或本项目中的 *_test.go 文件通常能找到用法示例。

文档生成日期: 2026年2月11日

5.9 KiB Raw Blame History