範例與疑難排解

片段範例便於對照協定；完整可執行指令碼見《Python 最小可執行範例》。請將常數換成你的實際值。

探索文件

curl -sS https://api-passport.swaymoon.com/.well-known/openid-configuration | jq .

請確認 authorization_endpoint、token_endpoint、userinfo_endpoint、jwks_uri 和 id_token_signing_alg_values_supported 等欄位。

授權 URL（瀏覽器跳轉）

https://api-passport.swaymoon.com/oauth2/authorize
  ?response_type=code
  &client_id=swm_YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20name%20picture%20email
  &state=YOUR_STATE
  &code_challenge=YOUR_CHALLENGE
  &code_challenge_method=S256

拼 URL 時對查詢參數只編碼一次。若網址列裡出現 redirect_uri=http%253A%252F%252F…，屬於雙重編碼，伺服器端會按字面值校驗並失敗。

換取權杖：機密用戶端（curl）

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CLIENT_SECRET='YOUR_SECRET'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "code_verifier=$VERIFIER"

換取權杖：JWT 斷言用戶端（curl）

先在後端用私鑰簽發 client_assertion（不要把私鑰寫進命令列歷史）。Python 範例：

import time, uuid
from jwcrypto import jwk, jwt  # pip install jwcrypto

key = jwk.JWK.from_json(open("private.jwk.json").read())  # 含 d 的私鑰，勿提交入口
now = int(time.time())
token = jwt.JWT(
    header={"alg": "ES256", "kid": key["kid"], "typ": "JWT"},
    claims={
        "iss": "swm_YOUR_CLIENT_ID",
        "sub": "swm_YOUR_CLIENT_ID",
        "aud": "https://api-passport.swaymoon.com/oauth2/token",
        "jti": str(uuid.uuid4()),
        "iat": now,
        "exp": now + 300,
    },
)
token.make_signed_token(key)
assertion = token.serialize()

然後：

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'
ASSERTION='...'   # 上一步簽發的 JWT

curl -sS \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "code_verifier=$VERIFIER" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=$ASSERTION"

aud 必須與探索文件裡的 token_endpoint 一致。重新整理權杖時把 grant_type 換成 refresh_token，並再簽一枚新的斷言（新的 jti / iat / exp）。

換取權杖：非機密用戶端（curl）

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'

curl -sS \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "code_verifier=$VERIFIER"

UserInfo（curl）

curl -sS https://api-passport.swaymoon.com/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

重新整理權杖（機密用戶端）

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

常見問題

聯調提示

• 根據探索文件取得端點，避免硬編碼路徑。
• 完整本機指令碼：《Python 最小可執行範例》。
• 登入和授權確認在瀏覽器中完成；機密與 JWT 斷言用戶端的換取權杖與 UserInfo 應在伺服器端進行。
• 正式環境的 Issuer 和前端網域分別為 api-passport.swaymoon.com 和 passport.swaymoon.com。

取得協助

• 使用者文件：關閉開發人員模式後，檢視「指南」和「法律」分類。
• 開發者入口網站：develop.swaymoon.com
• 聯絡方式：hello@swaymoon.com（請勿透過公共管道傳送明文 client_secret；描述問題時可將其打碼）