# 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 脚本：

```powershell
./run-prebuilt.ps1
```

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

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

1.  **后端**:
    ```bash
    go run main.go
    ```
2.  **前端**:
    ```bash
    cd web
    yarn install
    yarn start
    ```

---

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

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

### 步骤 1: 创建应用 (Application)

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

### 步骤 2: 代码集成

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

**流程简述**:

1.  **重定向**: 用户未登录时，将浏览器重定向到 Casdoor 登录页：
    `http://CASDOOR_HOST/login/oauth/authorize?client_id=<Client_ID>&response_type=code&redirect_uri=<Redirect_URL>&scope=read&state=<Random_String>`
2.  **回调 (Callback)**: 用户登录成功后，Casdoor 会跳回您配置的 `Redirect URL`，并附带一个 `code` 参数。
3.  **换取 Token**: 您的后端服务使用 `code` + `Client ID` + `Client Secret` 向 Casdoor 请求 `access_token`。
4.  **解析 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

1.  在 `controllers/` 下新建您的控制器文件，例如 `my_feature.go`。
2.  在 `routers/router.go` 中注册路由：
    ```go
    // 添加到 API 路由组
    beego.Router("/api/my-feature", &controllers.MyFeatureController{}, "get:GetData")
    ```
3.  重新运行 `main.go`。

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

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

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

---

## 5. 有用资源链接

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

---

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