fa93d71725
添加OAuth2认证相关配置文件和服务实现，包括环境变量配置、PKCE流程支持、token管理等功能。主要变更： - 新增OAuth2配置文件 - 实现OAuth2服务层 - 更新请求拦截器支持token自动刷新 - 修改认证API和store以支持OAuth2流程
173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
# OIDC 集成说明
|
||
|
||
## 概述
|
||
|
||
本项目已经使用 `oidc-client-ts` 库集成 OpenID Connect 认证，替换了原有的自定义登录实现。
|
||
|
||
## 新增文件
|
||
|
||
### 1. OIDC 配置
|
||
- `src/config/oidc.ts` - OIDC 客户端配置
|
||
|
||
### 2. OIDC 服务
|
||
- `src/services/oidc-auth.service.ts` - OIDC 认证服务封装
|
||
|
||
### 3. 回调页面
|
||
- `src/views/_core/authentication/callback.vue` - OIDC 登录回调处理页面
|
||
|
||
### 4. API 更新
|
||
- `src/api/core/auth.ts` - 更新为使用 OIDC token
|
||
|
||
### 5. Store 更新
|
||
- `src/store/auth.ts` - 更新为使用 OIDC 认证流程
|
||
|
||
## 修改文件
|
||
|
||
### 1. 路由配置
|
||
- `src/router/routes/core.ts` - 添加了 `/auth/callback` 路由
|
||
- `src/router/guard.ts` - 更新为使用 OIDC 认证检查
|
||
|
||
### 2. 请求拦截器
|
||
- `src/api/request.ts` - 更新为使用 OIDC 的 token 刷新
|
||
|
||
### 3. 环境配置
|
||
- `.env.development` - 添加 `VITE_AUTH_SERVER_URL` 配置
|
||
|
||
## 环境变量
|
||
|
||
在 `.env` 文件中配置以下变量：
|
||
|
||
```env
|
||
# OIDC认证服务器地址
|
||
VITE_AUTH_SERVER_URL=http://localhost:5132
|
||
```
|
||
|
||
## 认证流程
|
||
|
||
### 密码模式登录 (Resource Owner Password Credentials)
|
||
|
||
1. 用户在登录页面输入用户名和密码
|
||
2. 调用 `authStore.authLogin({ username, password })`
|
||
3. 使用 OIDC 的 `signinResourceOwnerCredentials` 方法直接获取 token
|
||
4. Token 存储到 store，并在请求头中携带
|
||
5. 获取用户信息并设置到用户 store
|
||
|
||
### 授权码模式登录 (Authorization Code Flow)
|
||
|
||
1. 前端调用 `oidcAuthService.signinRedirect()` 重定向到认证服务器
|
||
2. 用户在认证服务器完成认证
|
||
3. 认证服务器重定向回 `/auth/callback?code=...`
|
||
4. 回调页面调用 `authStore.handleCallback()` 处理授权码
|
||
5. 换取访问令牌并存储
|
||
|
||
## Token 管理
|
||
|
||
### 自动续期
|
||
|
||
- 当 token 即将过期（60秒前），OIDC 服务会自动静默续期
|
||
- 如果静默续期失败，会重定向到登录页
|
||
|
||
### 手动刷新
|
||
|
||
```typescript
|
||
await authStore.refreshToken();
|
||
```
|
||
|
||
### 退出登录
|
||
|
||
```typescript
|
||
await authStore.logout();
|
||
```
|
||
|
||
## API 使用
|
||
|
||
### 使用 Access Token
|
||
|
||
API 请求会自动携带 Bearer token：
|
||
|
||
```typescript
|
||
// 请求头会自动添加
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
### 获取用户信息
|
||
|
||
```typescript
|
||
// 从 token claims 获取
|
||
const userInfo = getUserInfoFromToken(user);
|
||
|
||
// 或从服务器获取
|
||
const userInfo = await getUserInfoApi();
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误
|
||
|
||
1. **invalid_grant** - 用户名或密码错误
|
||
2. **invalid_client** - 客户端 ID 无效
|
||
3. **expired_token** - Token 已过期
|
||
4. **invalid_token** - Token 无效
|
||
|
||
所有错误都会显示友好的提示信息，并重定向到登录页。
|
||
|
||
## 注意事项
|
||
|
||
1. **Token 存储**：Token 存储在 localStorage 中，由 oidc-client-ts 管理
|
||
2. **CORS 配置**：认证服务器需要配置 CORS 允许前端域名
|
||
3. **HTTPS**：生产环境必须使用 HTTPS
|
||
4. **PKCE**：如果使用授权码模式，建议启用 PKCE 增强安全性
|
||
|
||
## 后端要求
|
||
|
||
认证服务器必须支持以下功能：
|
||
|
||
- OpenID Connect 1.0 兼容
|
||
- Resource Owner Password Credentials 授权类型
|
||
- Authorization Code 授权类型
|
||
- Refresh Token 支持
|
||
- Userinfo 端点
|
||
|
||
## 开发建议
|
||
|
||
1. 开发时使用 `http://localhost:5132` 作为认证服务器
|
||
2. 生产环境配置实际的认证服务器地址
|
||
3. 使用浏览器开发者工具的 Application 标签查看存储的 token
|
||
4. 监控网络请求，查看 OAuth 流程
|
||
|
||
## 迁移指南
|
||
|
||
如果你之前使用自定义的登录实现：
|
||
|
||
1. 删除旧的登录 API 调用
|
||
2. 替换为使用 `authStore.authLogin()` 方法
|
||
3. 确保 request 拦截器使用 OIDC token
|
||
4. 添加 `/auth/callback` 路由
|
||
5. 配置环境变量 `VITE_AUTH_SERVER_URL`
|
||
|
||
## 故障排除
|
||
|
||
### Token 过期问题
|
||
|
||
如果遇到 token 频繁过期：
|
||
|
||
1. 检查认证服务器的 token 有效期设置
|
||
2. 确保自动续期功能正常工作
|
||
3. 查看浏览器控制台的错误信息
|
||
|
||
### CORS 问题
|
||
|
||
如果遇到 CORS 错误：
|
||
|
||
1. 确保认证服务器配置了 CORS
|
||
2. 检查前端域名是否在允许列表中
|
||
3. 确认 `VITE_AUTH_SERVER_URL` 配置正确
|
||
|
||
### 回调失败
|
||
|
||
如果登录回调失败：
|
||
|
||
1. 检查 `redirect_uri` 是否匹配
|
||
2. 确认认证服务器返回的授权码
|
||
3. 查看浏览器控制台的详细错误信息
|