使用生成式 AI 接入非機密用戶端

本文面向希望借助生成式 AI、以非機密用戶端（clientType=public，認證方式 none）接入通行帳戶的開發者：適合純 HTML、靜態站或純瀏覽器端應用程式。可執行指令碼見《Python 最小可執行範例》。

若專案包含可保管金鑰的伺服器端、API Route、Serverless Function 或 BFF，請改用機密用戶端，閱讀《使用生成式 AI 接入機密用戶端》。

適用與不適用

產品約定（與入口網站一致）：

• 不發放 client_secret；換取權杖時不要使用 HTTP Basic。
• 強制 PKCE（S256）。
• 不簽發 refresh_token；Access Token 約 5 分鐘，過期後重新走授權碼流程。
• 重新導向 URI 須預先登記，且與授權請求中的 redirect_uri 逐字元一致。拼授權 URL 時用一次編碼即可（例如 URLSearchParams / urllib.parse.urlencode），不要對已編碼的 URI 再 encode。

在入口網站建立

1. 登入 develop.swaymoon.com，進入識別碼，點選 +。
2. 描述填寫同意頁可識別的名稱；用戶端類型選非機密用戶端（建立後不可改為機密）。
3. 圖示可用預設或上傳裁剪。
4. 重新導向 URI登記回呼位址。Python 非機密 demo 使用：http://127.0.0.1:8765/callback。
5. 功能：保留必選 openid；按需設定 email 與資料細項（選用或必選；必選須填理由與隱私權政策）。詳見《權限與同意》。
6. 確認後點「註冊」，複製 client_id（無 client_secret）。

http://127.0.0.1 與 http://localhost 視為不同位址。協定參數見《授權碼與 PKCE》。

把提示詞交給 AI

接入已有前端 / 靜態專案時，可貼上下列提示詞（不要傳送真實權杖或完整回呼查詢字串）：

請在目前純前端 / 靜態專案中接入「搖月 Swaymoon 通行帳戶」登入（非機密用戶端）。
- clientType=public，認證方式 none；禁止 client_secret 與 HTTP Basic。
- Issuer：https://api-passport.swaymoon.com ；Discovery 為準。
- Authorization Code + PKCE（S256）；換票表單含 grant_type、code、redirect_uri、client_id、code_verifier。
- 無 refresh_token；預設 scope 含 openid；需要時再加 email 或資料細項，勿用整包 profile。
- state / code_verifier 放 sessionStorage；以 sub 識別使用者；輸出須登記的 Redirect URI。

本機標準庫聯調見《Python 最小可執行範例》。有伺服器端時的提示詞見《使用生成式 AI 接入機密用戶端》。

安全要點

• 登入與授權必須跳轉官方通行帳戶網域。
• client_id 可以出現在前端；勿編造 client_secret。
• 最小 scope；尊重使用者取消選用權限；UserInfo 未授權資料項為預設佔位值（見《權杖與使用者資訊》）。
• 需要「保持登入」時，引入可保管金鑰的伺服器端並改用機密用戶端 + 自有工作階段。

疑難排解見《範例與疑難排解》。