# 鼎捷云 IAM 登录接入指南

> 面向新项目从零接入鼎捷云统一身份认证（IAM），涵盖前端登录、SSO 回调、后端 Token 鉴权全链路。

---

## 一、整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│  浏览器                                                          │
│                                                                  │
│  ┌───────────┐     ┌─────────────┐     ┌───────────────────────┐  │
│  │  登录页    │────→│  iamAuth.ts  │────→│  sessionStorage        │  │
│  │  /login   │     │  RSA+AES     │     │  userToken / userInfo  │  │
│  └───────────┘     └──────┬──────┘     └───────────┬───────────┘  │
│                            │                         │            │
│  ┌───────────┐             │            ┌────────────▼──────────┐ │
│  │  SSO 回调  │─────────────┘            │  axios 拦截器          │ │
│  │  /sso-login│                        │  自动带 IAM 鉴权请求头   │ │
│  └───────────┘                          └────────────┬──────────┘ │
└──────────────────────────────────────────────────────┼────────────┘
                                                        │
                  ┌─────────────────────────────────────┼──────────────────┐
                  │                  │                                    │
           ┌──────▼─────┐     ┌──────▼──────┐                      ┌──────▼──────┐
           │  Vite 代理   │     │  后端 API    │                      │  鼎捷云 IAM  │
           │  /iam-api →  │     │  FastAPI     │                      │             │
           │  /api → 8000 │     │  current_admin│───────→│ token/analyze│
           └────────────┘     └─────────────┘                      └─────────────┘
```

### 两种登录方式

**方式一：账号密码登录（普通登录）**

```
用户输入账号密码
  → 前端 RSA+AES 加密链路调 IAM /identity/login 拿 userToken
  → 拉取租户列表 → 切换默认租户刷新 token
  → userToken + userInfo 存 sessionStorage → 跳首页
```

**方式二：SSO 单点登录**

```
外部系统跳转 /sso-login?userToken=xxx
  → 前端调 iamSsoLogin(userToken)
    → POST /identity/token/refresh/app   刷新应用 token
    → POST /identity/login/info          获取登录详情
    → POST /tenant?appId=APPID           拉取租户列表，选默认租户
    → POST /identity/token/refresh/tenant 切换租户刷新 token
  → userInfo 写入 sessionStorage → 跳首页
```

### 后端鉴权流程

```
前端请求（带 digi-middleware-auth-user / digi-middleware-auth-app 头）
  → 后端 current_admin 依赖读取请求头
  → 调 IAM POST /api/iam/v2/identity/token/analyze 校验
  → 200 + 含 id/name → 返回管理员信息（缓存 30s）
  → 非 200 / 无用户标识 → 401
```

---

## 二、前置准备

### 2.1 在鼎捷云 IAM 注册应用

接入前需在鼎捷云 IAM 平台完成应用注册，获取以下凭证：

| 凭证 | 说明 | 用途 |
|---|---|---|
| `apptoken` | 应用 token（digi-middleware-auth-app） | 所有 IAM API 请求头必带 |
| `appId` | 应用 ID | 租户列表查询参数 |

### 2.2 配置 SSO 回调地址

在 IAM 应用配置中，将 SSO 回调地址设为：

```
https://你的域名/sso-login
```

IAM 认证成功后会以 `?userToken=xxx` 形式回跳到该地址。

### 2.3 IAM 关键接口清单

| 接口 | 方法 | 用途 |
|---|---|---|
| `/api/iam/v2/identity/publickey` | GET | 获取服务端 RSA 公钥 |
| `/api/iam/v2/identity/aeskey` | POST | 用客户端公钥换取加密的 AES 密钥 |
| `/api/iam/v2/identity/login` | POST | 账号密码登录 |
| `/api/iam/v2/identity/token/refresh/app` | POST | SSO 刷新应用 token |
| `/api/iam/v2/identity/login/info` | POST | 获取登录详情 |
| `/api/iam/v2/identity/token/refresh/tenant` | POST | 切换租户刷新 token |
| `/api/iam/v2/tenant?appId=APPID` | POST | 拉取用户授权租户列表 |
| `/api/iam/v2/identity/token/analyze` | POST | **后端校验 token（核心）** |

IAM 服务地址：`https://iam.digiwincloud.com.cn`

---

## 三、前端接入

### 3.1 创建前端项目

```bash
npm create vite@latest frontend -- --template react-ts
cd frontend
npm install
npm install react-router-dom axios antd @ant-design/icons jsencrypt dayjs
```

依赖说明：

| 依赖 | 用途 |
|---|---|
| `react-router-dom` | 路由（登录页、SSO 回调、路由守卫） |
| `axios` | HTTP 请求 + 拦截器带 IAM 头 |
| `antd` | UI 组件库 |
| `jsencrypt` | IAM 登录 RSA 密钥对生成与加密 |
| `dayjs` | 日期格式化（可选） |

### 3.2 Vite 代理配置

`vite.config.ts`：

```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      // 后端 API 代理
      '/api': 'http://localhost:8000',
      // 鼎捷云 IAM 代理（避免浏览器跨域）
      '/iam-api': {
        target: 'https://iam.digiwincloud.com.cn',
        changeOrigin: true,
        rewrite: (p) => p.replace(/^\/iam-api/, ''),
      },
    },
  },
})
```

### 3.3 创建 IAM 登录服务

`src/services/iamAuth.ts` — 核心模块，封装 IAM 登录、SSO、会话管理：

```ts
import { JSEncrypt } from 'jsencrypt';

/**
 * 鼎捷云 IAM 登录服务
 *
 * 完整登录流程：
 * 1. RSA+AES 加密链路获取 userToken（/api/iam/v2/identity/login）
 * 2. 拉取用户授权租户列表，默认选第一个
 * 3. 切换租户刷新 token
 * 4. 将完整用户信息写入 sessionStorage
 */

// 代理路径（vite.config.ts 中 /iam-api → https://iam.digiwincloud.com.cn）
const IAM_API_BASE = '/iam-api/api/iam/v2';
const IAM_IDENTITY_BASE = `${IAM_API_BASE}/identity`;

// ★ 替换为你的 IAM 应用凭证
export const APP_TOKEN = '你的应用 apptoken';
export const APPID = '你的应用ID';

// IAM AES 加密固定 IV（16 字节）
const AES_IV = 'ghUb#er57HBh(u%g';

/** PEM 包装/剥离工具 */
function wrapPem(base64Key: string): string {
  if (base64Key.includes('BEGIN')) return base64Key;
  const body = base64Key.replace(/-----(BEGIN|END)[^-]+-----/g, '').replace(/\s+/g, '');
  const lines = body.match(/.{1,64}/g) || [];
  return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----`;
}

function stripPem(pem: string): string {
  return pem.replace(/-----(BEGIN|END)[^-]+-----/g, '').replace(/\s+/g, '');
}

/** AES-CBC/PKCS7 加密，输出 base64 */
async function aesEncryptToBase64(plainText: string, aesKey: string): Promise<string> {
  const enc = new TextEncoder();
  const keyData = enc.encode(aesKey);
  const ivData = enc.encode(AES_IV);
  const cryptoKey = await crypto.subtle.importKey('raw', keyData, { name: 'AES-CBC' }, false, ['encrypt']);
  const cipherBuf = await crypto.subtle.encrypt({ name: 'AES-CBC', iv: ivData }, cryptoKey, enc.encode(plainText));
  const bytes = new Uint8Array(cipherBuf);
  let bin = '';
  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
  return btoa(bin);
}

/** 应用层请求头（含 apptoken） */
function appHeaders(extra?: Record<string, string>): Record<string, string> {
  return { 'Content-Type': 'application/json', 'digi-middleware-auth-app': APP_TOKEN, ...extra };
}

/** 用户鉴权请求头（含 apptoken + usertoken） */
function userHeaders(userToken: string, extra?: Record<string, string>): Record<string, string> {
  return appHeaders({ 'digi-middleware-auth-user': userToken, ...extra });
}

/** 从响应中提取 token 字符串 */
function pickToken(obj: Record<string, unknown>): string | undefined {
  if (typeof obj.token === 'string') return obj.token;
  if (typeof obj.userToken === 'string') return obj.userToken;
  const data = obj.data as Record<string, unknown> | undefined;
  if (data && typeof data.token === 'string') return data.token;
  const result = obj.result as Record<string, unknown> | undefined;
  if (result && typeof result.token === 'string') return result.token;
  return undefined;
}

export interface IamLoginParams { userId: string; password: string; tenantId?: string }
export interface IamLoginResult { token: string; userId: string; userInfo: Record<string, unknown> }

/**
 * IAM 普通登录（identityType: query）
 * 加密链路：生成 RSA 密钥对 → 获取服务端公钥 → 加密客户端公钥 → 换 AES 密钥 → 加密密码 → 登录
 */
export async function iamLogin({ userId, password, tenantId }: IamLoginParams): Promise<IamLoginResult> {
  // 1. 客户端生成 RSA 密钥对（1024）
  const client = new JSEncrypt({ default_key_size: '1024' });
  client.getKey();
  const clientPrivateKeyPem = client.getPrivateKey();
  const clientPublicKeyB64 = stripPem(client.getPublicKey());

  // 2. 获取服务端公钥
  const pkRes = await fetch(`${IAM_IDENTITY_BASE}/publickey`, { headers: appHeaders() });
  if (!pkRes.ok) throw new Error(`获取服务端公钥失败 (HTTP ${pkRes.status})`);
  const pkJson = await pkRes.json();
  const serverPublicKey: string = pkJson.publicKey;
  if (!serverPublicKey) throw new Error('服务端公钥为空');

  // 3. 服务端公钥加密客户端公钥
  const server = new JSEncrypt();
  server.setPublicKey(wrapPem(serverPublicKey));
  const clientEncryptPublicKey = server.encrypt(clientPublicKeyB64);
  if (!clientEncryptPublicKey) throw new Error('加密客户端公钥失败');

  // 4. 获取加密的 AES 密钥
  const aesRes = await fetch(`${IAM_IDENTITY_BASE}/aeskey`, {
    method: 'POST', headers: appHeaders(),
    body: JSON.stringify({ clientEncryptPublicKey }),
  });
  if (!aesRes.ok) throw new Error(`获取 AES 密钥失败 (HTTP ${aesRes.status})`);
  const aesJson = await aesRes.json();
  const encryptAesKey: string = aesJson.encryptAesKey;
  if (!encryptAesKey) throw new Error(`获取 AES 密钥失败: ${JSON.stringify(aesJson)}`);

  // 5. 客户端私钥解密 AES 密钥
  client.setPrivateKey(clientPrivateKeyPem);
  const aesKey = client.decrypt(encryptAesKey);
  if (!aesKey) throw new Error('解密 AES 密钥失败');

  // 6. AES 加密密码
  const passwordHash = await aesEncryptToBase64(password, aesKey);

  // 7. 登录
  const loginBody: Record<string, string> = { userId, passwordHash, clientEncryptPublicKey, identityType: 'query' };
  if (tenantId) loginBody.tenantId = tenantId;
  const loginRes = await fetch(`${IAM_IDENTITY_BASE}/login`, { method: 'POST', headers: appHeaders(), body: JSON.stringify(loginBody) });
  const loginJson = (await loginRes.json().catch(() => ({}))) as Record<string, unknown>;
  const initialToken = pickToken(loginJson);
  if (!loginRes.ok || !initialToken) {
    const msg = loginJson.message || loginJson.msg || loginJson.error || `HTTP ${loginRes.status}`;
    throw new Error(`登录失败: ${msg}`);
  }

  // 8. 拉取租户列表 + 切换默认租户
  const tenantCtx = await switchDefaultTenant(initialToken);

  // 9. 组装完整 userInfo
  const userInfo: Record<string, unknown> = {
    ...(tenantCtx.authoredUser ?? {}), ...(loginJson ?? {}), userId,
    token: tenantCtx.token, isLoggedin: true,
    ...(tenantCtx.currTenantList ? { currTenantList: tenantCtx.currTenantList } : {}),
  };
  return { token: tenantCtx.token, userId, userInfo };
}

/**
 * 切换默认租户
 * 1. POST /tenant?appId=APPID 拉取租户列表
 * 2. 优先选 isDefault=true 的租户，否则取第一个
 * 3. POST /identity/token/refresh/tenant 刷新 token
 */
export async function switchDefaultTenant(userToken: string): Promise<{
  token: string; authoredUser?: Record<string, unknown>; currTenantList?: unknown[]
}> {
  let finalToken = userToken;
  let authoredUser: Record<string, unknown> | undefined;
  let currTenantList: unknown[] | undefined;
  try {
    const tenantRes = await fetch(`${IAM_API_BASE}/tenant?appId=${encodeURIComponent(APPID)}`, { method: 'POST', headers: userHeaders(userToken) });
    if (!tenantRes.ok) throw new Error(`获取租户列表失败 (HTTP ${tenantRes.status})`);
    const tenantJson = (await tenantRes.json().catch(() => ({}))) as Record<string, unknown>;
    let tenants: unknown[] = [];
    if (Array.isArray(tenantJson)) tenants = tenantJson;
    else if (Array.isArray(tenantJson.data)) tenants = tenantJson.data as unknown[];
    else if (Array.isArray(tenantJson.list)) tenants = tenantJson.list as unknown[];
    else if (Array.isArray(tenantJson.result)) tenants = tenantJson.result as unknown[];

    if (tenants.length > 0) {
      currTenantList = tenants;
      const defaultTenant = (tenants.find((t) => (t as Record<string, unknown>)?.isDefault === true) ?? tenants[0]) as Record<string, unknown>;
      const tenantSid = defaultTenant.sid ?? defaultTenant.tenantSid ?? defaultTenant.id;
      if (tenantSid !== undefined && tenantSid !== null) {
        const refreshRes = await fetch(`${IAM_IDENTITY_BASE}/token/refresh/tenant`, {
          method: 'POST', headers: userHeaders(userToken), body: JSON.stringify({ tenantSid }),
        });
        if (refreshRes.ok) {
          const refreshJson = (await refreshRes.json().catch(() => ({}))) as Record<string, unknown>;
          const refreshedToken = pickToken(refreshJson);
          if (refreshedToken) finalToken = refreshedToken;
          if (refreshJson.authoredUser && typeof refreshJson.authoredUser === 'object') {
            authoredUser = refreshJson.authoredUser as Record<string, unknown>;
          } else {
            authoredUser = refreshJson;
          }
        }
      }
    }
  } catch (ex) {
    console.warn('[IAM] 租户切换流程异常，将使用原 token', ex);
  }
  return { token: finalToken, authoredUser, currTenantList };
}

/**
 * SSO 登录（基于外部传入的 userToken）
 */
export async function iamSsoLogin(initialUserToken: string): Promise<IamLoginResult> {
  // 1. 刷新应用 token
  const refreshAppRes = await fetch(`${IAM_IDENTITY_BASE}/token/refresh/app`, { method: 'POST', headers: userHeaders(initialUserToken) });
  if (!refreshAppRes.ok) throw new Error(`SSO token 刷新失败 (HTTP ${refreshAppRes.status})`);
  const refreshAppJson = (await refreshAppRes.json().catch(() => ({}))) as Record<string, unknown>;
  const appRefreshedToken = pickToken(refreshAppJson) ?? initialUserToken;

  // 2. 获取登录详情
  let loginInfoJson: Record<string, unknown> = {};
  try {
    const infoRes = await fetch(`${IAM_IDENTITY_BASE}/login/info`, { method: 'POST', headers: userHeaders(appRefreshedToken) });
    if (infoRes.ok) loginInfoJson = (await infoRes.json().catch(() => ({}))) as Record<string, unknown>;
  } catch (ex) { console.warn('[IAM] login/info 调用异常', ex); }

  // 3. 切换默认租户
  const tenantCtx = await switchDefaultTenant(appRefreshedToken);

  // 4. 组装 userInfo
  const userId = (loginInfoJson.userId as string) ?? (refreshAppJson.userId as string) ?? (tenantCtx.authoredUser?.userId as string) ?? '';
  const userInfo: Record<string, unknown> = {
    ...(tenantCtx.authoredUser ?? {}), ...(refreshAppJson ?? {}), ...(loginInfoJson ?? {}),
    userId, token: tenantCtx.token, isLoggedin: true,
    ...(tenantCtx.currTenantList ? { currTenantList: tenantCtx.currTenantList } : {}),
  };
  return { token: tenantCtx.token, userId, userInfo };
}

/* ---------------- sessionStorage 会话管理 ---------------- */

const KEY_USER_TOKEN = 'userToken';
const KEY_USER_INFO = 'userInfo';
const KEY_APP_TOKEN = 'digi-middleware-auth-app';

export function saveSession(token: string, info: Record<string, unknown>): void {
  sessionStorage.setItem(KEY_USER_TOKEN, token);
  sessionStorage.setItem(KEY_USER_INFO, JSON.stringify(info));
  sessionStorage.setItem(KEY_APP_TOKEN, APP_TOKEN);
}

export function getUserToken(): string | null { return sessionStorage.getItem(KEY_USER_TOKEN); }

export function getUserInfo(): Record<string, unknown> | null {
  const raw = sessionStorage.getItem(KEY_USER_INFO);
  if (!raw) return null;
  try { return JSON.parse(raw); } catch { return null; }
}

export function clearSession(): void {
  sessionStorage.removeItem(KEY_USER_TOKEN);
  sessionStorage.removeItem(KEY_USER_INFO);
  sessionStorage.removeItem(KEY_APP_TOKEN);
}
```

### 3.4 创建登录页

`src/pages/Login/index.tsx`：

```tsx
import { useState } from 'react';
import { Button, Form, Input } from 'antd';
import { LockOutlined, UserOutlined, CloseCircleOutlined } from '@ant-design/icons';
import { useLocation, useNavigate } from 'react-router-dom';
import { iamLogin, saveSession } from '../../services/iamAuth';

export default function Login() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');
  const nav = useNavigate();
  const loc = useLocation();

  const onFinish = async (values: { userId: string; password: string }) => {
    setLoading(true);
    setError('');
    try {
      const result = await iamLogin({ userId: values.userId.trim(), password: values.password });
      saveSession(result.token, result.userInfo);
      const from = (loc.state as { from?: string })?.from ?? '/';
      nav(from, { replace: true });
    } catch (ex) {
      setError(ex instanceof Error ? ex.message : '登录失败，请稍后重试');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div style={{ /* 深色背景样式 */ }}>
      <Form onFinish={onFinish} size="large" autoComplete="on">
        <Form.Item name="userId" rules={[{ required: true, message: '请输入账号' }]}>
          <Input prefix={<UserOutlined />} placeholder="账号（用户ID / 手机号 / 邮箱）" className="iam-login-input" />
        </Form.Item>
        <Form.Item name="password" rules={[{ required: true, message: '请输入密码' }]}>
          <Input.Password prefix={<LockOutlined />} placeholder="密码" className="iam-login-input" />
        </Form.Item>
        {error && <div><CloseCircleOutlined /> {error}</div>}
        <Form.Item>
          <Button type="primary" htmlType="submit" block loading={loading}>
            {loading ? '登录中...' : '登 录'}
          </Button>
        </Form.Item>
      </Form>
      <p style={{ textAlign: 'center', color: 'rgba(168,216,255,0.6)' }}>鼎捷云统一身份认证 · IAM</p>
    </div>
  );
}
```

> **placeholder 颜色**：antd Input 的 `className` 传给外层 wrapper，需在 `index.html` 用后代选择器命中实际 `input`：
>
> ```html
> <style>
>   .iam-login-input input::placeholder { color: #858D9A !important; }
> </style>
> ```

### 3.5 创建 SSO 回调页

`src/pages/SSOLogin/index.tsx`：

```tsx
import { useEffect, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';
import { Spin } from 'antd';
import { CloseCircleOutlined } from '@ant-design/icons';
import { iamSsoLogin, saveSession } from '../../services/iamAuth';

const SSOLogin: React.FC = () => {
  const navigate = useNavigate();
  const [searchParams] = useSearchParams();
  const [error, setError] = useState('');

  useEffect(() => {
    const userToken = searchParams.get('userToken');
    if (!userToken) { setError('URL 缺少 userToken 参数'); return; }

    let cancelled = false;
    (async () => {
      try {
        const result = await iamSsoLogin(userToken);
        if (cancelled) return;
        saveSession(result.token, result.userInfo);
        navigate('/', { replace: true });
      } catch (ex) {
        if (cancelled) return;
        setError(ex instanceof Error ? ex.message : 'SSO 登录失败');
      }
    })();
    return () => { cancelled = true; };
  }, [searchParams, navigate]);

  if (error) {
    return (
      <div>
        <CloseCircleOutlined />
        <div>SSO 登录失败：{error}</div>
        <button onClick={() => navigate('/login', { replace: true })}>前往登录页</button>
      </div>
    );
  }
  return <div><Spin size="large" /><div>正在登录...</div></div>;
};

export default SSOLogin;
```

### 3.6 路由守卫

`src/App.tsx`：

```tsx
import { Navigate, Route, Routes, useLocation } from 'react-router-dom';
import Login from './pages/Login';
import SSOLogin from './pages/SSOLogin';
import { clearSession, getUserInfo } from './services/iamAuth';

/** 未登录跳登录页，携带来源路径用于回跳 */
function RequireAuth({ children }: { children: React.ReactNode }) {
  const location = useLocation();
  const token = sessionStorage.getItem('userToken');
  if (!token) {
    return <Navigate to="/login" replace state={{ from: location.pathname + location.search }} />;
  }
  return <>{children}</>;
}

export default function App() {
  useLocation();
  return (
    <Routes>
      <Route path="/login" element={<Login />} />
      <Route path="/sso-login" element={<SSOLogin />} />
      <Route path="/*" element={<RequireAuth>{/* 你的业务页面 */}</RequireAuth>} />
    </Routes>
  );
}
```

### 3.7 Axios 拦截器

`src/api/client.ts` — 请求自动带 IAM 鉴权头，401 清理会话跳登录：

```ts
import axios from 'axios';
import { APP_TOKEN } from '../services/iamAuth';

const api = axios.create({ baseURL: '/api', timeout: 15000 });

// 请求拦截：自动带 IAM 鉴权头
api.interceptors.request.use((config) => {
  const token = sessionStorage.getItem('userToken');
  if (token) {
    config.headers['digi-middleware-auth-user'] = token;
    config.headers['digi-middleware-auth-app'] = APP_TOKEN;
  }
  return config;
});

// 响应拦截：401 清理会话跳登录
api.interceptors.response.use(
  (res) => res,
  (err) => {
    if (err.response?.status === 401) {
      const path = window.location.pathname;
      if (path !== '/login' && !path.startsWith('/sso-login')) {
        sessionStorage.removeItem('userToken');
        sessionStorage.removeItem('userInfo');
        window.location.href = '/login';
      }
    }
    return Promise.reject(err);
  },
);

export default api;
```

---

## 四、后端接入

### 4.1 创建后端项目

```bash
mkdir backend && cd backend
python3 -m venv venv && source venv/bin/activate
pip install fastapi uvicorn[standard] asyncpg httpx pydantic
```

`requirements.txt`：

```
fastapi>=0.115.0
uvicorn[standard]>=0.30.0
asyncpg>=0.30.0
httpx>=0.27.0
pydantic>=2.9.0
```

### 4.2 配置项

`app/core/config.py`：

```python
"""配置：环境变量读取"""

import os

class Settings:
    # IAM 配置
    IAM_BASE_URL: str = os.getenv("IAM_BASE_URL", "https://iam.digiwincloud.com.cn")
    IAM_APP_TOKEN: str = os.getenv("IAM_APP_TOKEN", "你的应用 apptoken")
    IAM_CACHE_TTL: int = int(os.getenv("IAM_CACHE_TTL", "30"))  # token 校验缓存秒数

    # 前端静态文件目录（生产环境）
    STATIC_DIR: str = os.getenv("STATIC_DIR", "../frontend/dist")

settings = Settings()
```

环境变量：

| 变量 | 说明 | 默认值 |
|---|---|---|
| `IAM_BASE_URL` | IAM 服务地址 | `https://iam.digiwincloud.com.cn` |
| `IAM_APP_TOKEN` | 应用 apptoken | 无，**必填** |
| `IAM_CACHE_TTL` | token 校验缓存秒数 | `30` |

### 4.3 IAM Token 校验服务

`app/core/iam.py` — 调用 IAM `token/analyze` 校验用户 token，带进程内缓存：

```python
"""鼎捷云 IAM token 鉴权服务

通过调用 IAM /api/iam/v2/identity/token/analyze 校验请求头中的
digi-middleware-auth-user / digi-middleware-auth-app，解析出用户信息。
进程内缓存（userToken -> userInfo），TTL 由 IAM_CACHE_TTL 控制。
"""

import time
import httpx
from .config import settings

_http_client: httpx.AsyncClient | None = None
_cache: dict[str, tuple[dict | None, float]] = {}

def _get_http_client() -> httpx.AsyncClient:
    global _http_client
    if _http_client is None:
        _http_client = httpx.AsyncClient(timeout=5.0)
    return _http_client

async def close_iam_client() -> None:
    """关闭 httpx 客户端（进程退出时调用）。"""
    global _http_client
    if _http_client is not None:
        await _http_client.aclose()
        _http_client = None

async def analyze_token(user_token: str, app_token: str | None = None) -> dict | None:
    """校验 IAM userToken，返回用户信息 dict 或 None。"""
    # 1. 查缓存
    now = time.time()
    cached = _cache.get(user_token)
    if cached is not None and (now - cached[1]) < settings.IAM_CACHE_TTL:
        return cached[0]

    # 2. 调用 IAM analyze
    headers = {
        "digi-middleware-auth-user": user_token,
        "digi-middleware-auth-app": app_token or settings.IAM_APP_TOKEN,
    }
    try:
        client = _get_http_client()
        resp = await client.post(
            f"{settings.IAM_BASE_URL}/api/iam/v2/identity/token/analyze",
            headers=headers,
        )
    except Exception as ex:
        _cache[user_token] = (None, now)
        print(f"[IAM] analyze 请求异常: {ex}")
        return None

    if resp.status_code == 200:
        data = resp.json()
        if data.get("id") or data.get("name"):
            _cache[user_token] = (data, now)
            return data
        _cache[user_token] = (None, now)
        return None

    _cache[user_token] = (None, now)
    return None
```

### 4.4 IAM analyze 返回格式

`POST /api/iam/v2/identity/token/analyze` 成功返回：

```json
{
  "tenantSid": 1029303229426688,
  "tenantId": "datasolution",
  "tenantName": "鼎捷雅典娜演示",
  "sid": 50891717448256,
  "id": "dongsk@digiwin.com",
  "name": "董书康",
  "telephone": "13851711172",
  "email": "dongsk@digiwin.com",
  "appId": "data-business-demo",
  "tokenType": "digiwin",
  "tokenExpiresIn": 3232527,
  "identityType": "service"
}
```

| 字段 | 说明 |
|---|---|
| `id` | 用户标识（邮箱/手机号/用户ID） |
| `name` | 用户姓名 |
| `email` | 邮箱 |
| `telephone` | 手机号 |
| `tenantId` | 租户 ID |
| `tenantName` | 租户名称 |

### 4.5 依赖注入

`app/core/deps.py` — FastAPI 依赖，从请求头读取 IAM 凭证并校验：

```python
"""FastAPI 依赖：IAM token 校验，提取当前用户"""

from fastapi import Header, HTTPException, status
from . import iam

async def current_admin(
    user_token: str | None = Header(None, alias="digi-middleware-auth-user"),
    app_token: str | None = Header(None, alias="digi-middleware-auth-app"),
) -> dict:
    if not user_token:
        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "未提供 IAM userToken")

    info = await iam.analyze_token(user_token, app_token)
    if info is None:
        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "IAM token 无效或已过期")

    # 返回统一用户信息
    return {
        "username": info.get("name") or info.get("id") or "unknown",
        "userId": info.get("id"),
        "name": info.get("name"),
        "email": info.get("email"),
        "tenantId": info.get("tenantId"),
        "tenantName": info.get("tenantName"),
    }
```

### 4.6 业务路由示例

`app/routers/auth.py` — 所有需要鉴权的路由依赖 `current_admin`：

```python
from fastapi import APIRouter, Depends
from ..core.deps import current_admin

router = APIRouter(prefix="/api/admin", tags=["admin"])

@router.get("/me")
async def me(admin: dict = Depends(current_admin)):
    """返回当前 IAM 登录用户信息"""
    return {
        "userId": admin.get("userId"),
        "username": admin.get("username"),
        "name": admin.get("name"),
        "email": admin.get("email"),
        "tenantId": admin.get("tenantId"),
    }
```

### 4.7 应用入口

`app/main.py`：

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.core.iam import close_iam_client
from app.routers import auth  # 及其他路由

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    await close_iam_client()

app = FastAPI(title="你的应用", lifespan=lifespan)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(auth.router)
# app.include_router(其他路由)

@app.get("/api/health")
async def health():
    return {"status": "ok"}
```

### 4.8 启动后端

```bash
cd backend
IAM_APP_TOKEN=你的应用apptoken \
  python3 -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

---

## 五、Docker 部署

### 5.1 Dockerfile（多阶段构建）

```dockerfile
# 阶段1：构建前端
FROM node:20-alpine AS frontend-build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build

# 阶段2：Python 运行时
FROM python:3.12-slim
WORKDIR /app
COPY backend/requirements.txt ./requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
COPY backend/app ./app
COPY --from=frontend-build /app/frontend/dist ./app/static
ENV STATIC_DIR=/app/app/static
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### 5.2 docker-compose.yml

```yaml
services:
  app:
    build: .
    network_mode: host
    environment:
      - IAM_BASE_URL=https://iam.digiwincloud.com.cn
      - IAM_APP_TOKEN=${IAM_APP_TOKEN}
      - IAM_CACHE_TTL=30
    restart: unless-stopped
```

---

## 六、验证与联调

### 6.1 启动

```bash
# 后端
cd backend
IAM_APP_TOKEN=你的应用apptoken python3 -m uvicorn app.main:app --port 8000

# 前端
cd frontend
npm install && npm run dev
```

### 6.2 验证鉴权链路

```bash
# 有效 token → 200 返回用户信息
curl -s http://localhost:8000/api/admin/me \
  -H 'digi-middleware-auth-user: <userToken>' \
  -H 'digi-middleware-auth-app: <appToken>'

# 无 token → 401
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/admin/me

# 无效 token → 401
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/admin/me \
  -H 'digi-middleware-auth-user: invalid-xxx'
```

### 6.3 通过前端代理验证

```bash
# 前端代理 → 后端
curl -s http://localhost:5173/api/admin/me \
  -H 'digi-middleware-auth-user: <userToken>' \
  -H 'digi-middleware-auth-app: <appToken>'

# 前端代理 → IAM
curl -s -X POST http://localhost:5173/iam-api/api/iam/v2/identity/token/analyze \
  -H 'digi-middleware-auth-user: <userToken>' \
  -H 'digi-middleware-auth-app: <appToken>'
```

---

## 七、接入清单

### 前端

- [ ] `npm install jsencrypt react-router-dom axios antd`
- [ ] 创建 `src/services/iamAuth.ts`（替换 `APP_TOKEN` / `APPID`）
- [ ] 创建 `src/pages/Login/index.tsx`（账号密码登录页）
- [ ] 创建 `src/pages/SSOLogin/index.tsx`（SSO 回调页）
- [ ] `App.tsx` 配置 `/login`、`/sso-login` 路由 + `RequireAuth` 守卫
- [ ] `src/api/client.ts` 请求拦截器带 IAM 头，401 清理跳登录
- [ ] `vite.config.ts` 添加 `/iam-api` 代理
- [ ] `index.html` 添加 placeholder 颜色样式（可选）

### 后端

- [ ] `requirements.txt` 添加 `httpx>=0.27.0`
- [ ] `config.py` 添加 `IAM_BASE_URL` / `IAM_APP_TOKEN` / `IAM_CACHE_TTL`
- [ ] 创建 `core/iam.py`（analyze_token + 缓存）
- [ ] 创建 `core/deps.py`（current_admin 校验 IAM token）
- [ ] `main.py` lifespan 增加 `close_iam_client()`
- [ ] 业务路由 `Depends(current_admin)` 鉴权

### IAM 平台

- [ ] 注册应用，获取 `apptoken` 和 `appId`
- [ ] 配置 SSO 回调地址为 `https://你的域名/sso-login`

---

## 八、注意事项

1. **IAM 应用凭证**：`APP_TOKEN` / `APPID` 必须替换为你在鼎捷云 IAM 注册的应用凭证，不可复用其他应用的。

2. **SSO 回调地址**：IAM 认证成功后以 `?userToken=xxx` 回跳 `/sso-login`，需在 IAM 平台提前配置。

3. **缓存策略**：后端 `analyze_token` 默认缓存 30s（`IAM_CACHE_TTL`），减少对 IAM 的重复调用。token 失效后最长 30s 生效，如需即时生效可调小或关闭缓存。

4. **placeholder 颜色**：antd Input 的 `className` 传给外层 wrapper，需用 `.className input::placeholder` 后代选择器才能命中实际 `input` 元素。

5. **会话存储**：本方案使用 `sessionStorage`，关闭浏览器标签后登录态丢失。如需持久化可改为 `localStorage`（注意 XSS 风险）。

6. **生产环境代理**：生产部署时若前后端同源（Dockerfile 多阶段构建），前端 `/iam-api` 代理不再生效，需在 Nginx 或后端配置 IAM 反向代理：
   ```nginx
   location /iam-api/ {
       proxy_pass https://iam.digiwincloud.com.cn/;
   }
   ```