接入指南:通行证是什么与如何接入
起司通行证统一登录的整体介绍:能力总览、接入前置准备与对接清单,接入方从这里开始。
更新于 2026-10-10
接入指南:通行证是什么与如何接入
本文是「起司通行证开放平台」的总览:说明通行证能为你提供什么能力、接入前要准备什么、以及一份可以直接照着执行的对接清单。
「起司通行证」(account.cheesesynx.cn)是芝士昱森全平台统一的账号体系:任何平台接入通行证后,用户用同一套账号即可登录所有平台,无需重复注册。
一、能力总览
| 能力 | 说明 | 文档 |
|---|---|---|
| 统一登录(OIDC 授权码模式) | 用户用通行证账号登录你的平台,支持账密 / 短信验证码 / 两步验证 / 第三方登录 | 《OIDC 登录:端点与三步流程》 |
| 用户信息(claims) | 用户名、昵称、头像、邮箱、实名状态;可按需申请权限等级 admin_level |
《scope 与用户字段》 |
| 协议同意门禁 | 平台协议更新后自动要求用户重新同意,合规免实现 | 《协议同意门禁》 |
| 服务端开放能力 | 查/调用户余额、起司、学生认证状态等(HMAC-SHA256 签名) | 《签名规范》《接口清单与错误码》 |
二、前置准备
向通行证管理员提供三样东西,领取 client_id / client_secret:
- 平台名称(如「起司云文档站」);
- 回调地址(redirect_uri,必须与登记的完全一致,含协议 / 路径 / 结尾斜杠);
- 所需 scope(见《scope 与用户字段》;需要 refresh_token 才申请
offline_access)。
如需服务端开放能力,另向管理员领取 App Key + App Secret。
三、对接清单(照此执行)
- 向管理员提供:平台名称、回调地址、所需 scope;
- 领取
client_id/client_secret(及如需的app_key/app_secret); - 实现授权码三步流程,或直接用标准 OIDC 库 + 发现文档自动配置;
- 用
sub(通行证 UID)做账号关联键,资料以 userinfo 为准; - 服务端数据需求走开放能力签名调用;
- 联调完成后请管理员在通行证审计日志确认联调记录。
四、推荐接入方式
推荐标准 OIDC 库 + 发现文档自动配置,无需硬编码端点:
发现文档:https://account.cheesesynx.cn/.well-known/openid-configuration
以 Node.js openid-client 为例:
const { discovery } = require('openid-client');
const issuer = await discovery('https://account.cheesesynx.cn', client_id, client_secret);
本子站其余文档按主题展开:OIDC 登录、scope 与字段、协议门禁、服务端开放能力、常见问题。