PAYATHON 2026

passport-onshape OAuth 认证后为何返回 400 Invalid request?

排障赵师傅

仅凭这段 400 Invalid request 响应,还无法确定具体原因。进入 Onshape 登录页,说明浏览器已到达登录流程,但不代表 OAuth 授权参数已通过校验。

代码里有几处明确的问题:Passport 和手动调试路由使用的 callback URL、scope 不一致,失败页面的路由路径也写错了。先统一这些配置,再定位 400 出现在哪一步。如果浏览器还没有返回本地 callback,优先检查授权请求和应用注册信息。

先确认 400 由哪个请求返回

打开浏览器开发者工具的 Network 面板,启用 Preserve log,重新走一遍授权流程,同时检查 Express 和 nginx 的访问日志。

实际观察到的情况 排查重点
400 来自 Onshape,浏览器没有请求本地 callback 授权参数、注册的 Redirect URLs、应用权限及登录过程中的请求
浏览器请求了 callback,并带有 error 参数 授权服务器返回的错误及 error_description
callback 已收到 code,随后服务端报错 用授权码换取 token 的请求
token 已取得,随后出现 Failed to fetch user profile 用户信息接口、访问令牌和权限

/oauth/token 和用户信息接口通常由 Node.js 服务端调用,浏览器的 Network 面板未必能看到这些请求,需要结合服务端日志判断。

如果 callback 根本没有收到请求,修改 serializeUser、deserializeUser 或获取用户资料的代码,也解决不了这次授权阶段的错误。

需要检查哪些请求参数

三个 Onshape 端点与文档一致

题目中的配置是:

ONSHAPE_AUTHORIZATION_URL=https://oauth.onshape.com/oauth/authorize
ONSHAPE_TOKEN_URL=https://oauth.onshape.com/oauth/token
ONSHAPE_USER_PROFILE_URL=https://cad.onshape.com/api/users/sessioninfo

这些地址与 Onshape OAuth 文档列出的端点一致,目前没有依据判断问题出在这三个地址上。

请求中的参数:

redirect_uri=https:%2F%2Flocalhost:443%2Fauth%2Fonshape%2Fcallback

解码后是:

https://localhost:443/auth/onshape/callback

冒号没有编码,本身不足以说明 URL 有误。直接用 URLSearchParams 编码原始参数即可,不要先调用 encodeURIComponent 再交给它,以免重复编码。

两条授权入口使用了不同的 callback

Passport 使用:

callbackURL: process.env.ONSHAPE_CALLBACK_URL_NGINX

手动调试路由使用:

redirect_uri: process.env.ONSHAPE_CALLBACK_URL

对应的地址分别是:

https://localhost:443/auth/onshape/callback
http://localhost:5001/auth/onshape/callback

这是两个不同的 Redirect URI。要让两种配置都能工作,注册信息必须分别允许这两个地址,且每条流程在授权和换取 token 时都要使用一致的地址。

如果手动入口成功返回 HTTP callback,后续却由配置了 HTTPS callback 的 Passport strategy 换取 token,就会出现 redirect_uri 不一致的问题。

排查时先只保留一个 callback,逐项核对以下地址:

  • Onshape 应用注册中的 Redirect URLs;
  • 授权请求中的 redirect_uri;
  • 换取 token 请求中的 redirect_uri;
  • 浏览器实际访问的 callback 地址。

注册了完整 URI 后,应按字符串完全一致的规则匹配,不要依赖默认端口省略、尾部斜杠或地址规范化。即使浏览器访问效果相同,https://localhost/... 与 https://localhost:443/... 也要统一写法。参见 RFC 6749 §3.1.2.3。

注册页面中的 OAuth URL 是启动授权流程的应用入口,Redirect URLs 则是授权完成后接收回调的地址。Onshape 开发者设置说明还要求 Redirect URLs 通常使用 HTTPS。HTTP localhost 的例外针对已安装桌面应用,不能据此认定所有应用类型都允许 HTTP callback。

OAuth2ReadPII 有效,逗号也不能直接判错

Onshape 中,OAuth2ReadPII 是读取用户资料的权限,OAuth2Read 是读取文档的权限。检查应用注册中的 Permissions 是否包含请求所需的权限,具体可参见 Onshape 权限说明。

两条入口的 scope 也不一致:

// Passport 入口
scope: 'OAuth2ReadPII'

// 手动入口
scope: 'OAuth2ReadPII,OAuth2Read'

手动请求因此不能作为完全等价的对照实验。

scope 的分隔符也要按当前实现核对,不宜直接套用其他 OAuth 服务的经验,把逗号改成空格。passport-onshape 的公开源码默认用逗号连接 scope 数组,项目中仍需核对已安装的版本。当前示例只有一个 scope,分隔符不会影响这条请求。

缺少 state 需要修正,是否导致 400 仍待确认

原始授权 URL 没有 state,手动请求则使用了固定值:

state: 'test123'

固定值无法有效防止 CSRF。每次授权都应生成随机的 state,将它绑定到会话,并在 callback 中校验。

当前错误响应没有指出缺少 state,因此还不能确定补上它就能解决 Onshape 的 400。

统一配置的代码示例

假设这次只测试 HTTPS nginx 入口,并且已在 Onshape 的 Redirect URLs 中登记以下完整地址:

ONSHAPE_CALLBACK_URL=https://localhost:443/auth/onshape/callback

让 strategy 统一读取这个变量:

const passport = require('passport');
const OnShapeStrategy = require('passport-onshape');

require('dotenv').config();

passport.use(
  new OnShapeStrategy(
    {
      clientID: process.env.ONSHAPE_CLIENT_ID,
      clientSecret: process.env.ONSHAPE_CLIENT_SECRET,
      callbackURL: process.env.ONSHAPE_CALLBACK_URL,
      authorizationURL: 'https://oauth.onshape.com/oauth/authorize',
      tokenURL: 'https://oauth.onshape.com/oauth/token',
      userProfileURL: 'https://cad.onshape.com/api/users/sessioninfo',
      state: true
    },
    (accessToken, refreshToken, profile, done) => {
      profile.accessToken = accessToken;
      profile.refreshToken = refreshToken;
      done(null, profile);
    }
  )
);

state: true 依赖 passport-oauth2 的会话状态存储机制来存储、验证随机 state,因此需要先启用 Express session。可对照其实现核对项目依赖。

在挂载 /auth 路由前,初始化中间件:

const session = require('express-session');

// 仅适用于应用确实位于一个可信反向代理之后的部署。
app.set('trust proxy', 1);

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,
    secure: true,
    sameSite: 'lax'
  }
}));

app.use(passport.initialize());
app.use(passport.session());
app.use('/auth', authRoutes);

这段 Cookie 配置适用于浏览器顶层跳转到 HTTPS callback 的场景。nginx 必须正确传递外部协议,浏览器也必须能正常访问本地 HTTPS 地址。如果改用 HTTP 调试,需要相应调整 Cookie 配置,secure: true 会影响会话 Cookie,不能原样照搬。

认证入口只保留一个 scope,不再显式传入固定 state:

router.get(
  '/onshape',
  passport.authenticate('onshape', {
    scope: 'OAuth2ReadPII'
  })
);

启用 Passport 管理的 state 后,从这条入口重新开始测试。原先手动构造 URL 的路由没有在 Passport 状态存储中创建对应记录,不能直接混用同一个 callback 来验证完整流程。

增加日志,定位失败阶段

在 callback 的 passport.authenticate 前加入日志,记录 code、state 是否存在,以及返回的错误:

router.get(
  '/onshape/callback',
  (req, res, next) => {
    console.info('Onshape callback reached', {
      hasCode: typeof req.query.code === 'string',
      hasState: typeof req.query.state === 'string',
      error: req.query.error,
      errorDescription: req.query.error_description
    });

    next();
  },
  passport.authenticate('onshape', {
    failureRedirect: '/auth/failure'
  }),
  (req, res) => {
    res.redirect('/protected');
  }
);

如果始终没有这条日志,继续检查浏览器中返回 400 的 Onshape 请求,此时还不需要排查 token 或用户资料接口。

如果已经收到 code,检查服务端是否执行了以下请求:

POST https://oauth.onshape.com/oauth/token
Content-Type: application/x-www-form-urlencoded

还要确认其中的 redirect_uri 与授权请求一致。Onshape 的调试说明要求:授权请求提供了 redirect_uri 时,换取 token 的 POST 请求也必须提供该参数。授权码不能重复使用,每次重试都应重新发起授权。

failureRedirect 不能替代错误处理中间件。token 交换或获取 profile 出错时,应保留 Passport 传给 Express 的错误,记录错误类型、HTTP 状态和脱敏后的响应内容。不要输出 client secret、授权码、access token、refresh token 或完整 Cookie。

修正失败页面路径

路由已通过以下代码挂载:

app.use('/auth', authRoutes);

因此,失败页面应定义为:

router.get('/failure', (req, res) => {
  res.send('<h1>Authentication Failed</h1>');
});

原来的定义:

router.get('/auth/failure', ...);

实际对应 /auth/auth/failure,与 failureRedirect: '/auth/failure' 不一致,会导致失败跳转落到错误路径。这个问题发生在本地路由中,无法解释尚未返回本地 callback 时出现的 Onshape 400。

仍然失败时,需要补充什么

进一步排查需要以下信息:

  • Network 面板中实际返回 400 的请求地址、方法、响应,以及此前的重定向链;
  • callback 是否被访问,是否收到 code 或 error;
  • 注册的 Redirect URLs、应用类型和 Permissions 配置,敏感信息需遮盖;
  • 当前实际使用的 callback 环境变量,注意核对日志打印的变量与 strategy 使用的变量,避免一个是 HTTP、另一个是 HTTPS;
  • 依赖版本和 Passport 的完整脱敏错误。

用以下命令查看依赖版本:

npm ls passport passport-onshape passport-oauth2 oauth express express-session

如果已确认 callback 从未被调用、参数与注册信息一致,并且用官方示例也能稳定复现,可携带失败时间和脱敏请求信息联系 Onshape API 支持,请其查询服务端拒绝请求的具体原因。

备注:内容仅供参考。