员工与会员登录
让员工用 Betly 后台账号、会员用手机号验证码登录你的应用,不用另建账号和密码。协议是标准的 OAuth 2.0 授权码模式,必须带 PKCE。Betly 不签发 ID Token,应用用访问令牌调 /api/v1/me 获取身份。
前提
- 应用已登记 OAuth 回调地址,拿到 client_id 与 client_secret。
- 管理员在【授权】→【可登录账号】里开放了对应的账号类型,并已启用授权。
- 员工还需要角色里有该应用的“进入应用”权限项;会员登录要求场馆已开通手机号登录,并配置好短信服务,否则会员收不到验证码。
登录流程
text
浏览器 → 应用:点“用 Betly 账号登录”
应用 → 浏览器:302 到 Betly 授权入口(带 state、code_challenge、account_type)
浏览器 ↔ Betly:员工沿用后台登录态;会员输入手机号验证码并确认授权
Betly → 浏览器:302 回应用的回调地址(带 code、state)
应用服务端 → Betly:用 code + code_verifier + client_secret 换访问令牌
应用服务端 → Betly:GET /api/v1/me,拿到员工或会员身份第一步:跳转到授权入口
text
https://admin.mx5.cn/oauth/authorize
?response_type=code
&client_id=<client_id>
&redirect_uri=<登记过的回调地址,逐字一致>
&state=<随机串,回调时校验>
&code_challenge=<BASE64URL(SHA256(code_verifier))>
&code_challenge_method=S256
&scope=email
&account_type=memberaccount_type:staff员工登录(默认),member会员登录。同一个应用同时开放两类账号时,用它决定展示哪种登录界面。它只影响界面,Betly 签发令牌时按实际登录的账号判定身份。scope不决定应用能读什么数据,能读什么只看管理员授予的权限范围。state和code_verifier保存在应用服务端的会话里,一次登录一组,用完即删。
员工已登录 Betly 后台时,不会看到任何页面,直接回到应用。会员每次都会看到授权确认页,列出应用将获得的信息。
第二步:处理回调
回调地址收到 code 和 state。先核对 state 与发起时保存的一致,再换令牌。
收到 error=access_denied 表示没有登录成功:会员拒绝了授权,或员工没有进入该应用的权限。给出提示并提供“重新登录”即可,不要自动重试。
第三步:换取访问令牌
http
POST /auth/v1/oauth/token HTTP/1.1
Host: supa.mx5.cn
Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<code>&redirect_uri=<回调地址>&code_verifier=<code_verifier>返回 access_token(约 1 小时有效)、refresh_token、expires_in。授权码只能用一次。
第四步:获取身份
http
GET /api/v1/me HTTP/1.1
Host: api.mx5.cn
Authorization: Bearer <access_token>json
{ "sub": "…", "org_id": "…", "name": "张三", "audience": "staff" }
{ "sub": "…", "org_id": "…", "name": "", "audience": "member", "phone_masked": "138****8000" }sub是本组织内的员工或会员编号,用它关联应用自己的用户记录。不要用姓名或手机号关联。audience区分员工和会员;同一个人的员工身份和会员身份是两个不同的sub。- 新注册的会员可能没有昵称,
name为空字符串。
查询当前员工的企微身份
需要以当前员工身份提交企微审批时,在服务端使用员工 OAuth access token 调用独立接口:
http
GET /api/v1/me/wecom HTTP/1.1
Host: api.mx5.cn
Authorization: Bearer <access_token>json
{ "sub": "…", "org_id": "…", "wecom_userid": "zhangsan" }接口仅允许员工访问,不接受应用凭证或会员身份,也不能通过参数指定其他员工或组织。sub、org_id 应与应用当前员工会话一致;wecom_userid 为该员工已绑定的企微 userid,未绑定时明确返回 null。不要把 Betly 的 sub 当成企微 userid,不要从浏览器参数取申请人。接口不返回企微 Secret 或 access_token,也不代表调用应用已获得企微审批权限。
基础 /api/v1/me 响应不变。先发布并验证此独立接口,再切换下游应用;404 或调用失败不等于未绑定,不能退回猜测身份发送。企微绑定的内部存储迁移独立处理,不影响此接口契约。
从后台菜单进入
员工从 Betly 后台菜单进入应用时,Betly 会在应用地址上附带 betly_sub,值是当前登录后台的员工编号,与 /api/v1/me 返回的 sub 相同:
text
https://<应用域名>/<菜单路径>?betly_sub=<员工编号>同一台电脑上可能先后有不同员工使用后台。应用已有登录会话时,要核对 betly_sub 与会话里的 sub,不一致就清除会话并重新发起登录;员工已登录后台时,重新登录不会出现任何页面。betly_sub 不是凭证,只能用来判断要不要重新登录,不能凭它认定身份。
刷新与失效
访问令牌快过期时,用 refresh_token 换新:
text
grant_type=refresh_token&refresh_token=<refresh_token>请求方式与第三步相同。下列情况刷新会失败(403),已签发的访问令牌调用接口也会被拒绝,应用应清除登录状态、引导重新登录:
- 管理员暂停或吊销了应用授权(恢复授权后旧的登录也不能继续用);
- 员工离职,或角色里去掉了“进入应用”权限;
- 会员已不在该组织;
- 管理员不再对这类账号开放应用。
建议在进入重要页面时调用一次 /api/v1/me,及时发现上述变化。
示例代码(Node.js)
js
import crypto from 'node:crypto';
const b64url = (buf) => Buffer.from(buf).toString('base64url');
export function startLogin(session, accountType) {
const state = b64url(crypto.randomBytes(16));
const verifier = b64url(crypto.randomBytes(32));
session.oauth = { state, verifier };
const query = new URLSearchParams({
response_type: 'code',
client_id: process.env.BETLY_CLIENT_ID,
redirect_uri: process.env.BETLY_REDIRECT_URI,
state,
code_challenge: b64url(crypto.createHash('sha256').update(verifier).digest()),
code_challenge_method: 'S256',
scope: 'email',
account_type: accountType, // 'staff' | 'member'
});
return `https://admin.mx5.cn/oauth/authorize?${query}`;
}
export async function finishLogin(session, callbackUrl) {
const url = new URL(callbackUrl);
const pending = session.oauth;
delete session.oauth;
if (url.searchParams.get('error')) throw new Error('用户未完成授权');
if (!pending || url.searchParams.get('state') !== pending.state) throw new Error('登录请求无效');
const basic = Buffer.from(`${process.env.BETLY_CLIENT_ID}:${process.env.BETLY_CLIENT_SECRET}`);
const tokenResponse = await fetch('https://supa.mx5.cn/auth/v1/oauth/token', {
method: 'POST',
headers: {
Authorization: `Basic ${basic.toString('base64')}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'authorization_code',
code: url.searchParams.get('code'),
redirect_uri: process.env.BETLY_REDIRECT_URI,
code_verifier: pending.verifier,
}),
});
if (!tokenResponse.ok) throw new Error('Betly 未签发令牌');
const tokens = await tokenResponse.json();
const me = await fetch('https://api.mx5.cn/api/v1/me', {
headers: { Authorization: `Bearer ${tokens.access_token}` },
}).then((response) => response.json());
return { tokens, me }; // me.audience: 'staff' | 'member'
}