141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
# 阿里云身份认证服务集成说明
|
||
|
||
## 功能概述
|
||
|
||
本项目已成功集成阿里云身份认证服务（CloudAuth）的身份证二要素核验功能，实现用户实名认证。
|
||
|
||
**✅ 当前状态：已启用真实的阿里云身份认证API调用（新版SDK）**
|
||
|
||
**🔧 最新更新：** 已修复 `MissingFaceImageUrl` 错误，更新为官方推荐的新版SDK和正确的API接口。
|
||
|
||
## 实现的功能
|
||
|
||
### 1. 实名认证接口
|
||
- **端点**: `POST /user/identity/verify`
|
||
- **功能**: 用户提交身份证号码和真实姓名进行实名认证
|
||
- **认证流程**:
|
||
- 验证身份证号码和姓名格式
|
||
- 调用阿里云身份认证服务验证信息匹配性
|
||
- 验证通过后更新用户认证状态
|
||
|
||
### 2. 认证状态查询
|
||
- **端点**: `GET /user/identity/status`
|
||
- **功能**: 查询当前用户的实名认证状态和相关信息（脱敏后）
|
||
|
||
### 3. 认证状态检查
|
||
- **端点**: `GET /user/identity/check`
|
||
- **功能**: 简单检查当前用户是否已完成实名认证
|
||
|
||
## 数据库字段说明
|
||
|
||
用户表（`user`）中实名认证相关字段：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `real_username` | varchar(64) | 真实用户名 |
|
||
| `id_number` | varchar(18) | 身份证号码 |
|
||
| `is_verified` | tinyint | 是否实名认证 (0-未认证, 1-已认证) |
|
||
|
||
## 配置信息
|
||
|
||
### application.yml 配置
|
||
|
||
```yaml
|
||
aliyun:
|
||
cloudauth:
|
||
region: cn-hangzhou
|
||
endpoint: cloudauth.aliyuncs.com
|
||
# 直接从配置文件读取认证信息
|
||
access-key-id: LTAI5t68do3qVXx5Rufugt3X
|
||
access-key-secret: 2vD9ToIff49Vph4JQXsn0Cy8nXQfzA
|
||
connection-timeout: 10000
|
||
response-timeout: 10000
|
||
# 身份认证配置
|
||
biz-type: ID_2META
|
||
param-type: normal
|
||
```
|
||
|
||
### 配置说明
|
||
|
||
**直接配置文件读取方式**：
|
||
- ✅ 所有配置直接在application.yml中管理
|
||
- ✅ 无需设置环境变量
|
||
- ✅ 配置集中统一，便于管理
|
||
|
||
## 当前实现状态
|
||
|
||
### 已实现
|
||
✅ 配置文件集成
|
||
✅ 数据库字段支持
|
||
✅ API接口完整实现
|
||
✅ DTO类和响应封装
|
||
✅ 用户认证状态管理
|
||
✅ 输入验证和异常处理
|
||
✅ 日志记录和监控
|
||
✅ **真实阿里云CloudAuth SDK集成**
|
||
✅ **真实身份证二要素验证**
|
||
✅ **完整的错误处理和权限检查**
|
||
|
||
### 当前实现状态
|
||
|
||
**✅ 已完成真实阿里云API集成**:
|
||
|
||
1. **✅ 已启用阿里云SDK**: `pom.xml`中的阿里云CloudAuth依赖已启用
|
||
2. **✅ 已实现真实API调用**: `IdentityVerifyServiceImpl`中已集成真实的阿里云身份认证API
|
||
3. **✅ 已配置访问凭证**: 支持环境变量和配置文件两种方式配置AccessKey
|
||
|
||
### 重要提醒
|
||
|
||
**⚠️ 生产环境部署前请确认：**
|
||
1. **配置有效的阿里云AccessKey**: 确保具有CloudAuth服务权限
|
||
2. **验证网络连接**: 确保服务器能够访问阿里云API
|
||
3. **监控API调用**: 关注API调用成功率和响应时间
|
||
|
||
## API使用示例
|
||
|
||
### 提交实名认证
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8081/user/identity/verify \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer your_jwt_token" \
|
||
-d '{
|
||
"realName": "张三",
|
||
"idNumber": "110101199003077777"
|
||
}'
|
||
```
|
||
|
||
### 查询认证状态
|
||
|
||
```bash
|
||
curl -X GET http://localhost:8081/user/identity/status \
|
||
-H "Authorization: Bearer your_jwt_token"
|
||
```
|
||
|
||
## 安全特性
|
||
|
||
1. **JWT认证**: 所有接口都需要有效的JWT令牌
|
||
2. **数据脱敏**: 查询接口返回脱敏后的用户信息
|
||
3. **输入验证**: 严格的身份证号码和姓名格式验证
|
||
4. **异常处理**: 完善的错误处理和日志记录
|
||
5. **事务保证**: 认证过程使用数据库事务保证数据一致性
|
||
|
||
## 业务逻辑保护
|
||
|
||
- 已实名认证的用户不能重复认证
|
||
- 完整的输入参数验证
|
||
- 用户状态检查和权限控制
|
||
- 不破坏现有的用户管理和业务逻辑
|
||
|
||
## 扩展计划
|
||
|
||
1. 集成真实的阿里云CloudAuth SDK
|
||
2. 添加认证历史记录
|
||
3. 支持企业用户认证
|
||
4. 添加认证失败重试机制
|
||
5. 集成短信/邮件通知功能
|
||
|
||
---
|
||
|
||
*文档最后更新: 2024年8月31日*
|