web 系统对接飞书三方登录完整步骤实战使用示例
下面我将详细说明Web系统对接飞书三方登录的完整步骤,并提供实战示例(基于Node.js/Express):
一、完整对接流程
-
注册飞书开放平台应用
- 登录飞书开放平台
- 创建企业自建应用 → 获取
App ID
和App Secret
- 配置安全域名和重定向URL(如
https://yourdomain.com/auth/feishu/callback
)
-
OAuth2.0 授权流程
sequenceDiagram 用户->>你的应用: 点击"飞书登录" 你的应用->>飞书服务器: 重定向到授权页 飞书服务器->>用户: 显示授权页面 用户->>飞书服务器: 同意授权 飞书服务器->>你的应用: 重定向回Callback URL(携带code) 你的应用->>飞书服务器: 用code换access_token 飞书服务器->>你的应用: 返回access_token和用户信息 你的应用->>用户: 创建本地会话,登录成功
二、实战代码示例(Node.js/Express)
1. 安装依赖
npm install express axios dotenv
2. 环境配置 (.env
)
FEISHU_APP_ID = cli_xxxxxx
FEISHU_APP_SECRET = xxxxxxxxxxxxxx
REDIRECT_URI = https://yourdomain.com/auth/feishu/callback
3. 核心代码实现
const express = require('express');
const axios = require('axios');
const app = express();
require('dotenv').config();// 飞书登录入口
app.get('/login/feishu', (req, res) => {const authUrl = `https://open.feishu.cn/open-apis/authen/v1/index?` +`app_id=${process.env.FEISHU_APP_ID}` +`&redirect_uri=${encodeURIComponent(process.env.REDIRECT_URI)}` +`&state=YOUR_STATE_TOKEN`; // 可选防CSRF参数res.redirect(authUrl);
});// 飞书回调处理
app.get('/auth/feishu/callback', async (req, res) => {try {const { code } = req.query;// 1. 使用code换取access_tokenconst tokenRes = await axios.post('https://open.feishu.cn/open-apis/authen/v1/access_token',{grant_type: 'authorization_code',code},{headers: {'Content-Type': 'application/json; charset=utf-8','Authorization': `Bearer ${process.env.FEISHU_APP_ID}:${process.env.FEISHU_APP_SECRET}`}});const { access_token, expires_in, refresh_token } = tokenRes.data.data;// 2. 获取用户信息const userRes = await axios.get('https://open.feishu.cn/open-apis/authen/v1/user_info',{headers: { 'Authorization': `Bearer ${access_token}` }});const userData = userRes.data.data;console.log('飞书用户信息:', userData);/* 典型返回结构:{name: "张三",en_name: "John",avatar_url: "https://xxx",open_id: "ou_xxxxxx",union_id: "on_xxxxxx",email: "user@domain.com",mobile: "+8613812345678"}*/// 3. 本地化处理(示例)// - 检查union_id是否已注册// - 创建新用户或更新现有用户// - 生成本地会话res.send(`登录成功!欢迎 ${userData.name}`);} catch (error) {console.error('飞书登录失败:', error.response.data);res.status(500).send('登录失败');}
});app.listen(3000, () => console.log('Server running on port 3000'));
三、关键配置说明
-
飞书应用权限配置
- 必须开启权限:
获取用户 user ID
、获取用户手机号
、获取用户邮箱
- 网页权限:
读取用户基础信息
- 必须开启权限:
-
安全注意事项
-
常见错误处理
错误码 原因 解决方案 60011 App ID无效 检查.env配置 10020 无效授权码 检查URL编码和重定向URI 99991400 权限不足 检查开放平台权限配置
四、前端集成示例(React)
function LoginPage() {const feishuLogin = () => {// 替代方案:后端提供/auth/feishu接口做302跳转更安全window.location.href = `https://your-backend.com/login/feishu`;};return (<button onClick={feishuLogin} style={styles.feishuButton}><img src="feishu-logo.png" alt="飞书登录"/>飞书账号登录</button>);
}const styles = {feishuButton: {backgroundColor: '#00D6C6',padding: '10px 20px',borderRadius: '4px',color: 'white',display: 'flex',alignItems: 'center'}
};
五、调试技巧
-
使用飞书沙箱环境
- 修改API端点:
https://open-sandbox.feishu.cn/...
- 测试账号需添加到应用可见范围
- 修改API端点:
-
日志记录关键节点
// 在关键步骤添加日志 console.log('Received code:', code); console.log('Access token response:', tokenRes.data);
-
Postman测试Token获取
POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/ Headers: Content-Type: application/json; charset=utf-8 Body: {"app_id": "cli_xxx","app_secret": "xxxxx" }
完成上述步骤后,你的Web系统即可实现专业级的飞书三方登录功能。实际部署时需补充错误处理、会话管理、用户绑定等业务逻辑。