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_token
    const 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'));

三、关键配置说明

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