OpenMax
免费试用

快速开始

5 分钟跑通一个最小的 OpenMax Workspace 应用:写 manifest、提交、用 OpenMax 登录,在页面上显示当前成员。

快速开始

跟着下面 5 步,做一个最小的 Workspace 应用:在 Workspace 里点开它,用 OpenMax 登录,页面上显示「你好,<你的名字>」。代码只有一个 Node.js 文件。

这一页为了短,只走「新标签打开」。要嵌在 Workspace 页面里打开,登录要改用 requestAuthCode,见第 5 步。

准备

  • Node.js 20 或更高。
  • 一个能从外网用 https 访问的域名,指到你跑服务的机器,例如 https://hello.example.com。url 和 redirect_uri 不能用 localhost、IP 或内网域名(规则见应用类型与 manifest)。本机开发可以用一个对外的 https 隧道:按现在的主机规则,隧道服务的域名不会被拒,但平台没有明确承诺。
  • 你在一个 OpenMax 组织里。组织管理员自己提交的应用会自动通过;不是管理员的话,第 2 步要等管理员批。
  • 如果由 AI Agent 代做:提交可以由 Agent 完成;审批、生成 App Secret、首次打开验收(第 4 步)要由人类成员来做。

第 1 步:写 manifest

把下面存成 manifest.json,把 hello.example.com 换成你的域名:

{
  "schema": "openmax.app.v1",
  "slug": "hello-openmax",
  "name": { "zh": "你好 OpenMax", "en": "Hello OpenMax" },
  "description": "显示当前登录成员的最小示例",
  "icon": "你",
  "version": "1.0.0",
  "url": "https://hello.example.com/",
  "redirect_uri": "https://hello.example.com/callback",
  "open": ["external"],
  "entries": [{ "path": "/", "title": "首页" }],
  "scopes": ["org:me:read"]
}
  • open 只写 external:在新标签打开,先不处理嵌入。
  • redirect_uri 和 url 同一个主机,后面代码里要逐字节一样。

第 2 步:提交,拿到 App ID 和 App Secret

  1. 在 Workspace 的应用页点「提交应用」,粘贴 manifest.json。页面会当场校验,有错会标到字段上。
  2. 审批通过后,在应用页的「我提交的」tab 里能看到 App ID(app_…)。
  3. 在同一个 tab 里点「生成 App Secret」。它只显示一次,马上存好,只放服务端。
  4. 组织应用审批通过后会自动装到本组织,不用再另外安装。

详见提交审批与安装。

第 3 步:写服务

mkdir hello-openmax && cd hello-openmax
npm init -y && npm pkg set type=module
npm install express@5 jose

新建 server.js:

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

const ISSUER = process.env.OPENMAX_ISSUER || "https://openmax.com"; // OpenMax 的地址:https://openmax.com
const APP_ID = process.env.OPENMAX_APP_ID;
const APP_SECRET = process.env.OPENMAX_APP_SECRET; // 只放服务端
const ORG_ID = process.env.OPENMAX_ORG_ID; // 你的组织 id:只放行这个组织的成员
const REDIRECT_URI = "https://hello.example.com/callback"; // 和 manifest 逐字节一样
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/api/v1/apps/jwks`));
const rnd = () => crypto.randomBytes(32).toString("base64url");
const same = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && crypto.timingSafeEqual(x, y); }; // 常量时间比较 state
const flows = new Map(); // 示例用内存;正式应用放服务端存储,10 分钟过期、只用一次
const sessions = new Map();
const cookieOf = (req, name) => (req.headers.cookie || "").split("; ").find((c) => c.startsWith(name + "="))?.slice(name.length + 1);
const COOKIE = "Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=900";

const app = express();

// 首页:有会话就打招呼,没有就去登录
app.get("/", (req, res) => {
  const user = sessions.get(cookieOf(req, "sid"));
  if (!user) return res.redirect("/login");
  res.send(`<h1>你好,${user.name.replace(/[<>&"]/g, "")}</h1><p>组织:${user.orgId}</p>`);
});

// 发起授权:授权码 + PKCE,带 state、nonce
app.get("/login", (req, res) => {
  const flow = { id: rnd(), state: rnd(), nonce: rnd(), verifier: rnd() };
  flows.set(flow.id, flow);
  res.setHeader("Set-Cookie", `flow=${flow.id}; ${COOKIE}`);
  const q = new URLSearchParams({
    response_type: "code", client_id: APP_ID, redirect_uri: REDIRECT_URI,
    state: flow.state, nonce: flow.nonce,
    code_challenge: crypto.createHash("sha256").update(flow.verifier).digest("base64url"),
    code_challenge_method: "S256",
  });
  res.redirect(`${ISSUER}/api/v1/apps/authorize?${q}`);
});

// 回调:核 iss 和 state,换 token,验 id_token,核 sub 和组织
app.get("/callback", async (req, res) => {
  const fail = (why) => { console.log("sign-in failed:", why); res.status(400).send("登录失败,请重新打开"); }; // 失败原因只打在服务端日志里,浏览器只看到「登录失败」
  const flow = flows.get(cookieOf(req, "flow"));
  flows.delete(cookieOf(req, "flow"));
  if (!flow || req.query.iss !== ISSUER || !same(String(req.query.state ?? ""), flow.state)) return fail("flow, iss or state");
  if (req.query.error) return res.status(403).send(`登录失败:${String(req.query.error).replace(/[<>&"]/g, "")}`);
  try {
    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 " + r.status + " " + (await r.text())); // 响应体只有 error 和 error_description,不含密钥
    const { id_token, access_token } = await r.json();
    const { payload } = await jwtVerify(id_token, JWKS, { issuer: ISSUER, audience: APP_ID, algorithms: ["RS256"] });
    if (payload.nonce !== flow.nonce || payload.sub !== payload.member_id) return fail("nonce or sub");
    if (payload.org_id !== ORG_ID) {
      console.log("rejected org_id:", payload.org_id); // 第一次可以不设 OPENMAX_ORG_ID 跑,从这行日志拿到自己组织的 id
      return res.status(403).send("不是本组织的成员"); // 别的组织的成员不放行
    }
    const me = await fetch(`${ISSUER}/api/v1/me`, { headers: { Authorization: `Bearer ${access_token}` } }); // 用 access_token 调接口
    if (me.ok) console.log("me:", (await me.json()).data.display_name); // /api/v1/me 的字段包在 data 里
    const sid = rnd();
    sessions.set(sid, { name: payload.name, orgId: payload.org_id, memberId: payload.member_id });
    res.setHeader("Set-Cookie", `sid=${sid}; ${COOKIE}`);
    res.redirect("/");
  } catch (e) {
    fail(e.code || e.message); // 验签失败、过期、网络出错:一律当登录失败,不把错误细节给浏览器
  }
});

app.listen(3000, () => console.log("listening on :3000"));

运行(把 3000 端口挂到你的 https 域名后面)。OPENMAX_ORG_ID 是你组织的 id:第一次可以先不设,登录一次,从服务端日志 rejected org_id: 那行拿到,再带上它重启。登录成功后,服务端日志会打出 me: 和你的名字,这是用 access_token 调 /api/v1/me 拿到的(字段在返回体的 data 里,见登录)。

OPENMAX_APP_ID=app_xxx OPENMAX_APP_SECRET=xxx OPENMAX_ORG_ID=你的组织id node server.js

第 4 步:在 Workspace 里打开

在 Workspace 左栏点「你好 OpenMax」,再点「新标签打开」。第一次会跳到 OpenMax 授权,回来后页面显示「你好,<你的名字>」。

打不开时先看这几样:

现象 多半是
授权页报 redirect_uri 不对 代码里的 REDIRECT_URI 和 manifest 不是逐字节一样
回调报「登录失败」,日志是 sign-in failed: flow, iss or state 回调检查没过:流程 cookie 没带回来(域名不是 https,或换了浏览器),iss 不等于 OPENMAX_ISSUER,或 state 不对
回调报「登录失败」,日志是 sign-in failed: 后跟 nonce or sub 或验签错误 id_token 没过:签名、aud、过期、nonce 或 sub 不对
显示「不是本组织的成员」 第一次运行(还没设 OPENMAX_ORG_ID)出现是正常的,从服务端日志 rejected org_id: 那一行拿到组织 id;设了还出现,就是设错了
授权页提示「切换到 {组织} 并继续」(APP_ORGANIZATION_MISMATCH) 应用属于你的另一个组织,点切换即可
回调报「登录失败」,日志是 sign-in failed: token … 换 token 失败,日志里有状态码和 error:App Secret 不对;code 用过一次(只能用一次)或拿到后超过 60 秒才换;换 token 时的 REDIRECT_URI 和授权时不一样
授权回 access_denied 应用没在本组织安装或已停用,或你的角色看不到任何入口

第 5 步:下一步

  • 嵌进 Workspace 页面里打开:open 加 embed,改用 requestAuthCode 登录,见登录「嵌入时登录」。
  • 会话过期、复核身份、错误处理的完整写法:见端到端示例和登录。
  • 上线前过一遍上线清单。
  • 怎么选接入方式、参考实现和常见的坑:见开发者首页「按你的情况选一条路」。