接入指南:通行证是什么与如何接入

起司通行证统一登录的整体介绍:能力总览、接入前置准备与对接清单,接入方从这里开始。

更新于 2026-10-10

接入指南:通行证是什么与如何接入

本文是「起司通行证开放平台」的总览:说明通行证能为你提供什么能力、接入前要准备什么、以及一份可以直接照着执行的对接清单。

「起司通行证」(account.cheesesynx.cn)是芝士昱森全平台统一的账号体系:任何平台接入通行证后,用户用同一套账号即可登录所有平台,无需重复注册。

一、能力总览

能力 说明 文档
统一登录(OIDC 授权码模式) 用户用通行证账号登录你的平台,支持账密 / 短信验证码 / 两步验证 / 第三方登录 《OIDC 登录:端点与三步流程》
用户信息(claims) 用户名、昵称、头像、邮箱、实名状态;可按需申请权限等级 admin_level 《scope 与用户字段》
协议同意门禁 平台协议更新后自动要求用户重新同意,合规免实现 《协议同意门禁》
服务端开放能力 查/调用户余额、起司、学生认证状态等(HMAC-SHA256 签名) 《签名规范》《接口清单与错误码》

二、前置准备

向通行证管理员提供三样东西,领取 client_id / client_secret:

  1. 平台名称(如「起司云文档站」);
  2. 回调地址(redirect_uri,必须与登记的完全一致,含协议 / 路径 / 结尾斜杠);
  3. 所需 scope(见《scope 与用户字段》;需要 refresh_token 才申请 offline_access)。

如需服务端开放能力,另向管理员领取 App Key + App Secret。

三、对接清单(照此执行)

  1. 向管理员提供:平台名称、回调地址、所需 scope;
  2. 领取 client_id / client_secret(及如需的 app_key / app_secret);
  3. 实现授权码三步流程,或直接用标准 OIDC 库 + 发现文档自动配置;
  4. 用 sub(通行证 UID)做账号关联键,资料以 userinfo 为准;
  5. 服务端数据需求走开放能力签名调用;
  6. 联调完成后请管理员在通行证审计日志确认联调记录。

四、推荐接入方式

推荐标准 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 与字段、协议门禁、服务端开放能力、常见问题。