纯前端 / SPA（PKCE）

快速上手：纯前端 / SPA（PKCE）

适用：静态站、SPA、小程序 webview 等没有自己后端的接入方。你的站点不需要保管任何密钥；登录闭环全部在浏览器里完成，SSO 通过 CORS 白名单放行你的 origin。

前置：在开发者平台创建应用时选「仅前端（公开客户端）」，并把你的站点 origin （如 https://demo.example.com）作为回调地址登记。

1. 引入 SDK

<script src="https://platform.geekhonize.top/sdk/v0.1.0/gh-sso.min.js"></script>

打包器用户也可以 npm install @geekhonize/sso-sdk 后 import GHSSO from '@geekhonize/sso-sdk'。

2. 配置并发起登录

<button id="login">用 GeekHonize 登录</button>
<script>
  GHSSO.config({
    clientId: 'gh_xxxxxxxx',              // 开发者平台给你的 client_id
    redirectUri: location.origin + '/cb'  // 必须与登记的回调地址逐字符一致
  });

  document.getElementById('login').onclick = () => GHSSO.login();
</script>

login() 会生成 state 和 PKCE 对（code_verifier 留在本页存储里，不落 URL），然后跳转到 auth.geekhonize.top 的授权页。用户在账号中心确认后就回跳。

3. 回调页处理

回调页（上面 redirectUri 指向的页面）加载时处理一次即可：

<script>
  GHSSO.config({ clientId: 'gh_xxxxxxxx', redirectUri: location.origin + '/cb' });

  const r = await GHSSO.handleCallback();   // 自动校验 state + 用 code 换令牌
  if (r.ok) {
    console.log('已登录：', r.user.username);
  } else {
    console.warn('未登录/失败：', r.error);  // 引导重新 GHSSO.login() 即可
  }
</script>

autoCallback 默认开启：页面只要带着 ?code= 就会自动消化，上面手写一行也可以省。换到的令牌存在 sessionStorage（可配置）。

4. 取用户与退出

if (GHSSO.isAuthenticated()) {
  const me = await GHSSO.me();   // 回源复核身份（推荐进页就调一次）
  console.log(me.username, me.roles);
}

document.getElementById('logout').onclick = () => GHSSO.logout({ federated: true });

安全边界（必须了解）

令牌存在浏览器本地，XSS 即失窃。 请配 CSP；对安全敏感的站点请改走

服务端接入。

访问令牌是 HS256 JWT，你的前端无法本地验签，核实身份只能 GHSSO.me()。
没有 refresh_token。令牌 7 天过期，过期后重新 login()。
CORS 白名单默认回落到你登记的回调地址的 origin；需要额外来源在应用设置里填 cors_origins。

排错

报错	原因
授权页「回调地址不在白名单内」	redirect_uri 与登记值不一致（端口、尾斜杠都算）
控制台 CORS 报错	当前 origin 未命中白名单
`state_mismatch`	授权页停留太久或开了新标签页；重新登录即可
`GHSSO: 非本地环境必须使用 https`	WebCrypto 只在安全上下文可用，线上页面上 https 是硬性要求

完整示例见 SDK 仓库 examples/static-pkce/。