接入概述開發人員

上次更新：2026年8月16日

接入概述

你可以透過搖月 Swaymoon 通行帳戶為網站或應用程式接入登入能力。搖月 Swaymoon 通行帳戶是符合 OAuth 2.1 和 OpenID Connect 規範的身分提供者（IdP）。使用者在官方網域完成登入與授權後，你的應用程式可使用授權碼換取權杖，並讀取使用者資訊。

本文位於「搖月 Swaymoon 開發者入口網站」→「指南」→「識別碼」。註冊與管理用戶端請使用開發者入口網站，並先閱讀同目錄《註冊與設定》。

如需檢視開發人員文件，請先開啟文件中心右上角的開發人員模式。

文件目錄

本「識別碼」目錄下：

文件	內容
《註冊與設定》	在開發者入口網站建立識別碼，設定重新導向 URI、選用隱私權政策連結、權限和金鑰（若有）
《授權碼與 PKCE》	發起瀏覽器授權、換取權杖和重新整理權杖
《權杖與使用者資訊》	了解 ID Token、Access Token、JWKS、UserInfo 和 `sub`
《權限與同意》	了解 `scope`、同意頁以及必選和選用權限
《範例與疑難排解》	curl 片段、常見錯誤碼和排查清單
《使用生成式 AI 接入機密用戶端》	有伺服器端時，用 AI 產生機密用戶端接入程式碼
《使用生成式 AI 接入非機密用戶端》	純前端 / 靜態站時，用 AI 產生非機密用戶端接入程式碼
《Python 最小可執行範例》	同一頁提供 public 與 confidential 兩種 PKCE demo，預設請求全部資料權限並展示授權確認頁。JWT 斷言換權杖見《授權碼與 PKCE》與《範例與疑難排解》

環境與端點

用途	正式環境
使用者登入 / 同意頁	`https://passport.swaymoon.com`
Issuer（OIDC API）	`https://api-passport.swaymoon.com`
開發者入口網站	`https://develop.swaymoon.com`
探索文件	`https://api-passport.swaymoon.com/.well-known/openid-configuration`

本機聯調時，Issuer 通常為 http://127.0.0.1:10001，具體值以你的環境變數為準。請始終以探索文件中的 URL 為準，避免硬編碼可能變更的路徑。

常用協定端點（Issuer 為前綴）：

端點	路徑
授權	`/oauth2/authorize`
權杖	`/oauth2/token`
JWKS	`/oauth2/jwks`
UserInfo	`/userinfo`
撤銷	`/oauth2/revoke`
內省	`/oauth2/introspect`

ID Token 使用 ES256（橢圓曲線）簽章演算法。入口網站支援三類用戶端，且均強制啟用 PKCE（S256）：

類型	認證方式	換取權杖	Refresh Token
機密用戶端	`client_secret_basic`	HTTP Basic + `code_verifier`	有（約 180 天）
非機密用戶端	`none`	請求體 `client_id` + `code_verifier`	無（過期後重新授權）
JWT 斷言用戶端	`private_key_jwt`	`client_assertion` + `code_verifier`	有（約 180 天）

建議接入路徑

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，JWT 另附 client_assertion）
  Passport->>App: 返回 access_token + id_token（機密與 JWT 另含 refresh_token）
  App->>Passport: GET UserInfo
  Passport->>App: 使用者聲明

在開發者入口網站按《註冊與設定》登記識別碼，選擇機密、非機密或 JWT 斷言。機密用戶端須妥善保存一次性展示的 client_secret；JWT 斷言只向入口提交公鑰，私鑰留在你的伺服器。
按《授權碼與 PKCE》實作授權碼流程（必須帶 PKCE）。
校驗 id_token（Issuer、audience、簽章和過期時間），並使用 Access Token 呼叫 UserInfo。
將通行帳戶返回的 sub 作為你方使用者的主鍵（pairwise，詳見《權杖與使用者資訊》）。

設計要點（請先讀）

授權碼 + PKCE：入口網站應用程式不可略過 code_challenge。
機密用戶端：換取權杖時使用 HTTP Basic（client_id / client_secret），並同時提交 code_verifier。
非機密用戶端：無 client_secret；換取權杖時在表單中提交 client_id 與 code_verifier。不要把「假裝有的金鑰」寫進前端。見《使用生成式 AI 接入非機密用戶端》與《Python 最小可執行範例》。
JWT 斷言用戶端：無 client_secret。換取權杖時在表單中提交 client_id、code_verifier 與用私鑰簽發的 client_assertion（ES256）。入口只存公鑰；私鑰不能上傳、不能進前端。概念與取捨見《註冊與設定》；請求格式見《授權碼與 PKCE》。
同意頁：使用者每次登入均須在授權頁明確確認（不會靜默略過）。openid 始終必選；email 與資料細項可設定為必選、選用或不申請；設為必選時須在入口網站填寫理由與隱私權政策。權限變更時，使用者會看到新增 / 減少對照。已上線的舊用戶端無需為此改程式碼；新用戶端請以《權限與同意》最新說明為準。
Pairwise sub：同一使用者在不同開發者團隊下的 sub 不同且穩定；不要用電子郵件當唯一主鍵。
電子郵件聲明：已授予 email 時，UserInfo 返回可聯絡使用者的電子郵件位址。使用者可選擇普通電子郵件或隱私郵件（隱私為中繼位址，真實電子郵件不會提供給你方）；兩種都按普通電子郵件處理即可。帳號主鍵請用 sub。

合規與品牌

登入與授權必須跳轉至官方通行帳戶網域。請勿自行搭建仿冒登入頁收集使用者密碼。
僅請求業務所需的最小 scope。
遵守通行帳戶與開發者入口網站的《使用者協議》《反濫用政策》；開發者接入問題可聯絡 hello@swaymoon.com。

下一步：完成《註冊與設定》後，實作《授權碼與 PKCE》。

接入概述 開發人員