416 lines
15 KiB
Markdown
416 lines
15 KiB
Markdown
---
|
||
name: pku-iaaa
|
||
description: |
|
||
Integrate Peking University (PKU) IAAA unified authentication system into web applications.
|
||
Use this skill whenever the user wants to implement PKU IAAA SSO login, PKU unified identity
|
||
authentication, or connect their app to iaaa.pku.edu.cn. Also trigger when the user mentions
|
||
"北大统一认证", "IAAA认证", "北大SSO", "PKU login", or wants to add campus authentication
|
||
for a Peking University application. Covers login redirect, token validation, proxy SSO,
|
||
and account verification — for any web framework (Django, Spring Boot, Express.js, Flask, etc).
|
||
---
|
||
|
||
# 北京大学 IAAA 统一身份认证集成
|
||
|
||
本 skill 指导你将北京大学 IAAA（统一安全系统）身份认证集成到任意 Web 应用中。
|
||
|
||
## 前置条件
|
||
|
||
集成前需在 IAAA 注册应用系统，准备以下信息：
|
||
- **应用系统 ID**（`appId`）：英文字母开头，可含数字
|
||
- **Key**：由 IAAA 提供，用于生成消息摘要
|
||
- **服务器 IP 地址**：应用系统所在服务器的 IP
|
||
- **回调地址 URL**（`redirectUrl`）：用于接收 token 的回调端点
|
||
|
||
申请方式：管理部门用户登录校内门户 → "信息服务"或"办事大厅" → 搜索"统一身份认证应用备案申请"。
|
||
注册后可在 `https://i3a.pku.edu.cn/iaaa/index.jsp` 自行管理服务器 IP 和回调 URL。
|
||
|
||
## 开始集成前，先确认需求
|
||
|
||
在动手写代码之前，先向用户确认：
|
||
|
||
1. **使用什么框架？** （Django / Spring Boot / Express.js / Flask / 其他）
|
||
2. **需要哪种级别的集成？**
|
||
- 基本认证（登录跳转 + Token 验证）— 绝大多数场景只需这个
|
||
- 代理 SSO（中心应用 + 分支应用架构）— 参见 `references/proxy-sso.md`
|
||
- 账号验证（仅校验某个学号/职工号是否存在）— 参见 `references/account-verify.md`
|
||
3. **系统是否还有非校内账号？** 如果是，需要同时保留自有登录入口（影响前端跳转参数）
|
||
|
||
## 认证流程概览
|
||
|
||
```
|
||
用户点击登录 ──POST──> iaaa.pku.edu.cn/iaaa/oauth.jsp
|
||
│
|
||
用户输入账号密码认证
|
||
│
|
||
认证成功，生成 token
|
||
│
|
||
302 重定向到 redirectUrl?token=xxx
|
||
│
|
||
应用服务端收到 token
|
||
│
|
||
服务端调用 validate.do 验证 token
|
||
│
|
||
验证成功，获取用户信息（identityId 等）
|
||
│
|
||
匹配本地用户，创建会话
|
||
```
|
||
|
||
## 第一步：登录跳转（前端）
|
||
|
||
用户点击登录时，通过 POST 表单跳转到 IAAA 统一登录页面。
|
||
|
||
### 关键参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `appID` | 注册的应用系统 ID |
|
||
| `redirectUrl` | 回调地址（验证 token 的端点），若含参数需 URLEncode |
|
||
| `redirectLogonUrl` | （可选）应用自有登录地址，当系统还有非校内账号时使用 |
|
||
|
||
### 实现要点
|
||
|
||
- 必须使用 POST 方法提交表单到 `https://iaaa.pku.edu.cn/iaaa/oauth.jsp`
|
||
- `redirectUrl` 的协议必须与实际部署一致（从当前请求动态获取，不要硬编码 `http://`）
|
||
- 回调 URL 的尾部斜杠很重要——IAAA 可能因缺少尾部斜杠而拒绝回调
|
||
|
||
### 参考实现（JavaScript 前端通用）
|
||
|
||
```javascript
|
||
function redirectToIAAALogin(appID, callbackPath, loginPath) {
|
||
const form = document.createElement('form');
|
||
form.action = 'https://iaaa.pku.edu.cn/iaaa/oauth.jsp';
|
||
form.method = 'POST';
|
||
form.style.display = 'none';
|
||
|
||
function addField(name, value) {
|
||
const input = document.createElement('input');
|
||
input.type = 'hidden';
|
||
input.name = name;
|
||
input.value = value;
|
||
form.appendChild(input);
|
||
}
|
||
|
||
// 使用当前页面协议，不要硬编码 http://
|
||
const baseUrl = `${location.protocol}//${location.host}`;
|
||
addField('appID', appID);
|
||
addField('redirectUrl', `${baseUrl}${callbackPath}`);
|
||
if (loginPath) {
|
||
addField('redirectLogonUrl', `${baseUrl}${loginPath}`);
|
||
}
|
||
|
||
document.body.appendChild(form);
|
||
form.submit();
|
||
}
|
||
```
|
||
|
||
## 第二步：Token 验证（服务端）
|
||
|
||
IAAA 认证成功后，会重定向浏览器到 `redirectUrl?token=<TOKEN>`。服务端需要验证这个 token。
|
||
|
||
### 验证端点
|
||
|
||
```
|
||
GET https://iaaa.pku.edu.cn/iaaa/svc/token/validate.do
|
||
?remoteAddr={REMOTE_ADDR}
|
||
&appId={APP_ID}
|
||
&token={TOKEN}
|
||
&msgAbs={MSG_ABS}
|
||
```
|
||
|
||
如果不需要返回用户详细信息（只需 identityId），可使用简单验证端点：
|
||
```
|
||
GET https://iaaa.pku.edu.cn/iaaa/svc/token/validateSimple.do?...（参数相同）
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `remoteAddr` | 访问应用系统的用户**真实 IP 地址** |
|
||
| `appId` | 应用系统 ID |
|
||
| `token` | IAAA 传回的票据 |
|
||
| `msgAbs` | MD5 消息摘要（见下方计算方法） |
|
||
|
||
### msgAbs 计算方法（极其重要）
|
||
|
||
1. 取除 `msgAbs` 以外的所有请求参数
|
||
2. 按**参数名升序**排列
|
||
3. 拼接为查询字符串格式：`appId={APP_ID}&remoteAddr={REMOTE_ADDR}&token={TOKEN}`
|
||
4. 将此字符串与 Key 直接拼接（不加分隔符）：`PARA_STR + Key`
|
||
5. 对拼接结果计算 MD5（UTF-8 编码，32 位十六进制，大小写不敏感）
|
||
|
||
**Python 示例：**
|
||
```python
|
||
import hashlib
|
||
|
||
para_str = f"appId={app_id}&remoteAddr={remote_addr}&token={token}"
|
||
raw = para_str + key
|
||
msg_abs = hashlib.md5(raw.encode('utf-8')).hexdigest()
|
||
```
|
||
|
||
**Java 示例：**
|
||
```java
|
||
String paraStr = "appId=" + appId + "&remoteAddr=" + remoteAddr + "&token=" + token;
|
||
String raw = paraStr + key;
|
||
MessageDigest md = MessageDigest.getInstance("MD5");
|
||
byte[] digest = md.digest(raw.getBytes(StandardCharsets.UTF_8));
|
||
String msgAbs = String.format("%032x", new BigInteger(1, digest));
|
||
```
|
||
|
||
**Node.js 示例：**
|
||
```javascript
|
||
const crypto = require('crypto');
|
||
const paraStr = `appId=${appId}&remoteAddr=${remoteAddr}&token=${token}`;
|
||
const msgAbs = crypto.createHash('md5').update(paraStr + key).digest('hex');
|
||
```
|
||
|
||
### 获取客户端真实 IP
|
||
|
||
反向代理（Nginx 等）环境下，客户端 IP 通常在 `X-Forwarded-For` 头中。取第一个值（最左侧）作为真实 IP：
|
||
|
||
```python
|
||
# Python / Django
|
||
remote_addr = request.META.get('HTTP_X_FORWARDED_FOR', '').split(',')[0].strip() \
|
||
or request.META.get('REMOTE_ADDR', '')
|
||
```
|
||
|
||
```java
|
||
// Java / Spring Boot
|
||
String remoteAddr = request.getHeader("X-Forwarded-For");
|
||
if (remoteAddr != null && !remoteAddr.isEmpty()) {
|
||
remoteAddr = remoteAddr.split(",")[0].trim();
|
||
} else {
|
||
remoteAddr = request.getRemoteAddr();
|
||
}
|
||
```
|
||
|
||
```javascript
|
||
// Node.js / Express
|
||
const remoteAddr = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
|
||
|| req.socket.remoteAddress;
|
||
```
|
||
|
||
### 返回结果
|
||
|
||
**成功：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"errCode": "0",
|
||
"errMsg": "认证成功",
|
||
"userInfo": {
|
||
"name": "用户姓名",
|
||
"status": "账号状态（开通/禁止）",
|
||
"identityId": "身份账号（学号/职工号）",
|
||
"deptId": "所在院系码",
|
||
"dept": "所在院系",
|
||
"identityType": "身份类别（学生/职工）",
|
||
"detailType": "身份细类",
|
||
"identityStatus": "身份状态（在校/减离）",
|
||
"campus": "校区"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"errCode": "错误码",
|
||
"errMsg": "错误信息"
|
||
}
|
||
```
|
||
|
||
简单验证端点（`validateSimple.do`）成功时 `userInfo` 中只包含 `identityId`。
|
||
|
||
### 服务端验证的完整参考实现
|
||
|
||
#### Django
|
||
|
||
```python
|
||
import hashlib
|
||
import logging
|
||
import requests
|
||
from django.contrib.auth import login, get_user_model
|
||
from django.http import HttpResponseRedirect
|
||
from django.shortcuts import render, reverse
|
||
|
||
logger = logging.getLogger(__name__)
|
||
User = get_user_model()
|
||
|
||
IAAA_APP_ID = "your_app_id"
|
||
IAAA_KEY = "your_key"
|
||
IAAA_USERID_FIELD = "username" # User 模型中与 identityId 对应的字段
|
||
|
||
def iaaa_callback(request):
|
||
"""IAAA 认证回调视图"""
|
||
token = request.GET.get('token')
|
||
if not token:
|
||
return render(request, 'login_failed.html', {'msg': '未收到认证票据'})
|
||
|
||
# 获取客户端真实 IP
|
||
remote_addr = (
|
||
request.META.get('HTTP_X_FORWARDED_FOR', '').split(',')[0].strip()
|
||
or request.META.get('REMOTE_ADDR', '')
|
||
)
|
||
|
||
# 计算消息摘要（参数按字母序排列）
|
||
para_str = f"appId={IAAA_APP_ID}&remoteAddr={remote_addr}&token={token}"
|
||
msg_abs = hashlib.md5((para_str + IAAA_KEY).encode('utf-8')).hexdigest()
|
||
|
||
# 调用 IAAA 验证服务
|
||
validate_url = (
|
||
f"https://iaaa.pku.edu.cn/iaaa/svc/token/validate.do"
|
||
f"?{para_str}&msgAbs={msg_abs}"
|
||
)
|
||
|
||
try:
|
||
resp = requests.get(validate_url, timeout=10)
|
||
resp.raise_for_status()
|
||
result = resp.json()
|
||
except Exception as e:
|
||
logger.error(f"IAAA token 验证请求失败: {e}")
|
||
return render(request, 'login_failed.html', {'msg': '身份认证服务暂不可用，请稍后重试'})
|
||
|
||
if not result.get('success'):
|
||
err_code = result.get('errCode', '未知')
|
||
err_msg = result.get('errMsg', '未知错误')
|
||
logger.warning(f"IAAA 认证失败: errCode={err_code}, errMsg={err_msg}")
|
||
return render(request, 'login_failed.html', {'msg': f'认证失败：{err_msg}'})
|
||
|
||
# 认证成功，提取用户身份
|
||
user_info = result.get('userInfo', {})
|
||
identity_id = user_info.get('identityId', '')
|
||
if not identity_id:
|
||
logger.warning(f"IAAA 认证成功但未返回 identityId: {result}")
|
||
return render(request, 'login_failed.html', {'msg': '无法获取您的身份账号'})
|
||
|
||
# 匹配本地用户
|
||
user = User.objects.filter(**{IAAA_USERID_FIELD: identity_id}).first()
|
||
if user is None:
|
||
logger.info(f"IAAA 用户 {identity_id} 在系统中不存在")
|
||
return render(request, 'login_failed.html', {'msg': '系统中不存在与您北大账号对应的用户'})
|
||
|
||
# 登录
|
||
login(request, user)
|
||
logger.info(f"IAAA 登录成功: {identity_id} ({user_info.get('name', '')})")
|
||
return HttpResponseRedirect(reverse('index'))
|
||
```
|
||
|
||
#### Spring Boot
|
||
|
||
```java
|
||
@GetMapping("/iaaa/callback")
|
||
public String iaaaCallback(
|
||
@RequestParam String token,
|
||
HttpServletRequest request,
|
||
HttpSession session) throws Exception {
|
||
|
||
// 获取客户端真实 IP
|
||
String remoteAddr = request.getHeader("X-Forwarded-For");
|
||
if (remoteAddr != null && !remoteAddr.isEmpty()) {
|
||
remoteAddr = remoteAddr.split(",")[0].trim();
|
||
} else {
|
||
remoteAddr = request.getRemoteAddr();
|
||
}
|
||
|
||
// 计算消息摘要
|
||
String paraStr = "appId=" + appId + "&remoteAddr=" + remoteAddr + "&token=" + token;
|
||
String msgAbs = md5(paraStr + key);
|
||
|
||
// 调用验证服务
|
||
String url = "https://iaaa.pku.edu.cn/iaaa/svc/token/validate.do?"
|
||
+ paraStr + "&msgAbs=" + msgAbs;
|
||
RestTemplate rest = new RestTemplate();
|
||
Map<String, Object> result = rest.getForObject(url, Map.class);
|
||
|
||
if (!(Boolean) result.get("success")) {
|
||
String errMsg = (String) result.getOrDefault("errMsg", "认证失败");
|
||
// 处理失败...
|
||
return "redirect:/login?error=" + URLEncoder.encode(errMsg, "UTF-8");
|
||
}
|
||
|
||
Map<String, String> userInfo = (Map<String, String>) result.get("userInfo");
|
||
String identityId = userInfo.get("identityId");
|
||
// 查找本地用户，创建会话...
|
||
|
||
return "redirect:/";
|
||
}
|
||
|
||
private String md5(String input) throws Exception {
|
||
MessageDigest md = MessageDigest.getInstance("MD5");
|
||
byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8));
|
||
return String.format("%032x", new java.math.BigInteger(1, digest));
|
||
}
|
||
```
|
||
|
||
#### Express.js
|
||
|
||
```javascript
|
||
const crypto = require('crypto');
|
||
const axios = require('axios');
|
||
|
||
app.get('/iaaa/callback', async (req, res) => {
|
||
const { token } = req.query;
|
||
if (!token) return res.redirect('/login?error=no_token');
|
||
|
||
const remoteAddr = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
|
||
|| req.socket.remoteAddress;
|
||
|
||
const paraStr = `appId=${APP_ID}&remoteAddr=${remoteAddr}&token=${token}`;
|
||
const msgAbs = crypto.createHash('md5').update(paraStr + KEY).digest('hex');
|
||
|
||
const url = `https://iaaa.pku.edu.cn/iaaa/svc/token/validate.do?${paraStr}&msgAbs=${msgAbs}`;
|
||
|
||
try {
|
||
const { data } = await axios.get(url);
|
||
|
||
if (!data.success) {
|
||
console.warn(`IAAA 认证失败: ${data.errCode} - ${data.errMsg}`);
|
||
return res.redirect(`/login?error=${encodeURIComponent(data.errMsg || '认证失败')}`);
|
||
}
|
||
|
||
const { identityId, name } = data.userInfo;
|
||
if (!identityId) {
|
||
return res.redirect('/login?error=no_identity');
|
||
}
|
||
|
||
// 查找本地用户，创建 session...
|
||
const user = await User.findOne({ where: { username: identityId } });
|
||
if (!user) {
|
||
return res.redirect('/login?error=user_not_found');
|
||
}
|
||
|
||
req.session.userId = user.id;
|
||
console.log(`IAAA 登录成功: ${identityId} (${name})`);
|
||
res.redirect('/');
|
||
} catch (err) {
|
||
console.error('IAAA 验证请求失败:', err.message);
|
||
res.redirect('/login?error=service_unavailable');
|
||
}
|
||
});
|
||
```
|
||
|
||
## 常见易错点
|
||
|
||
实现时特别注意以下几点，这些是实际集成中最常见的 bug 来源：
|
||
|
||
1. **协议硬编码**：`redirectUrl` 中不要写死 `http://`，应从当前请求或配置动态获取。生产环境通常是 HTTPS，协议不匹配会导致回调失败。
|
||
|
||
2. **msgAbs 参数排序**：参数必须严格按参数名字母升序拼接。当前 `validate.do` 只有三个参数（`appId`, `remoteAddr`, `token`），恰好已是字母序。但如果使用代理认证等其他端点（参数更多），一定要排序。
|
||
|
||
3. **错误响应处理**：IAAA 返回 `success: false` 时，务必提取 `errCode` 和 `errMsg` 记录到日志并展示给用户，不要只返回一个笼统的"认证失败"。
|
||
|
||
4. **客户端 IP**：`remoteAddr` 必须是用户的真实 IP。如果应用在反向代理之后，使用 `X-Forwarded-For` 头的第一个值。IP 不匹配会导致 token 验证失败。
|
||
|
||
5. **回调 URL 尾部斜杠**：IAAA 在注册时绑定了精确的回调 URL，运行时传入的 `redirectUrl` 必须完全匹配（包括尾部斜杠）。
|
||
|
||
6. **服务端可达性**：应用服务器必须能访问 `iaaa.pku.edu.cn` 的 443 端口（HTTPS）。
|
||
|
||
## 高级功能
|
||
|
||
对于需要代理 SSO（中心应用 + 分支应用）或账号验证的场景，参阅：
|
||
|
||
- `references/proxy-sso.md` — 代理身份认证（单点登录多个应用）
|
||
- `references/account-verify.md` — 验证北京大学账号是否存在
|