passport-saml登录回调session id变更导致认证失败问题

• 集成passport-saml与express-session实现SAML单点登录时出现认证流程断裂
• 用户发起登录流程时请求携带初始生成的session id，身份提供商（IDP）的认证响应到达登录回调接口时，服务端当前请求绑定的sessionId已变更为全新值
• 浏览器本地存储的session cookie仍保留初始session id，无法匹配回调阶段生成的新session id，最终身份认证流程无法正常完成

1. Cookie跨站配置不兼容：IDP发起的回调是跨站POST请求，如果express-session的cookie配置中sameSite设为Strict，或使用默认Lax配置（新版本Chrome等浏览器对跨站POST请求不会携带Lax级别的cookie），服务端收不到请求携带的初始session cookie，会自动生成全新session。如果生产环境开启secure: true但服务未正确识别HTTPS协议，也会导致cookie无法被浏览器携带。
2. 异步逻辑时序错误：SAML策略验证回调中，查询、删除旧session的逻辑是异步执行，但代码未等待该异步操作完成就提前调用done()返回用户信息，且逻辑存在缺陷：只要找到旧session进入destroy回调，无论销毁成功还是失败都会直接返回错误中断流程，异步时序错乱会触发session状态写入竞争。
3. RelayState逻辑错误：现有代码直接从RelayState参数读取IDP标识，覆盖了passport-saml默认通过RelayState绑定初始请求上下文、关联session的逻辑，导致回调阶段无法匹配初始登录请求的session。
4. session保存时序问题：回调接口中调用req.logIn后直接跳转，未等待session持久化完成就返回响应，存在session还未写入存储、cookie未更新就触发跳转的概率，导致前后session不匹配。

1. 修正express-session基础配置 #

添加适配跨站SAML回调的参数，若服务前有Nginx、Ingress等反向代理，需开启信任代理配置：

// 放在session配置前，生产环境反向代理场景必加
app.set('trust proxy', 1);

app.use(session({
  secret: process.env.SESSION_SECRET!,
  resave: false,
  saveUninitialized: false,
  store: yourSessionStore, // 替换为实际使用的session存储（Redis、Mongo等）
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production", // 生产环境HTTPS开启，本地开发设为false
    sameSite: process.env.NODE_ENV === "production" ? "none" : "lax", // 生产环境跨站回调必须设为none，且必须搭配secure:true
    maxAge: 24 * 60 * 60 * 1000 // 按业务需求调整过期时间
  }
}));

注意：sameSite: none必须搭配secure: true使用，否则浏览器会直接拒绝写入该cookie。

2. 修正SAML策略中的异步逻辑bug #

将旧session删除逻辑改为同步等待执行，修正错误返回逻辑，删除旧session失败不阻断正常登录流程：

// 原有的旧session删除逻辑替换为以下内容
if (!user) return done(new UserNotFoundError());

// 等待旧session清理完成再继续
await new Promise((resolve) => {
  sessionStore.all!((err: any, sessions: any) => {
    if (err) {
      console.error("query sessions failed:", err);
      return resolve(true);
    }
    const existingSess = (sessions as Array<{
      sid: string;
      passport?: { user?: { email?: string } };
    }>).find(sess => sess.passport?.user?.email === email);
    
    if (!existingSess?.sid) return resolve(true);
    sessionStore.destroy(existingSess.sid, (destroyErr) => {
      if (destroyErr) console.error("delete old session failed:", destroyErr);
      resolve(true);
    });
  });
});

// 所有异步操作完成后再返回认证结果
return done(null, { nameID, nameIDFormat, email, firstName, lastName });

3. 修正RelayState逻辑，保留session关联能力 #

不要占用RelayState传递IDP标识，改为将IDP信息存在初始请求的session中，保留passport-saml默认的RelayState上下文绑定能力：

1. 修改登录发起路由，提前将IDP标识写入session：

app.get(
  "/auth/saml/login/:providerId",
  (req, res, next) => {
    req.session.samlProviderId = req.params.providerId;
    // 等待session保存完成再跳转IDP
    req.session.save((err) => {
      if (err) return next(err);
      passport.authenticate("saml", { failureRedirect: "/", failureFlash: true })(req, res, next);
    });
  },
  function (req, res) {
    res.redirect("/");
  }
);

2. 修改MultiSamlStrategy的getSamlOptions逻辑，从session读取IDP配置：

getSamlOptions: function (request, done) {
  const providerId = request.session.samlProviderId;
  const provider = providers.find((p) => p.name === providerId);
  if (!provider) {
    return done(new Error("saml identity provider not found"));
  }
  return done(null, provider.config);
},

4. 修正回调路由的session保存时序 #

登录完成后显式等待session保存成功再跳转，避免时序问题：

app.post("/login/callback", function (req, res, next) {
  passport.authenticate("saml", (err: any, user: ISessionUser) => {
    if (err) {
      logger.info({ label: "SAML Authenticate Error:", error: err });
      return next(err);
    }
    req.logIn(user, (err) => {
      if (err) {
        logger.info({ label: "Login Error:", data: err });
        return next(err);
      }
      // 等待session持久化、cookie写入完成再跳转
      req.session.save((saveErr) => {
        if (saveErr) return next(saveErr);
        res.redirect("/");
      });
    });
  })(req, res, next);
});

• 打开浏览器开发者工具，对比跳转IDP前Set-Cookie的session id，和IDP回调请求携带的Cookie中的session id是否一致
• 生产环境确认回调请求为HTTPS协议，否则secure cookie不会被浏览器携带
• 若配置了CORS规则，需给回调接口开启credentials: true允许跨站携带cookie

内容的提问来源于stack exchange，提问作者JohnStephen.19