389 lines
14 KiB
Python
389 lines
14 KiB
Python
|
# =============================================================================
|
||
|
|
# 企微IT智能服务台 — MFA 二次认证 API
|
||
|
|
# =============================================================================
|
||
|
|
# 说明：基于 TOTP(Google Authenticator 兼容)的二次认证 API
|
||
|
|
# Phase 2.1 task #17: pyotp TOTP 服务 + User MFA 字段
|
||
|
|
#
|
||
|
|
# 端点列表:
|
||
|
|
# 1. GET /api/mfa/status — 查询绑定状态(路由守卫用)
|
||
|
|
# 2. POST /api/mfa/bind/start — 生成 secret + 二维码(尚未启用)
|
||
|
|
# 3. POST /api/mfa/bind/confirm — 输入 OTP 完成绑定(启用)
|
||
|
|
# 4. POST /api/mfa/verify — 输入 OTP 通过验证(写 Redis 30 分钟)
|
||
|
|
# 5. POST /api/mfa/disable — 用户主动关闭 MFA
|
||
|
|
# 6. POST /api/admin/mfa/reset/{employee_id} — 管理员重置(员工丢手机兜底)
|
||
|
|
#
|
||
|
|
# 鉴权:
|
||
|
|
# - 1-5 用 get_current_user(任意已登录用户)
|
||
|
|
# - 6 用 require_role("admin")(管理员)
|
||
|
|
#
|
||
|
|
# 流程(典型用户视角):
|
||
|
|
# 1. 前端路由守卫调 GET /status,bound=false → 跳转绑定页
|
||
|
|
# 2. 用户点"绑定" → POST /bind/start → 展示二维码 + secret
|
||
|
|
# 3. 用户用 Authenticator 扫码 → 输入 6 位码 → POST /bind/confirm
|
||
|
|
# 4. 后续敏感操作前 → POST /verify → Redis 30 分钟内免重复输
|
||
|
|
# 5. 丢手机 → 找管理员 → POST /admin/mfa/reset/{employee_id}
|
||
|
|
# =============================================================================
|
||
|
|
|
||
|
|
import logging
|
||
|
|
from datetime import datetime
|
||
|
|
from typing import Optional
|
||
|
|
|
||
|
|
import redis.asyncio as aioredis
|
||
|
|
from fastapi import APIRouter, Depends
|
||
|
|
from sqlalchemy import select
|
||
|
|
from sqlalchemy.ext.asyncio import AsyncSession
|
||
|
|
|
||
|
|
from app.config import settings
|
||
|
|
from app.database import get_db
|
||
|
|
from app.dependencies import UserInfo, get_current_user
|
||
|
|
from app.models.agent import Agent
|
||
|
|
from app.schemas.mfa import (
|
||
|
|
MFAAdminResetResponse,
|
||
|
|
MFABindConfirmRequest,
|
||
|
|
MFABindConfirmResponse,
|
||
|
|
MFABindStartResponse,
|
||
|
|
MFADisableRequest,
|
||
|
|
MFADisableResponse,
|
||
|
|
MFAStatusResponse,
|
||
|
|
MFAVerifyRequest,
|
||
|
|
MFAVerifyResponse,
|
||
|
|
)
|
||
|
|
from app.services.mfa_service import MFA_VERIFIED_TTL_SECONDS, MFAService
|
||
|
|
from app.utils.error_codes import ErrorCode
|
||
|
|
from app.utils.response import AppException, success_response
|
||
|
|
|
||
|
|
logger = logging.getLogger(__name__)
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# 路由配置
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# /api/mfa 前缀;admin 重置走 /api/admin/mfa 单独 router
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
router = APIRouter(prefix="/mfa", tags=["MFA二次认证"])
|
||
|
|
admin_router = APIRouter(prefix="/admin/mfa", tags=["MFA管理(管理员)"])
|
||
|
|
|
||
|
|
|
||
|
|
def _get_redis() -> aioredis.Redis:
|
||
|
|
"""获取 Redis 客户端(模块级 helper,便于测试 patch)。
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
aioredis.Redis: Redis 异步客户端
|
||
|
|
"""
|
||
|
|
return settings.create_redis_client()
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# 通用工具:根据 user_id 查 Agent 记录
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
async def _get_agent_by_employee_id(
|
||
|
|
db: AsyncSession, employee_id: str
|
||
|
|
) -> Optional[Agent]:
|
||
|
|
"""按 user_id(employee_id)查询 Agent 行。
|
||
|
|
|
||
|
|
Args:
|
||
|
|
db: 数据库会话
|
||
|
|
employee_id: 用户标识(企微 userid)
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
Optional[Agent]: 找不到返回 None
|
||
|
|
"""
|
||
|
|
stmt = select(Agent).where(Agent.user_id == employee_id)
|
||
|
|
result = await db.execute(stmt)
|
||
|
|
return result.scalars().first()
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# 通用工具:验证当前用户是否已登录 + 取得 Agent 行
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
async def _require_agent(
|
||
|
|
db: AsyncSession, current_user: UserInfo
|
||
|
|
) -> Agent:
|
||
|
|
"""根据当前 token 取出对应的 Agent 行,不存在则 404。
|
||
|
|
|
||
|
|
为什么需要 Agent 行:
|
||
|
|
MFA 状态/secret 都存在 agents 表,不是 employees 表。
|
||
|
|
|
||
|
|
Raises:
|
||
|
|
AppException: 坐席不存在(E4001)
|
||
|
|
"""
|
||
|
|
agent = await _get_agent_by_employee_id(db, current_user.employee_id)
|
||
|
|
if not agent:
|
||
|
|
raise AppException(ErrorCode.AGENT_NOT_FOUND, "坐席不存在,无法进行 MFA 操作")
|
||
|
|
return agent
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 1. GET /api/mfa/status — 查询绑定状态
|
||
|
|
# =============================================================================
|
||
|
|
@router.get("/status", response_model=None)
|
||
|
|
async def get_mfa_status(
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
):
|
||
|
|
"""查询当前用户的 MFA 绑定状态。
|
||
|
|
|
||
|
|
前端路由守卫使用:
|
||
|
|
- bound=false → 强制走绑定流程
|
||
|
|
- bound=true → 跳到"输入 OTP 验证"或继续业务
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({bound, enabled, last_verified_at})
|
||
|
|
"""
|
||
|
|
agent = await _require_agent(db, current_user)
|
||
|
|
|
||
|
|
return success_response(data=MFAStatusResponse(
|
||
|
|
bound=bool(agent.mfa_enabled and agent.mfa_secret),
|
||
|
|
enabled=bool(agent.mfa_enabled),
|
||
|
|
last_verified_at=agent.mfa_last_verified_at,
|
||
|
|
).model_dump(mode="json"))
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 2. POST /api/mfa/bind/start — 生成 secret + 二维码
|
||
|
|
# =============================================================================
|
||
|
|
@router.post("/bind/start", response_model=None)
|
||
|
|
async def bind_start(
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
):
|
||
|
|
"""生成 TOTP 密钥和二维码。
|
||
|
|
|
||
|
|
行为:
|
||
|
|
- 生成 32 位 base32 secret
|
||
|
|
- 把 secret 写入 agents.mfa_secret(mfa_enabled=False,mfa_bound_at=None)
|
||
|
|
- 返回 otpauth URI + base64 二维码 PNG(给前端展示)
|
||
|
|
|
||
|
|
重复调用策略:
|
||
|
|
- 如果已经 enabled=True → 拒绝,要求先 disable 再重新绑定
|
||
|
|
- 如果只是 secret 存在但 enabled=False → 复用旧 secret(支持"刷新二维码")
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({secret, otpauth_url, qr_code_base64})
|
||
|
|
"""
|
||
|
|
agent = await _require_agent(db, current_user)
|
||
|
|
|
||
|
|
# 已启用则拒绝重新绑定(必须先 disable)
|
||
|
|
if agent.mfa_enabled:
|
||
|
|
raise AppException(
|
||
|
|
ErrorCode.INVALID_PARAMETER,
|
||
|
|
"已绑定 MFA,如需重新绑定请先关闭",
|
||
|
|
)
|
||
|
|
|
||
|
|
# 复用旧 secret 还是新生成?
|
||
|
|
if agent.mfa_secret:
|
||
|
|
secret = agent.mfa_secret
|
||
|
|
else:
|
||
|
|
secret = MFAService.generate_secret()
|
||
|
|
agent.mfa_secret = secret
|
||
|
|
# mfa_enabled 保持 False,mfa_bound_at 等首次验证通过再写
|
||
|
|
db.add(agent)
|
||
|
|
await db.flush()
|
||
|
|
|
||
|
|
otpauth_url = MFAService.build_provisioning_uri(secret, agent.user_id)
|
||
|
|
qr_base64 = MFAService.render_qrcode_base64(otpauth_url)
|
||
|
|
|
||
|
|
logger.info(f"MFA bind/start: agent={agent.user_id}, secret_prefix={secret[:4]}...")
|
||
|
|
|
||
|
|
return success_response(data=MFABindStartResponse(
|
||
|
|
secret=secret,
|
||
|
|
otpauth_url=otpauth_url,
|
||
|
|
qr_code_base64=qr_base64,
|
||
|
|
).model_dump())
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 3. POST /api/mfa/bind/confirm — 输入 OTP 完成绑定
|
||
|
|
# =============================================================================
|
||
|
|
@router.post("/bind/confirm", response_model=None)
|
||
|
|
async def bind_confirm(
|
||
|
|
body: MFABindConfirmRequest,
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
):
|
||
|
|
"""用 6 位 OTP 码确认绑定,启用 MFA。
|
||
|
|
|
||
|
|
行为:
|
||
|
|
- 用 mfa_secret 校验 otp_code(valid_window=1)
|
||
|
|
- 校验通过 → mfa_enabled=True, mfa_bound_at=now(), mfa_last_verified_at=now()
|
||
|
|
- 校验失败 → 抛 AppException(E_INVALID_PARAMETER)
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({success: true})
|
||
|
|
"""
|
||
|
|
agent = await _require_agent(db, current_user)
|
||
|
|
|
||
|
|
# 必须先 start(secret 必须存在)
|
||
|
|
if not agent.mfa_secret:
|
||
|
|
raise AppException(
|
||
|
|
ErrorCode.INVALID_PARAMETER,
|
||
|
|
"请先调用 /api/mfa/bind/start 获取二维码",
|
||
|
|
)
|
||
|
|
|
||
|
|
# 校验 OTP
|
||
|
|
if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
|
||
|
|
logger.warning(f"MFA bind/confirm 验证码错误: agent={agent.user_id}")
|
||
|
|
raise AppException(ErrorCode.INVALID_PARAMETER, "OTP 验证码错误")
|
||
|
|
|
||
|
|
now = datetime.now()
|
||
|
|
agent.mfa_enabled = True
|
||
|
|
agent.mfa_bound_at = now
|
||
|
|
agent.mfa_last_verified_at = now
|
||
|
|
db.add(agent)
|
||
|
|
await db.flush()
|
||
|
|
|
||
|
|
logger.info(f"MFA bind/confirm 绑定成功: agent={agent.user_id}")
|
||
|
|
|
||
|
|
return success_response(data=MFABindConfirmResponse(success=True).model_dump())
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 4. POST /api/mfa/verify — 输入 OTP 通过验证(写 Redis 30 分钟)
|
||
|
|
# =============================================================================
|
||
|
|
@router.post("/verify", response_model=None)
|
||
|
|
async def verify_mfa(
|
||
|
|
body: MFAVerifyRequest,
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
redis: aioredis.Redis = Depends(_get_redis),
|
||
|
|
):
|
||
|
|
"""校验 6 位码,在 Redis 写 30 分钟复用标记。
|
||
|
|
|
||
|
|
行为:
|
||
|
|
- 校验通过 → mfa:verified:{employee_id}=1 TTL 1800s
|
||
|
|
+ 更新 mfa_last_verified_at
|
||
|
|
- 校验失败 → verified=false(不抛异常,前端可以重试)
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({verified, expires_in})
|
||
|
|
"""
|
||
|
|
agent = await _require_agent(db, current_user)
|
||
|
|
|
||
|
|
if not agent.mfa_enabled or not agent.mfa_secret:
|
||
|
|
# 用户还没绑定 MFA,直接返回 verified=false
|
||
|
|
# (前端可据此跳转到绑定流程)
|
||
|
|
return success_response(data=MFAVerifyResponse(
|
||
|
|
verified=False,
|
||
|
|
expires_in=0,
|
||
|
|
).model_dump())
|
||
|
|
|
||
|
|
# 校验
|
||
|
|
if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
|
||
|
|
logger.warning(f"MFA verify 验证码错误: agent={agent.user_id}")
|
||
|
|
return success_response(data=MFAVerifyResponse(
|
||
|
|
verified=False,
|
||
|
|
expires_in=0,
|
||
|
|
).model_dump())
|
||
|
|
|
||
|
|
# 写 Redis 复用标记
|
||
|
|
await MFAService.mark_verified(redis, agent.user_id, MFA_VERIFIED_TTL_SECONDS)
|
||
|
|
|
||
|
|
# 更新最后验证时间
|
||
|
|
now = datetime.now()
|
||
|
|
agent.mfa_last_verified_at = now
|
||
|
|
db.add(agent)
|
||
|
|
await db.flush()
|
||
|
|
|
||
|
|
logger.info(f"MFA verify 通过: agent={agent.user_id}")
|
||
|
|
|
||
|
|
return success_response(data=MFAVerifyResponse(
|
||
|
|
verified=True,
|
||
|
|
expires_in=MFA_VERIFIED_TTL_SECONDS,
|
||
|
|
).model_dump())
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 5. POST /api/mfa/disable — 用户主动关闭 MFA
|
||
|
|
# =============================================================================
|
||
|
|
@router.post("/disable", response_model=None)
|
||
|
|
async def disable_mfa(
|
||
|
|
body: MFADisableRequest,
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
redis: aioredis.Redis = Depends(_get_redis),
|
||
|
|
):
|
||
|
|
"""关闭 MFA(清空 secret + disabled 标记)。
|
||
|
|
|
||
|
|
安全要求: 必须先校验当前 OTP,防止误操作或被劫持后恶意关闭。
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({success: true})
|
||
|
|
"""
|
||
|
|
agent = await _require_agent(db, current_user)
|
||
|
|
|
||
|
|
if not agent.mfa_enabled or not agent.mfa_secret:
|
||
|
|
# 没绑定过,直接幂等成功
|
||
|
|
return success_response(data=MFADisableResponse(success=True).model_dump())
|
||
|
|
|
||
|
|
# 必须先验证 OTP
|
||
|
|
if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
|
||
|
|
raise AppException(ErrorCode.INVALID_PARAMETER, "OTP 验证码错误,无法关闭 MFA")
|
||
|
|
|
||
|
|
# 清空字段
|
||
|
|
agent.mfa_secret = None
|
||
|
|
agent.mfa_enabled = False
|
||
|
|
agent.mfa_bound_at = None
|
||
|
|
# mfa_last_verified_at 保留,作为历史记录
|
||
|
|
db.add(agent)
|
||
|
|
await db.flush()
|
||
|
|
|
||
|
|
# 顺手清掉 Redis 验证标记(避免遗留)
|
||
|
|
await MFAService.clear_verified(redis, agent.user_id)
|
||
|
|
|
||
|
|
logger.info(f"MFA disable: agent={agent.user_id}")
|
||
|
|
|
||
|
|
return success_response(data=MFADisableResponse(success=True).model_dump())
|
||
|
|
|
||
|
|
|
||
|
|
# =============================================================================
|
||
|
|
# 6. POST /api/admin/mfa/reset/{employee_id} — 管理员重置(丢手机兜底)
|
||
|
|
# =============================================================================
|
||
|
|
# 注意:此端点不要求 otp_code(员工已无法提供),只校验 admin 角色
|
||
|
|
# 鉴权:在函数体内手动检查 current_user.roles 是否含 'admin',抛 AppException(FORBIDDEN)
|
||
|
|
# 原因:@require_role 装饰器 + body 参数组合在 FastAPI 签名合并时会重复 current_user 参数
|
||
|
|
# (已知坑,见 memory rbac-pydantic-coroutine-pitfalls.md),手动校验更稳
|
||
|
|
# =============================================================================
|
||
|
|
@admin_router.post("/reset/{employee_id}", response_model=None)
|
||
|
|
async def admin_reset_mfa(
|
||
|
|
employee_id: str,
|
||
|
|
current_user: UserInfo = Depends(get_current_user),
|
||
|
|
db: AsyncSession = Depends(get_db),
|
||
|
|
redis: aioredis.Redis = Depends(_get_redis),
|
||
|
|
):
|
||
|
|
"""管理员重置指定员工的 MFA 绑定(无 OTP 验证)。
|
||
|
|
|
||
|
|
使用场景:
|
||
|
|
- 员工丢手机/换手机 → 管理员后台"重置 MFA"按钮
|
||
|
|
|
||
|
|
鉴权:校验 current_user 是否拥有 admin 角色。
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
success_response({success: true})
|
||
|
|
"""
|
||
|
|
# 角色校验:仅 admin 角色可访问
|
||
|
|
if "admin" not in current_user.roles:
|
||
|
|
raise AppException(
|
||
|
|
ErrorCode.FORBIDDEN,
|
||
|
|
"需要管理员权限",
|
||
|
|
)
|
||
|
|
|
||
|
|
stmt = select(Agent).where(Agent.user_id == employee_id)
|
||
|
|
result = await db.execute(stmt)
|
||
|
|
agent = result.scalars().first()
|
||
|
|
|
||
|
|
if not agent:
|
||
|
|
raise AppException(ErrorCode.AGENT_NOT_FOUND, f"坐席 {employee_id} 不存在")
|
||
|
|
|
||
|
|
agent.mfa_secret = None
|
||
|
|
agent.mfa_enabled = False
|
||
|
|
agent.mfa_bound_at = None
|
||
|
|
# mfa_last_verified_at 保留,作为审计
|
||
|
|
db.add(agent)
|
||
|
|
await db.flush()
|
||
|
|
|
||
|
|
# 顺手清 Redis 标记
|
||
|
|
await MFAService.clear_verified(redis, employee_id)
|
||
|
|
|
||
|
|
logger.info(f"MFA admin reset: employee_id={employee_id} by={current_user.employee_id}")
|
||
|
|
|
||
|
|
return success_response(data=MFAAdminResetResponse(success=True).model_dump())
|