OAuth 2.0 (DOC-OAUTH-001)

KNOW 使用標準 OAuth 2.0 授權碼流程搭配 PKCE。當你的應用程式需要代表使用者存取其 KNOW 帳號資訊時，請使用此流程。

Discovery (DOC-OAUTH-002)

GET https://me.know.tw/.well-known/openid-configuration

回傳所有 OAuth endpoint、支援的 scope、grant type 等資訊。OAuth client library 通常會自動從這個 endpoint 取得設定。

1. 建立 OAuth App (DOC-OAUTH-003)

前往 Knower Dashboard，選擇你的 Partner App，點選「管理 OAuth」。

你會取得：

Client ID — 公開識別碼
Client Secret — 只會顯示一次，請妥善保存

2. 導向授權 (DOC-OAUTH-004)

向以下 endpoint 發出 GET 請求：

GET https://me.know.tw/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid profile email
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

參數：

| 參數 | 必填 | 說明 | |------|------|------| | client_id | ✓ | 你的 Client ID | | redirect_uri | ✓ | 必須與 OAuth 設定中已註冊的 Redirect URI 完全一致 | | response_type | ✓ | 固定為 code | | scope | ✓ | 空白分隔的 scope 列表 | | state | ✓ | 防 CSRF 的隨機字串 | | code_challenge | 建議 | PKCE challenge（verifier 的 SHA-256，以 base64url 編碼） | | code_challenge_method | 建議 | S256 或 plain |

若使用者尚未登入，回應會包含 login_url，你的應用程式應將使用者導向該網址完成登入。登入後，使用者將在同意畫面確認授權；你的前端需將同意結果 POST 到 /oauth/authorize/confirm（欄位同上）以取得授權碼。

3. 處理 Callback (DOC-OAUTH-005)

使用者同意後，後端會回傳包含 redirect_url 的 JSON 回應；前端應將使用者導向該網址：

https://yourapp.com/callback?code=AUTH_CODE&state=YOUR_STATE

務必驗證 state 與原始請求一致，再用 code 交換 token，以防範 CSRF 攻擊。

4. 交換 Token (DOC-OAUTH-006)

curl -X POST https://me.know.tw/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

回應：

{
  "access_token": "vbco_...",
  "refresh_token": "vbcr_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

5. 取得使用者資訊 (DOC-OAUTH-007)

curl https://me.know.tw/api/oauth/userinfo \
  -H "Authorization: Bearer vbco_..."

回應：

{
  "sub": "user_id",
  "name": "Display Name",
  "preferred_username": "handle",
  "picture": "https://...",
  "email": "user@example.com",
  "email_verified": true
}

回傳欄位取決於授權的 scope：

openid / profile → sub, name, preferred_username, picture
email → email, email_verified

6. 刷新 Token (DOC-OAUTH-008)

Access token 有效期為 1 小時。使用 refresh token 換取新的：

curl -X POST https://me.know.tw/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=vbcr_..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Refresh token 有效期 30 天，每次使用會自動輪換——舊的 token 立刻失效。

7. 撤銷 Token (DOC-OAUTH-009)

curl -X POST https://me.know.tw/api/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "vbco_..."}'

無論 token 是否存在，皆回傳 {"ok": true}（符合 RFC 7009）。

PKCE 實作範例 (Node.js) (DOC-OAUTH-010)

import { randomBytes, createHash } from "crypto";

const verifier = randomBytes(32).toString("base64url");

const challenge = createHash("sha256")
  .update(verifier)
  .digest("base64url");

// 將 challenge 用於授權請求（code_challenge 參數）
// 將 verifier 用於 token 交換（code_verifier 參數）