OpenMax
免费试用

端到端示例

用 Node.js(Express + jose)和 Go 写的完整登录示例:发起授权、回调换 token、验 id_token、绑定账号、过期拦截。

端到端示例

这页给两段可以照着改的服务端代码:Node.js 版走完整条登录链路,Go 版只写回调换 token 和验 id_token。两段都是「新标签(顶层)」打开时的写法;嵌入时不要在 iframe 里跳转,改用「嵌入时登录」里的 requestAuthCode。

Node.js(Express + jose)

import crypto from "node:crypto";
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.OPENMAX_ISSUER;            // OpenMax 的地址:https://openmax.com
const APP_ID = process.env.OPENMAX_APP_ID;
const APP_SECRET = process.env.OPENMAX_APP_SECRET;    // 只放后端
const REDIRECT_URI = "https://my-app.example.com/auth/openmax/callback"; // 与 manifest 逐字节一致
const ALLOWED_ORG_IDS = new Set(process.env.OPENMAX_ORG_IDS.split(",")); // 组织应用 = 所属的那一个组织
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/api/v1/apps/jwks`));
const rnd = () => crypto.randomBytes(32).toString("base64url");

// iframe 内是第三方 cookie
const FLOW_COOKIE = { httpOnly: true, secure: true, sameSite: "none", partitioned: true, maxAge: 600_000 };

function safeReturnTo(p) {
  if (typeof p !== "string" || !p.startsWith("/") || p.startsWith("//") || p.startsWith("/\\")) return "/";
  if (/[\\\u0000-\u001f\u007f]/.test(p) || p.split(/[?#]/)[0].split("/").includes("..")) return "/";
  return p;
}

// 1) 没有会话:顶层(新标签)时前端把自己的窗口导航到这里(带失败标记时不要自动来);嵌入时不要来,用「嵌入时登录」的 requestAuthCode
app.get("/auth/openmax/login", async (req, res) => {
  const flow = { id: rnd(), state: rnd(), nonce: rnd(), verifier: rnd(),
                 returnTo: safeReturnTo(req.query.return_to) };
  await flows.put(flow.id, flow, { ttlSeconds: 600 });      // 服务端保存,单次使用
  res.cookie("app_login_flow", flow.id, FLOW_COOKIE);
  const challenge = crypto.createHash("sha256").update(flow.verifier).digest("base64url");
  const q = new URLSearchParams({
    response_type: "code", client_id: APP_ID, redirect_uri: REDIRECT_URI,
    state: flow.state, nonce: flow.nonce,
    code_challenge: challenge, code_challenge_method: "S256",
    scope: "org:me:read org:me.email:read",
  });
  res.redirect(`${ISSUER}/api/v1/apps/authorize?${q}`);
});

// 2) 回调:GET {redirect_uri}?code&state&iss  或  ?error&error_description&iss[&state]   (state 合法时才带回)
app.get("/auth/openmax/callback", async (req, res) => {
  const flow = await flows.take(req.cookies.app_login_flow);  // 取出即删除
  res.clearCookie("app_login_flow", FLOW_COOKIE);
  const fail = (why) => res.redirect(`/?login_error=${encodeURIComponent(why)}`); // 首页带标记不自动重试
  if (!flow) return fail("state");
  if (req.query.iss !== ISSUER) return fail("state");
  const s = String(req.query.state ?? "");
  if (s.length !== flow.state.length ||
      !crypto.timingSafeEqual(Buffer.from(s), Buffer.from(flow.state))) return fail("state");
  if (req.query.error) return fail(String(req.query.error));   // login_required / access_denied / ...

  const r = await fetch(`${ISSUER}/api/v1/apps/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code", code: String(req.query.code),
      redirect_uri: REDIRECT_URI, code_verifier: flow.verifier,
      client_id: APP_ID, client_secret: APP_SECRET,
    }),
  });
  if (!r.ok) return fail("token");
  const tok = await r.json();
  const { payload } = await jwtVerify(tok.id_token, JWKS, {
    issuer: ISSUER, audience: APP_ID, algorithms: ["RS256"], clockTolerance: 30,
  });
  if (payload.nonce !== flow.nonce || payload.sub !== payload.member_id) return fail("token");
  if (!ALLOWED_ORG_IDS.has(payload.org_id)) return fail("org");      // 固定组织:别的组织的成员不放行

  // 账号绑定:只认 (issuer, org_id, member_id);邮箱只展示,不用来自动关联已有账号(见「已有系统接入」)
  let account = await accounts.findByBinding(ISSUER, payload.org_id, payload.member_id);
  if (!account) {
    if (POLICY.provisioning !== "auto") return fail("not_bound");    // 手动预绑定:显示「请联系管理员开通」
    account = await accounts.provision({                            // 一个事务:账号 + 绑定 + 默认角色 + 默认项目;
      issuer: ISSUER, orgId: payload.org_id, memberId: payload.member_id, // 绑定有唯一约束,两个标签页同时首次进入只会建一个
      name: payload.name, email: payload.email,
      role: POLICY.defaultRole, projects: POLICY.defaultProjects,    // 不加入全部历史项目
    });
  }
  if (account.disabled) return fail("account_disabled");            // 应用内已停用:不重试

  await regenerateSession(req);                                      // 换新会话 ID,防会话固定
  req.session.user = { accountId: account.id, orgId: payload.org_id, memberId: payload.member_id };
  // 会话上限 = token 过期(15 分钟);到期由 requireSession 拦下重新授权
  req.session.openmax = { access_token: tok.access_token, expires_at: payload.exp * 1000 };
  if (tok.refresh_token) await saveRefreshToken(account.id, tok.refresh_token); // 仅 offline_access;每次刷新都换新的
  res.redirect(flow.returnTo === "/" ? POLICY.landingPath : flow.returnTo); // 只用服务端保存的路径
});

// 3) 每个业务请求先过这里:过期会话一律拦截、作废,再重新授权
function requireSession(req, res, next) {
  const s = req.session.openmax;
  if (req.session.user && s && Date.now() < s.expires_at - 30_000) return next();
  req.session.user = null; req.session.openmax = null;               // 过期 / 不完整的会话直接作废
  if (req.get("accept")?.includes("application/json"))
    return res.status(401).json({ error: "reauth_required" });       // 接口:前端收到后整页导航去授权
  if (req.query.login_error || req.query.signed_out)
    return res.status(401).send(loginHelpPage(req.query.login_error)); // 有失败 / 退出标记:只给「重新登录」按钮
  res.redirect(`/auth/openmax/login?return_to=${encodeURIComponent(req.originalUrl)}`); // 无感重新授权
}

// 4) 复核身份(可选):200 只说明此刻仍有效,不延长 expires_at —— 复核 ≠ 续期
const me = await fetch(`${ISSUER}/api/v1/me`, {
  headers: { Authorization: `Bearer ${req.session.openmax.access_token}` },
});
if (me.status === 401) { /* 授权已失效(停用 / 卸载 / 成员离开 / 过期):作废会话,显示无权限或重走一次授权 */ }
if (me.status === 403) { /* 缺 scope,显示无权限,不重试 */ }

flows、accounts、POLICY、regenerateSession、loginHelpPage 是你自己的存储、接入策略表(见「已有系统接入」)的配置和会话工具(如 express-session 的 req.session.regenerate)。

  • 会话 cookie 在 iframe 内同样要 Secure; HttpOnly; SameSite=None; Partitioned,maxAge 不超过 15 分钟(或干脆用会话 cookie)。
  • /auth/openmax/* 和回调本身不要挂 requireSession。
  • 前端(顶层 / 新标签):无会话且 URL 没有 login_error / signed_out 时,location.href = "/auth/openmax/login?return_to=" + encodeURIComponent(location.pathname + location.search);接口返回 reauth_required 时同样整页导航。
  • 嵌入时不要导航 iframe:改向宿主要授权码,后端接口见「嵌入时登录」里的示例。

Go(回调换 token + 验 id_token)

import "github.com/coreos/go-oidc/v3/oidc"

keys := oidc.NewRemoteKeySet(ctx, issuer+"/api/v1/apps/jwks")
verifier := oidc.NewVerifier(issuer, keys, &oidc.Config{ClientID: appID, SupportedSigningAlgs: []string{"RS256"}})

func callback(w http.ResponseWriter, r *http.Request) {
    flow, ok := takeFlow(r)                 // 按流程 cookie 取出并删除
    q := r.URL.Query()
    if !ok || q.Get("iss") != issuer ||
        subtle.ConstantTimeCompare([]byte(q.Get("state")), []byte(flow.State)) != 1 {
        http.Redirect(w, r, "/?login_error=state", http.StatusFound); return
    }
    if e := q.Get("error"); e != "" {
        http.Redirect(w, r, "/?login_error="+url.QueryEscape(e), http.StatusFound); return
    }
    resp, err := http.PostForm(issuer+"/api/v1/apps/token", url.Values{
        "grant_type": {"authorization_code"}, "code": {q.Get("code")},
        "redirect_uri": {redirectURI}, "code_verifier": {flow.Verifier},
        "client_id": {appID}, "client_secret": {appSecret},
    })
    // 检查 err / resp.StatusCode,解码 {access_token, id_token, expires_in, refresh_token, user}
    idt, err := verifier.Verify(r.Context(), tok.IDToken)   // 签名、iss、aud、exp
    if err != nil { /* 失败 */ }
    var claims struct {
        MemberID string `json:"member_id"`
        OrgID    string `json:"org_id"`
        Name     string `json:"name"`
        Email    string `json:"email"`
        Nonce    string `json:"nonce"`
    }
    if idt.Claims(&claims) != nil || claims.Nonce != flow.Nonce || idt.Subject != claims.MemberID { /* 失败 */ }
    if !allowedOrgIDs[claims.OrgID] { /* 失败:不是本部署服务的组织 */ }
    // 按 (issuer, claims.OrgID, claims.MemberID) 查绑定 → 按接入策略表处理未绑定 / 已停用
    // 建会话,过期时间 = idt.Expiry(15 分钟),跳回 flow.ReturnTo
}

Go 生成 PKCE:verifier := oauth2.GenerateVerifier(),oauth2.S256ChallengeOption(verifier)(golang.org/x/oauth2 ≥ 0.13)。