221 lines
4.9 KiB
Markdown
221 lines
4.9 KiB
Markdown
|
# 真实身份认证服务部署指南
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
本文档说明如何配置和部署真实的阿里云身份认证服务，实现生产环境的身份证二要素验证功能。
|
|||
|
|
|
|||
|
|
## 前置条件
|
|||
|
|
|
|||
|
|
### 1. 阿里云账号配置
|
|||
|
|
|
|||
|
|
#### 1.1 开通CloudAuth服务
|
|||
|
|
1. 登录阿里云控制台
|
|||
|
|
2. 开通"实人认证"服务
|
|||
|
|
3. 确认计费方式和额度
|
|||
|
|
|
|||
|
|
#### 1.2 创建AccessKey
|
|||
|
|
1. 进入 RAM 控制台
|
|||
|
|
2. 创建专用的RAM用户
|
|||
|
|
3. 生成AccessKey ID和Secret
|
|||
|
|
4. 分配CloudAuth相关权限
|
|||
|
|
|
|||
|
|
### 2. 必需权限
|
|||
|
|
|
|||
|
|
确保AccessKey具有以下权限之一：
|
|||
|
|
- `AliyunCloudAuthFullAccess` (完整权限)
|
|||
|
|
- 或自定义权限策略，包含：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"Version": "1",
|
|||
|
|
"Statement": [
|
|||
|
|
{
|
|||
|
|
"Effect": "Allow",
|
|||
|
|
"Action": [
|
|||
|
|
"cloudauth:VerifyMaterial"
|
|||
|
|
],
|
|||
|
|
"Resource": "*"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 配置步骤
|
|||
|
|
|
|||
|
|
### 1. 环境变量配置（推荐）
|
|||
|
|
|
|||
|
|
创建 `.env` 文件或设置系统环境变量：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 阿里云身份认证服务配置
|
|||
|
|
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_real_access_key_id
|
|||
|
|
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_real_access_key_secret
|
|||
|
|
export ALIBABA_CLOUD_REGION=ap-southeast-1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 应用配置文件
|
|||
|
|
|
|||
|
|
`application.yml` 已配置支持环境变量：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
aliyun:
|
|||
|
|
cloudauth:
|
|||
|
|
region: ${ALIBABA_CLOUD_REGION:ap-southeast-1}
|
|||
|
|
endpoint: cloudauth.aliyuncs.com
|
|||
|
|
access-key-id: ${ALIBABA_CLOUD_ACCESS_KEY_ID:}
|
|||
|
|
access-key-secret: ${ALIBABA_CLOUD_ACCESS_KEY_SECRET:}
|
|||
|
|
connection-timeout: 10000
|
|||
|
|
response-timeout: 10000
|
|||
|
|
biz-type: ID_2META
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 验证配置
|
|||
|
|
|
|||
|
|
启动应用后，通过日志确认配置是否正确：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
✅ 【真实验证模式】执行阿里云身份认证验证
|
|||
|
|
开始调用阿里云CloudAuth身份认证API
|
|||
|
|
调用阿里云API - BizType: ID_2META, BizId: identity_verify_xxx
|
|||
|
|
阿里云API响应 - RequestId: xxx, VerifyStatus: PASS
|
|||
|
|
✅ 阿里云身份认证成功 - 姓名和身份证号码匹配
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 测试验证
|
|||
|
|
|
|||
|
|
### 1. 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"
|
|||
|
|
}'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 预期响应
|
|||
|
|
|
|||
|
|
**成功响应：**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "实名认证成功",
|
|||
|
|
"data": {
|
|||
|
|
"passed": true,
|
|||
|
|
"resultStatus": "VERIFY_SUCCESS",
|
|||
|
|
"bizId": "SUCCESS_1234567890",
|
|||
|
|
"verifyTime": "2024-09-01 15:30:45"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**失败响应：**
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 400,
|
|||
|
|
"message": "身份证号码与姓名不匹配",
|
|||
|
|
"data": {
|
|||
|
|
"passed": false,
|
|||
|
|
"resultStatus": "FAIL_1234567890",
|
|||
|
|
"resultMessage": "身份证号码与姓名不匹配"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误排查
|
|||
|
|
|
|||
|
|
### 1. 常见错误及解决方案
|
|||
|
|
|
|||
|
|
#### AccessKeyId无效
|
|||
|
|
```
|
|||
|
|
错误：AccessKeyId无效，请检查阿里云访问凭证配置
|
|||
|
|
```
|
|||
|
|
**解决方案：**
|
|||
|
|
- 检查AccessKey ID是否正确
|
|||
|
|
- 确认AccessKey未被删除或禁用
|
|||
|
|
|
|||
|
|
#### 权限不足
|
|||
|
|
```
|
|||
|
|
错误：RAM权限不足，请确保AccessKey具有CloudAuth服务权限
|
|||
|
|
```
|
|||
|
|
**解决方案：**
|
|||
|
|
- 为RAM用户添加CloudAuth相关权限
|
|||
|
|
- 检查权限策略是否正确
|
|||
|
|
|
|||
|
|
#### 网络连接失败
|
|||
|
|
```
|
|||
|
|
调用阿里云身份认证API失败: Connect to cloudauth.aliyuncs.com:443 timed out
|
|||
|
|
```
|
|||
|
|
**解决方案：**
|
|||
|
|
- 检查服务器网络连接
|
|||
|
|
- 确认防火墙设置
|
|||
|
|
- 验证DNS解析
|
|||
|
|
|
|||
|
|
### 2. 日志监控
|
|||
|
|
|
|||
|
|
关键日志位置：
|
|||
|
|
- 认证开始：`【真实验证模式】执行阿里云身份认证验证`
|
|||
|
|
- API调用：`开始调用阿里云CloudAuth身份认证API`
|
|||
|
|
- API响应：`阿里云API响应 - RequestId: xxx`
|
|||
|
|
- 认证结果：`阿里云身份认证成功/失败`
|
|||
|
|
|
|||
|
|
## 性能和限制
|
|||
|
|
|
|||
|
|
### 1. API限制
|
|||
|
|
- 单个阿里云账号默认QPS限制：50次/秒
|
|||
|
|
- 单次查询响应时间：通常在500ms-2000ms
|
|||
|
|
|
|||
|
|
### 2. 成本考虑
|
|||
|
|
- 按调用次数计费
|
|||
|
|
- 建议设置用量监控和预警
|
|||
|
|
|
|||
|
|
### 3. 优化建议
|
|||
|
|
- 实现缓存机制（已验证用户短期内不重复验证）
|
|||
|
|
- 添加请求重试机制
|
|||
|
|
- 监控API成功率
|
|||
|
|
|
|||
|
|
## 安全建议
|
|||
|
|
|
|||
|
|
### 1. 凭证管理
|
|||
|
|
- ✅ 使用环境变量而非硬编码
|
|||
|
|
- ✅ 定期轮换AccessKey
|
|||
|
|
- ✅ 使用RAM用户而非主账号
|
|||
|
|
- ✅ 最小权限原则
|
|||
|
|
|
|||
|
|
### 2. 数据保护
|
|||
|
|
- ✅ 身份证号码脱敏存储
|
|||
|
|
- ✅ 日志中敏感信息脱敏
|
|||
|
|
- ✅ HTTPS传输加密
|
|||
|
|
|
|||
|
|
### 3. 监控告警
|
|||
|
|
- 设置API调用失败率告警
|
|||
|
|
- 监控异常认证模式
|
|||
|
|
- 记录所有认证操作审计日志
|
|||
|
|
|
|||
|
|
## 部署检查清单
|
|||
|
|
|
|||
|
|
### 部署前检查
|
|||
|
|
- [ ] 阿里云CloudAuth服务已开通
|
|||
|
|
- [ ] AccessKey已创建并具备正确权限
|
|||
|
|
- [ ] 环境变量已正确配置
|
|||
|
|
- [ ] 网络连通性已验证
|
|||
|
|
|
|||
|
|
### 部署后验证
|
|||
|
|
- [ ] 应用启动日志无错误
|
|||
|
|
- [ ] 真实身份数据测试通过
|
|||
|
|
- [ ] 错误身份数据正确拒绝
|
|||
|
|
- [ ] API响应时间在可接受范围内
|
|||
|
|
- [ ] 日志记录完整且敏感信息已脱敏
|
|||
|
|
|
|||
|
|
### 监控设置
|
|||
|
|
- [ ] API调用量监控
|
|||
|
|
- [ ] 错误率告警
|
|||
|
|
- [ ] 响应时间监控
|
|||
|
|
- [ ] 成本监控
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*文档更新时间：2024年9月1日*
|
|||
|
|
*适用版本：v1.0+（已集成真实阿里云API）*
|