接入概述

你可以通过摇月 Swaymoon 通行账户为网站或应用接入登录能力。摇月 Swaymoon 通行账户是符合 OAuth 2.1 和 OpenID Connect 规范的身份提供方（IdP）。用户在官方域名完成登录与授权后，你的应用可使用授权码换取令牌，并读取用户信息。

本文位于「摇月 Swaymoon 开发者门户」→「指南」→「标识符」。注册与管理客户端请使用 开发者门户，并先阅读同目录《注册与配置》。

如需查看开发人员文档，请先开启文档中心右上角的开发人员模式。

文档目录

本「标识符」目录下：

环境与端点

本地联调时，Issuer 通常为 http://127.0.0.1:10001，具体值以你的环境变量为准。请始终以发现文档中的 URL 为准，避免硬编码可能变更的路径。

常用协议端点（Issuer 为前缀）：

ID Token 使用 ES256（椭圆曲线）签名算法。门户支持两类客户端，且均强制启用 PKCE（S256）：

推荐接入路径

sequenceDiagram
  participant App as 你的应用
  participant Browser as 用户浏览器
  participant Passport as 通行账户

  App->>Browser: 302 重定向至授权端点（含 PKCE）
  Browser->>Passport: 登录（如需要）
  Browser->>Passport: 同意权限
  Passport->>Browser: 302 重定向至 redirect_uri?code=
  Browser->>App: 携带 authorization code
  App->>Passport: POST token（code + verifier；机密另附 Basic）
  Passport->>App: 返回 access_token + id_token（机密另含 refresh_token）
  App->>Passport: GET UserInfo
  Passport->>App: 用户声明

1. 在 开发者门户 按《注册与配置》登记标识符，选择机密或非机密；机密客户端须妥善保存一次性展示的 client_secret。
2. 按《授权码与 PKCE》实现授权码流程（必须带 PKCE）。
3. 校验 id_token（Issuer、audience、签名和过期时间），并使用 Access Token 调用 UserInfo。
4. 将通行账户返回的 sub 作为你方用户的主键（pairwise，详见《令牌与用户信息》）。

设计要点（请先读）

• 授权码 + PKCE：门户应用不可跳过 code_challenge。
• 机密客户端：换取令牌时使用 HTTP Basic（client_id / client_secret），并同时提交 code_verifier。
• 非机密客户端：无 client_secret；换取令牌时在表单中提交 client_id 与 code_verifier。不要把「假装有的密钥」写进前端。见《使用生成式 AI 接入非机密客户端》与《Python 最小可运行示例》。
• 同意页：用户每次登录均须在授权页显式确认（不会静默跳过）。openid 始终必选；email 与资料细项可配置为必选、可选或不申请；设为必选时须在门户填写理由与隐私政策。权限变更时，用户会看到新增 / 减少对照。已上线的旧客户端无需为此改代码；新客户端请以《权限与同意》最新说明为准。
• Pairwise sub：同一用户在不同开发者团队下的 sub 不同且稳定；不要用邮箱当唯一主键。
• 邮箱声明：已授予 email 时，UserInfo 返回可联系用户的邮箱地址。用户可选择普通邮箱或隐私邮箱（隐私为中继地址，真实邮箱不会提供给你方）；两种都按普通邮箱处理即可。账号主键请用 sub。

合规与品牌

• 登录与授权必须跳转至官方通行账户域名。请勿自行搭建仿冒登录页收集用户密码。
• 仅请求业务所需的最小 scope。
• 遵守通行账户与开发者门户的《用户协议》《反滥用政策》；开发者接入问题可联系 hello@swaymoon.com。

下一步：完成《注册与配置》后，实现《授权码与 PKCE》。