企业微信 OAuth 2.0 集成指南

快速开始

前置条件

1. 已有企业微信账号
2. 在企业微信管理后台创建了应用
3. 获取了企业 ID（CorpID）和应用 Secret

配置步骤

1. 配置企业微信应用

在 src/js/wecom-config.js 中填入你的企业信息：

export const WECOM_CONFIG = {
    // 从企业微信管理后台获取
    corpId: 'ww1234567890abcdef',
    agentId: '1000001',
    redirectUri: 'https://your-domain.com/',
    apiBaseUrl: '/api'
};

2. 在企业微信管理后台配置回调

1. 登录 企业微信管理后台
2. 点击 应用管理 → 选择你的应用
3. 进入 设置 标签
4. 在 OAuth 2.0 授权企业号管理员登录 中：

• 勾选 启用
• 填入 授权完成后的跳转链接（必须是你的应用域名）
• 填入 可信域名（用于 JSSDK 等功能）

3. 配置后端服务

参考 WECOM_OAUTH_GUIDE.md 中的后端实现示例。

使用流程

场景 1: 自动授权流程（推荐）

在企业微信中打开应用时自动进行授权：

// src/main.js 会自动处理以下流程：
// 1. 检查是否有授权码
// 2. 如果有授权码，交换用户信息
// 3. 如果没有授权码，重定向到授权页面
// 4. 获取用户信息后显示

场景 2: 手动授权链接

如果需要在页面中显示授权按钮：

import WeChatOAuth from './js/wechat-oauth.js';
import { WECOM_CONFIG } from './js/wecom-config.js';

const oauth = new WeChatOAuth(WECOM_CONFIG);
const authUrl = oauth.getAuthUrl();

// 创建授权链接
const authLink = document.createElement('a');
authLink.href = authUrl;
authLink.textContent = '点击授权登录';
document.body.appendChild(authLink);

获取用户信息

授权成功后，可以通过以下方式获取用户信息：

// 方式 1: 从全局变量访问
const user = window.currentUser;
console.log('用户ID:', user.userid);
console.log('用户名:', user.name);
console.log('手机号:', user.mobile);

// 方式 2: 从 OAuth 实例获取
import WeChatOAuth from './js/wechat-oauth.js';
const oauth = new WeChatOAuth(config);
const userInfo = oauth.getUserInfo();

// 方式 3: 从 sessionStorage 获取
const userInfo = JSON.parse(sessionStorage.getItem('wecom_user_info'));

用户信息说明

获取的用户信息包含以下字段：

字段	说明	示例
userid	企业微信用户ID	user123@company
name	用户姓名	张三
mobile	用户手机号	13800138000
email	用户邮箱	zhang@company.com
department	用户部门	技术部
position	用户职位	工程师

安全说明

1. 防止 CSRF 攻击

系统会自动生成和验证 state 参数：

// 前端会自动：
// 1. 生成随机 state
// 2. 保存到 sessionStorage
// 3. 在回调时验证 state

// 防止恶意网站冒充授权

2. 数据安全

• ✅ 使用 HTTPS 传输所有数据
• ✅ 授权码存储在 sessionStorage（浏览器关闭时清除）
• ✅ 用户信息存储在 sessionStorage（不持久化）
• ✅ 敏感信息不存储在 localStorage

3. API 安全

• ✅ 后端必须验证 access_token
• ✅ 实现速率限制防止 API 滥用
• ✅ 记录审计日志
• ✅ 定期更新 Secret

故障排查

问题 1: 重定向错误

错误信息: redirect_uri mismatch

解决方案:
1. 检查 WECOM_CONFIG.redirectUri 是否与企业微信后台配置一致
2. 确保协议、域名、路径都完全匹配（包括末尾 /）
3. 清除浏览器缓存重试

问题 2: 获取用户信息失败

错误信息: 获取用户信息失败

解决方案:
1. 检查后端 /api/wecom/getUserInfo 端点是否正常
2. 验证后端是否获取到了正确的 access_token
3. 查看浏览器控制台的完整错误信息
4. 检查网络标签中的请求/响应

问题 3: 授权码过期

错误信息: 授权码已过期

解决方案:
1. 授权码有效期为 10 分钟
2. 需要在授权后立即交换用户信息
3. 如果超时，需要重新授权

问题 4: Secret 不正确

错误信息: invalid secret

解决方案:
1. 确认 Secret 是从应用详情中复制的
2. 不要包含空格或特殊字符
3. 如果已泄露，应在企业微信后台重置

高级配置

1. 自定义错误处理

// src/js/app.js 中修改 handleAuthCallback 函数
async function handleAuthCallback(code) {
    try {
        const userInfo = await oauth.exchangeCodeForUserInfo(code);
        // 自定义成功处理逻辑
    } catch (error) {
        if (error.message.includes('40014')) {
            // 处理无效的用户ID
        } else if (error.message.includes('40001')) {
            // 处理过期的 access_token
        }
    }
}

2. 集成业务系统

// 获取用户信息后同步到业务系统
async function syncUserToBackend(userInfo) {
    const response = await apiClient.post('/user/sync', {
        userid: userInfo.userid,
        name: userInfo.name,
        mobile: userInfo.mobile
    });
    return response;
}

3. 实现权限控制

// 检查用户是否有权限访问某功能
async function checkPermission(feature) {
    const user = window.currentUser;
    const response = await apiClient.get(`/permission/check/${feature}/${user.userid}`);
    return response.data.authorized;
}

性能优化

1. 缓存用户信息

用户信息已自动缓存到 sessionStorage，刷新页面时会自动恢复。

2. 延迟加载

对于不是立即需要的功能，可以使用延迟加载：

// 只在需要时才加载历史记录
if (oauth.isAuthorized()) {
    loadHistory();
}

3. 减少 API 调用

// 合并多个 API 请求
async function fetchUserData(userId) {
    return Promise.all([
        apiClient.get(`/user/${userId}`),
        apiClient.get(`/user/${userId}/permission`),
        apiClient.get(`/user/${userId}/settings`)
    ]);
}

部署指南

1. 生产环境构建

npm run build

生成的文件在 dist/ 目录中。

2. 服务器配置

配置 Web 服务器处理 SPA 路由：

Nginx:
nginx location / { try_files $uri $uri/ /index.html; }

Apache:
apache <IfModule mod_rewrite.c> RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L] </IfModule>

3. HTTPS 配置

企业微信要求使用 HTTPS。使用 Let's Encrypt 配置 SSL：

certbot certonly --standalone -d your-domain.com

参考资源

• 企业微信开发文档
• OAuth 2.0 规范
• OWASP 安全指南

支持

如有问题，请：
1. 查看浏览器控制台错误日志
2. 参考企业微信官方文档
3. 检查网络请求（F12 → Network）
4. 查阅本指南的故障排查部分