快速开始
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
- 在 Workspace 的应用页点「提交应用」,粘贴
manifest.json。页面会当场校验,有错会标到字段上。 - 审批通过后,在应用页的「我提交的」tab 里能看到 App ID(
app_…)。 - 在同一个 tab 里点「生成 App Secret」。它只显示一次,马上存好,只放服务端。
- 组织应用审批通过后会自动装到本组织,不用再另外安装。
详见提交审批与安装。
第 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 |
应用没在本组织安装或已停用,或你的角色看不到任何入口 |
