web 系统对接飞书三方登录完整步骤实战使用示例

下面我将详细说明Web系统对接飞书三方登录的完整步骤，并提供实战示例（基于Node.js/Express）：

一、完整对接流程

---

1. 注册飞书开放平台应用

   • 登录飞书开放平台
   • 创建企业自建应用 → 获取 App ID 和 App Secret
   • 配置安全域名和重定向URL（如 https://yourdomain.com/auth/feishu/callback）

2. 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: "[e-mail]",mobile: "[phone]"}*/// 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'));

---

三、关键配置说明

1. 飞书应用权限配置

   • 必须开启权限：获取用户 user ID、获取用户手机号、获取用户邮箱
   • 网页权限：读取用户基础信息

2. 安全注意事项

3. 常见错误处理

   错误码	原因	解决方案
   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'}
};

---

五、调试技巧

1. 使用飞书沙箱环境

   • 修改API端点：https://open-sandbox.feishu.cn/...
   • 测试账号需添加到应用可见范围

2. 日志记录关键节点

   // 在关键步骤添加日志
   console.log('Received code:', code);
   console.log('Access token response:', tokenRes.data);
   

3. 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系统即可实现专业级的飞书三方登录功能。实际部署时需补充错误处理、会话管理、用户绑定等业务逻辑。