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

本文面向希望借助生成式 AI、以機密用戶端接入 OAuth 2.1 / OpenID Connect（OIDC）登入的開發者。即使尚未系統學習相關協定，也可以按照本頁步驟完成基礎接入。

整個過程只需要四步：

1. 把本頁提供的提示詞交給 AI。
2. 將 AI 輸出的 Redirect URI（重新導向 URI）登記到搖月開發者入口網站的識別碼精靈（選機密用戶端）。
3. 將開發者入口網站產生的 client_id 和 client_secret 設定為伺服器端環境變數。
4. 啟動應用程式並測試**「透過搖月 Swaymoon 通行帳戶登入」**按鈕。

本頁提示詞面向包含可保管金鑰的伺服器端執行時期的應用程式。若專案以純 HTML、靜態網站或純瀏覽器端形態交付，請改讀《使用生成式 AI 接入非機密用戶端》與《Python 最小可執行範例》，不要編造 client_secret。

如果不確定專案架構，提示詞會要求 AI 先檢查：是否存在傳統後端、API Route、Serverless Function 或 BFF（Backend for Frontend）等可安全保存 client_secret 的執行時期。

關鍵安全要求

client_secret 是機密用戶端用於身分認證的憑證，只能保存在伺服器端。不得將其傳送給 AI，也不得將其寫入前端程式碼、用戶端可見的環境變數或 Git 儲存庫。非機密用戶端不會發放 client_secret。

第一步：把提示詞交給 AI

在 AI 程式設計工具中開啟專案，然後完整複製以下提示詞。

無需向提示詞補充任何真實憑證。AI 應先完成程式碼實作，再輸出需要登記的 Redirect URI。

請在目前專案中接入「搖月 Swaymoon 通行帳戶」登入，並直接完成程式碼修改和必要測試。

互動目標：
- 在合適的登入頁面新增「透過搖月 Swaymoon 通行帳戶登入」按鈕。
- 使用者選擇按鈕後前往搖月官方頁面登入。
- 登入成功後返回目前應用程式，並保持登入狀態。

請先檢查專案的部署與執行時期形態：
- 如果專案有伺服器端、API Route、Serverless Function 或 BFF，可安全保管 client_secret，請繼續按機密用戶端實作。
- 如果專案是純 HTML、純靜態網站或權杖交換只能發生在瀏覽器中的純 SPA：不要使用機密用戶端；應改用入口網站的非機密用戶端（clientType=public，認證方式 none），並按無 client_secret 的 PKCE 權杖交換實作（參考《使用生成式 AI 接入非機密用戶端》《Python 最小可執行範例》）。
- 任何情況下都不得把 client_secret 放到瀏覽器或前端程式碼中。

接入設定：
- Issuer：https://api-passport.swaymoon.com
- Discovery：https://api-passport.swaymoon.com/.well-known/openid-configuration
- 流程：Authorization Code + PKCE（S256）
- 有伺服器端時用戶端認證：client_secret_basic（機密用戶端）；純前端時使用 none（非機密用戶端，表單攜帶 client_id + code_verifier，無 refresh_token）
- ID Token 簽章演算法：ES256
- 登入入口優先使用：GET /auth/swaymoon
- 回呼入口優先使用：GET /auth/swaymoon/callback
- 預設只申請 openid。僅在目前產品確實需要時增加 email 或具體資料細項（如 name、picture），不要用整包 profile 一把拿走。

實作要求：
1. 優先使用適合目前框架、仍在維護的 OIDC 用戶端程式庫，並透過 Discovery 取得協定端點。
2. 在伺服器端產生並保存 state、nonce 和 PKCE code_verifier，回呼時嚴格校驗。
3. 只在伺服器端使用 SWAYMOON_CLIENT_ID 和 SWAYMOON_CLIENT_SECRET 換取權杖。
4. 使用 JWKS 校驗 ID Token 的 ES256 簽章，並校驗 iss、aud、exp、iat 和 nonce。
5. 在伺服器端呼叫 UserInfo，確認其中的 sub 與 ID Token 的 sub 一致。
6. 使用 sub 查找或建立本機使用者，不要使用 email 作為使用者主鍵；按權杖 scope 解釋資料欄位，未授權項會是預設佔位值而非真實資料。
7. 建立目前應用程式自己的安全登入工作階段。瀏覽器只保存設定了 HttpOnly 和合理 SameSite 屬性的應用程式工作階段 Cookie，不保存搖月權杖；正式環境使用 HTTPS 時必須設定 Secure。
8. 登入後的跳轉目標只允許站內相對路徑或可信白名單，避免開放重新導向。
9. 不得在 localStorage、sessionStorage、普通 Cookie、日誌、錯誤頁面或測試快照中保存金鑰和權杖。
10. 不得使用 NEXT_PUBLIC_、VITE_、NUXT_PUBLIC_、PUBLIC_ 等公開變數名前綴保存金鑰。
11. 建立不含真實值的 .env.example，並確保本機金鑰檔案已被 .gitignore 忽略。
12. 不要詢問或要求我把真實 client_secret 發到對話中。

請在完成後提供清晰、可執行的接入說明：
1. 「請複製下面這整行到搖月開發者入口網站」，然後單獨輸出本機開發使用的完整 Redirect URI。
2. 正式環境應登記的完整 Redirect URI；如果目前不知道正式網域，請明確標出需要替換的部分。
3. 我需要在伺服器端設定哪些環境變數，以及應在目前框架或部署平台的哪裡填寫。只顯示變數名，不顯示或猜測金鑰值。
4. 如何啟動專案、找到登入按鈕並完成一次測試。
5. 你修改了哪些檔案。

AI 完成程式碼修改後，定位其輸出的以下內容：

請複製下面這整行到搖月開發者入口網站：
http://127.0.0.1:3000/auth/swaymoon/callback

以上位址僅為範例。連接埠和路徑以 AI 根據目前專案輸出的結果為準。

第二步：登記 Redirect URI

什麼是 Redirect URI？

Redirect URI 即開發者入口網站精靈中的「重新導向 URI」，是預先登記在 OAuth 用戶端中的回呼端點。使用者在搖月通行帳戶完成身分認證和授權確認後，授權伺服器會將瀏覽器重新導向至該位址，並攜帶授權回應，例如 code 和 state。

Redirect URI 通常對應 AI 在應用程式後端建立的回呼路由，不是普通首頁。該路由負責校驗授權回應、換取權杖、建立應用程式工作階段，並將使用者重新導向至登入後的頁面。

Redirect URI 通常由應用程式 Origin 和回呼路徑組成。Origin 包含 scheme、host 和 port，例如 https://app.example.com 或 http://127.0.0.1:3000。

應用程式 Origin + /auth/swaymoon/callback

例如：

請優先使用 AI 根據專案路由和執行連接埠輸出的完整 Redirect URI，不要自行推測。

Redirect URI 的精確匹配要求

授權請求中的 redirect_uri 必須與開發者入口網站中的登記值逐字元一致。這項校驗用於防止授權碼被傳送至未經登記的位址。以下差異均會被視為不同的 URI：

• http:// 和 https:// 不同；
• 127.0.0.1 和 localhost 不同；
• 3000 和 3001 連接埠不同；
• 有無末尾 / 也可能不同。

因此，請完整複製 AI 輸出的 URI，不要手動修改。如果 AI 分別輸出本機環境和正式環境的 URI，請在開發者入口網站中逐條登記。

在開發者入口網站填寫

1. 登入 搖月開發者入口網站。
2. 進入識別碼，點選 + 開啟「註冊應用程式識別碼」精靈。
3. 描述：填寫使用者在同意頁可識別的名稱；有伺服器端時選擇機密用戶端。
4. 圖示：可用預設圖示，或上傳並裁剪後繼續。
5. 重新導向 URI：貼上 AI 給出的完整 Redirect URI（本機與正式可分別新增）。
6. 功能：保持 openid 必選。需要聯絡電子郵件時再設定 email（必選 / 選用 / 不申請）；資料細項亦可選或必選（必選須填理由與隱私權政策）。使用者可能選擇隱私郵件，你方按普通 email 處理即可。詳見《權限與同意》。
7. 確認後點「註冊」。

建立成功後，開發者入口網站會提示用戶端憑證（請立即保存）：

• client_id：OAuth 用戶端的公開識別，用於識別發起授權請求的應用程式；
• client_secret：機密用戶端的認證憑證，僅在建立時顯示一次，必須立即安全保存（非機密用戶端無此欄位）。

第三步：設定用戶端憑證

AI 通常已經在專案中建立了類似下面的設定範本：

SWAYMOON_ISSUER=https://api-passport.swaymoon.com
SWAYMOON_CLIENT_ID=
SWAYMOON_CLIENT_SECRET=
SWAYMOON_REDIRECT_URI=

請按照 AI 針對你的框架給出的說明，在伺服器端環境變數中填寫真實值。

• 本機開發時，通常填寫到已被 .gitignore 忽略的 .env.local 或同類檔案中。
• 部署網站時，填寫到部署平台的 Environment Variables、Secrets 或「環境變數」設定頁面中。
• SWAYMOON_REDIRECT_URI 填寫剛才登記的完整 Redirect URI。
• 如果 AI 還要求設定應用程式工作階段金鑰，請在本機終端機按照它給出的命令產生隨機值，再自行填入環境變數，不要把產生結果發回 AI。

用戶端憑證的安全要求

以下操作均被禁止：

• 不要把 client_secret 貼到 AI 對話中；
• 不要把 client_secret 寫進 HTML、React、Vue 或其他前端檔案；
• 不要使用 NEXT_PUBLIC_、VITE_、NUXT_PUBLIC_、PUBLIC_ 等前端公開變數保存它；
• 不要把包含真實金鑰的 .env 檔案提交到 Git；
• 不要把 Access Token、ID Token 或 Refresh Token 保存到 localStorage。

如果 AI 要求將 client_secret 寫入前端，請停止採用該實作，並改為由伺服器端或 BFF 完成權杖交換。

第四步：測試登入

1. 按照 AI 給出的命令啟動專案。
2. 開啟包含登入按鈕的頁面。
3. 選擇**「透過搖月 Swaymoon 通行帳戶登入」**。
4. 在搖月官方頁面完成登入和授權。
5. 瀏覽器返回你的應用程式，並顯示已登入狀態。

使用者側只需顯示一個登入按鈕。授權重新導向、回呼校驗、權杖交換和應用程式工作階段建立均由伺服器端完成。

<a href="/auth/swaymoon">透過搖月 Swaymoon 通行帳戶登入</a>

實際按鈕的元件實作和樣式由 AI 根據目前專案產生，無需手動複製以上 HTML。

常見問題

可以將錯誤資訊提供給 AI 輔助排查，但應先移除其中的用戶端憑證、權杖和完整回呼查詢參數。不要傳送包含 code= 或 state= 的完整瀏覽器位址。

有關協定流程和參數的完整說明，請閱讀《接入概述》《授權碼與 PKCE》《權杖與使用者資訊》《權限與同意》《範例與疑難排解》和《Python 最小可執行範例》；用戶端註冊見同目錄《註冊與設定》。