使用者流程(authorization code + PKCE)
使用者本人在你的應用裡操作自己的資料時走這條。發出的 token 是 profile self。
v1 沒有代理。 「A 代表 B 操作」的
delegatedprofile 是 v2 規劃中的範圍,本版不提供。不要用selftoken 加上自訂 header 假裝代理——平台不會承認。
流程
- 產生
code_verifier(43–128 字元的高熵隨機字串)與code_challenge = BASE64URL(SHA256(code_verifier))。 - 把使用者導到授權端點:
https://auth.lightup.tech/oauth2/authorize
?response_type=code
&client_id=tp_example_app
&redirect_uri=<登記過的精確值>
&scope=lightup.profile.self.read lightup.person.metadata.read
&state=<你產生的隨機值>
&code_challenge=<challenge>
&code_challenge_method=S256
- 使用者登入並在同意頁核准。同意頁顯示應用名稱、發布者、請求的能力(用目錄裡的說明文字,不是 raw scope 字串),以及撤銷入口。
- 平台導回你的
redirect_uri,帶code與state。先比對state,不符就中止。 - 用
code換 token:
POST https://auth.lightup.tech/oauth2/token,application/x-www-form-urlencoded。
| 欄位 | 必填 | 說明 |
|---|---|---|
grant_type |
必填 | 固定 authorization_code |
client_id |
必填 | 第三方 client id,形狀 tp_<tenant label>_<slug>,由 amygdala 配發。 |
client_secret |
選填 | confidential client 才有;public client 不送。 |
code |
必填 | /oauth2/authorize 導回時帶的一次性授權碼。用過就失效。 |
code_verifier |
必填 | PKCE verifier,43–128 字元。授權請求送的是它的 S256 雜湊 (code_challenge),plain 不支援。 |
redirect_uri |
必填 | 必須與授權請求送出的那一個完全相同,且已登記在 client 上。 |
code 與 refresh_token 都是一次性的:重送同一個 code 會得到 invalid_grant,
逾時之後不要盲目重試,重新走一次流程。
續期
POST https://auth.lightup.tech/oauth2/token,application/x-www-form-urlencoded。
| 欄位 | 必填 | 說明 |
|---|---|---|
grant_type |
必填 | 固定 refresh_token |
client_id |
必填 | 第三方 client id,形狀 tp_<tenant label>_<slug>,由 amygdala 配發。 |
client_secret |
選填 | confidential client 才有。 |
refresh_token |
必填 | 上一次回應給的那一張。不透明字串,不要解析。 |
scope |
選填 | 可選,只能縮小原本的 scope,不能放大。省略就沿用原本的。 |
token 端點的錯誤
錯誤狀態:400、401、429。
body 是 OAuth 既有的 TokenError 形狀(error + error_description),
不是本 API 其他端點的 Problem——不要把兩者放進同一個解析路徑。
error |
意思 |
|---|---|
invalid_client |
client id/secret 不對,或 client 已停用 |
invalid_grant |
code/refresh token 無效、過期或已用過;PKCE code_verifier 不符 |
invalid_scope |
請求的 scope 不在 client 允許範圍、tenant grant 或方案上限內 |
unsupported_grant_type |
這個 grant 沒開。client_credentials 今天就是這個答案 |
error_description 一般是給人看的、字串隨時可能改。唯一的例外是契約明文列出的
機器可讀值,目前只有一個:
{ "error": "invalid_grant", "error_description": "tenant_suspended" }
意思是你這個 client 的租戶被停權,簽發端直接拒絕發 token;authorization_code
與 refresh_token 都會撞到。重試與重新走一次授權流程都沒有用,要等租戶恢復,
請聯絡租戶管理員。
⚠️ 注意這是 400 的 OAuth 錯誤形狀(error + error_description),不是 API
其他端點的 Problem。tenant_suspended 這個字串在兩種形狀裡都會出現——
簽發被拒是 400 OAuth error,每請求判權被拒是 403 Problem。
不要把兩者放進同一個解析路徑。
回應可能還帶一個 message 欄位(平台既有的人類可讀欄位)。它不是契約的一部分,
不要解析它。
PKCE 是必填
- public client(行動/桌面/SPA)強制 PKCE S256。
- 第三方 confidential client 也必填 PKCE,不吃第一方「confidential 可以不帶 PKCE」的相容路徑。
- 只接受
S256,不接受plain。
Redirect URI
- 一律精確比對。不支援子網域萬用字元。
- 原生應用依 RFC 8252 使用系統瀏覽器加自訂 scheme 或 loopback(
http://127.0.0.1:<port>/...),不要用內嵌 WebView 收 code。
Token 與 refresh
| 項目 | 值 |
|---|---|
| profile | self |
sub |
使用者的 psn_… |
actor.accountId |
使用者的 acc_… |
| TTL | 15 分鐘 |
| refresh | 有,嚴格 rotation |
嚴格 rotation 的意思:每次用 refresh token 都會拿到新的一張,舊的立刻作廢。重放一張已經用掉的 refresh token 會殺掉整個 token family——使用者要重新授權。第三方不會拿到 reuse grace、sliding 或 absolute-max 這些放寬。
實務上:同一個使用者的 refresh 呼叫要序列化,不要讓多個執行緒或多台機器同時拿同一張 refresh token 去換。
登出、撤銷與「這張 token 現在還算不算有效」
ℹ️ 狀態(2026-09-30)。 本節描述的
/oauth2/introspect、/oauth2/logout、 back-channel logout 與 logout 登記都已上線(lightup-rs #1408/#1412/#1425/#1431)。 以下是正式行為,不是預告。
三件事不要混在一起
| 你想做的事 | 用哪一個 | 效果範圍 |
|---|---|---|
| 丟掉我自己這個 app 存的 refresh token | POST /oauth2/revoke |
只撤你這個 client 的那一條 rotation 鏈(token family)。使用者仍然是登入狀態,其他 app 的 token 不受影響,不會有 back-channel 通知 |
| 把使用者登出(結束這次登入) | GET|POST /oauth2/logout(RP-Initiated Logout) |
結束平台上那顆登入 session,並對這顆 session 上所有第三方 app 送 back-channel logout(包含發起的你自己) |
| 問一張 token現在還有不有效 | POST /oauth2/introspect |
即時讀取,無快取。這是權威來源 |
在途的 access token 不會因為上面任何一項而立刻失效:它有效到自己的 exp(最長
15 分)。要更快,就在每個敏感操作前 introspect。
/oauth2/revoke(RFC 7009)
- 撤的是那張 refresh token 所屬的整個 family。
- 依 RFC 7009,成功一律 200 且無 body;token 不存在、已過期、或屬於別的 client, 同樣回 200 且不做事——不會告訴你那張 token 存不存在。所以逾時可以安全重試。
- 它不是登出。 不結束 session、不送 back-channel。把 revoke 當成登出會讓使用者 以為自己登出了,其實下次點你的登入按鈕會直接靜默拿到新 token。
- 租戶以你的 client 登記的租戶為準(和 token 端點同一條解析):你不需要、也不能在 請求裡指定租戶。
/oauth2/logout(RP-Initiated Logout)
id_token_hint必填。 沒有 hint 的登出請求會被拒——否則任何網頁都能把人登出。 hint 必須是平台簽發的 ID token,已過期的可以(規格允許)。第一方產品簽發的 ID token 也接受(見下方「第一方 hint」)。- 帶
client_id時,必須等於 hint 的aud。 post_logout_redirect_uri必須精確等於你登記過的值(見下節):多一個尾斜線、 多一個 query 參數都不算相符。不符會得到錯誤頁(400),而且使用者不會被登出 ——請把登記值與你送出的字串當成同一份常數管理。state會原樣帶回。- 沒帶
post_logout_redirect_uri(或沒登記)時,使用者停在平台的「已登出」頁, 登出本身照做。 - 對已經結束的 session 再登出一次也是成功(冪等)。
瀏覽器綁定:不是同一個瀏覽器會先看到確認頁。 發出登出請求的瀏覽器若不是那顆 session
的持有者(平台從它的 session cookie 推不出同一個 sid),會先顯示確認頁——一張 POST
回 /oauth2/logout 的表單,把你送來的參數原樣帶著,使用者按下確認才真的登出。
因為 id_token_hint 是可以被複製的,單靠它等於讓任何拿到 hint 的頁面把人登出。
實務影響:從使用者自己的瀏覽器導向 /oauth2/logout 會直接登出;從伺服器端或
另一個瀏覽器/裝置發同一個請求不會靜默登出,會停在確認頁。想在後端「把某個 session
殺掉」不要用這條路由。
另外:post_logout_redirect_uri 的驗證在綁定檢查之前。帶了沒登記的 redirect 會
直接得到 400 錯誤頁,不會先看到確認頁——除錯時不要把「沒看到確認頁」讀成「綁定成立」。
第一方 hint:hint 是 LightUp 第一方產品的 ID token 時也接受(discovery 公告了
end_session_endpoint,用通用 OIDC library 的第一方 RP 會把使用者送來這裡)。那條路徑
的導回條件不一樣:可接受該 client 在該 token 自己的租戶內登記的 redirect_uris
之一(平台只在那一個租戶裡找這個 client id,不會跨租戶去拿同名登記的值),或任一
該租戶自有網域上的 https URL;不符就顯示「已登出」頁、不回錯誤。它不會結束第一方
產品的登入——那個登入在各自 BFF 的 cookie 裡,這條路由碰不到。
⚠️ 這個放寬與你無關。 第三方 hint 的 post_logout_redirect_uri 只接受 logout
登記裡的精確值;「該租戶網域下的 https URL」不適用於第三方(否則任何能在租戶網域上
放一個頁面的人就能決定你的使用者登出後去哪裡)。
logout 登記:怎麼申請
post-logout redirect URI 與 back-channel logout URI 不在你的 client 登記表單的欄位裡, 而是一份旁掛的登記值。申請方式:
- 把要登記的 URI 交給租戶 owner,由 owner 在 LightUp Dashboard 的「整合」頁送出; 或由平台操作者用內部路由代填。
- 第三方不會、也不能直接呼叫這條內部 API——它在 internal 面,需要平台的 internal token。你提供值,平台寫入。
- 登記是整份覆寫:每次送出的就是完整清單,省略某一項等於清空它。要改一個 URI, 請連同其他要保留的一起送。
URI 規則(不符會被拒):
| 規則 | 說明 |
|---|---|
https |
只接受 https |
| 公開網域 | 網域必須含一個點(裸主機名如 https://intranet/… 會被拒 → not_fully_qualified);拒絕 IP 位址(IPv4 與 IPv6 都算 → ip_literal)、localhost、*.localhost、.local、.internal、.svc、.cluster.local(→ private_host) |
| 無 fragment | 不可有 #… |
| 無 wildcard | 不可有 *(沒有子網域萬用字元,和 redirect URI 一樣是精確比對) |
| 無 userinfo | 不可有 user:pass@ |
| 長度 | 每個 URI ≤ 2048 位元組(純 ASCII 的 URL 等於 2048 字元) |
| 數量 | post-logout redirect URI 最多 10 個 |
被拒時是 400,代碼是穩定的(可以判斷,不要對訊息文字做字串比對):
| 狀態 | body | 何時 |
|---|---|---|
| 400 | {"error":"too_many_uris","field":"postLogoutRedirectUris"} |
超過 10 個 |
| 400 | {"error":"invalid_uri","field":"postLogoutRedirectUris"|"backchannelLogoutUri","index"?:n,"reason":R} |
某一個 URI 不合規;index 只在 field 是 postLogoutRedirectUris 時出現(0 起算)。第一個不合規的就回傳,不會一次列出全部 |
| 404 | {"error":"client_not_found"} |
client 不存在或不是第三方 client |
| 404 | {"error":"not_found"} |
第三方功能在本部署未開啟,路由不存在 |
| 503 | {"error":"temporarily_unavailable"} |
讀寫失敗,可重試 |
reason(R)的封閉集合:too_long(> 2048 位元組)、unparsable、not_https、
wildcard、userinfo、fragment、ip_literal、private_host、not_fully_qualified。
判斷順序固定:too_long → wildcard → unparsable → not_https → userinfo →
fragment → host(ip_literal/private_host/not_fully_qualified)。一個 URI 同時犯
兩條時回先撞到的那一個——https://*.example.org/x 是 wildcard 而不是 unparsable,
https://localhost/x 是 private_host 而不是 not_fully_qualified。
後果講清楚:
- 沒有登記 back-channel logout URI 的 app 收不到 back-channel logout。 平台不會改用 其他方式通知你,你只能靠 introspect 發現。
- 沒有登記 post-logout redirect URI 的 app,使用者做 RP-initiated logout 之後只會看到 平台的「已登出」頁,不會回到你的 app。
驗證方式:登記完成後,在 discovery 文件(https://auth.lightup.tech/.well-known/openid-configuration)
看到 end_session_endpoint 與 backchannel_logout_supported: true,再實際走一次
登出並確認你的 back-channel 端點收到請求。
back-channel logout:什麼時候收得到
收得到的前提是你登記了 back-channel logout URI。收到時機:
| 事件 | 會收到嗎 |
|---|---|
| 使用者在你的 app 裡做 RP-initiated logout | 會(這顆 session 上所有 app 都收到,包含你) |
| 使用者在平台上登出 | 會 |
| 帳號被關閉、合併,或第二因子變更 | 會 |
| 偵測到 refresh token 重放(見下節) | 會 |
| 帳號被停用、租戶被停權、安全 epoch 變動 | 會(平台定期重驗發現後送出) |
你自己呼叫 /oauth2/revoke |
不會(那是你自己發起的,不是登出事件) |
送信形式:POST 你登記的 URI,application/x-www-form-urlencoded,帶 logout_token
(一顆 JWT,header typ 是 logout+jwt,claims 有 iss/aud/sid/sub/jti/events,
沒有 nonce)。回 2xx 視為成功,失敗會重試幾次後放棄。
⚠️ back-channel 是 best effort,不是保證。 送信會重試,但平台重啟可能讓還沒送完的 通知消失。不要把它當成唯一的撤權訊號——權威來源是 introspect。本文件不承諾任何 傳播秒數。
⚠️ 登記通過不代表送得出去。 送信用的 HTTP client 有自己的解析器,連線當下就判斷
位址:落在私有網段、loopback、cloud metadata(169.254.169.254)、CGNAT
(100.64.0.0/10)、IPv6 私有與 link-local、multicast 與各種保留/文件用網段,都不送
(IPv4-mapped 的 IPv6 位址按它承載的 IPv4 判斷;已棄用的 IPv4-compatible 形式,也就是
::/96 裡的位址如 ::a00:1、::808:808,整段不送,不看它承載的是哪個 IPv4)。
登記時檢查的是 URI 的字面值,送出時檢查的是當下解析到的 IP——所以登記時通過的 URI,
如果之後 DNS 指向私有位址,送出時仍然會被拒。
一個名稱解析出多個位址時,只要有一個被封鎖,整個名稱就不連(DNS rebinding 會刻意 讓答案裡同時出現一個內部位址)。所以 back-channel 端點的 DNS 不要同時回公開與內部 位址,例如 split-horizon 的記錄;請把它放在真正只對外的位址上。
⚠️ 通知是「至多一次」。 平台在寫下「session 已結束」與送出通知之間如果重啟, session 仍然是結束的(introspect 與 refresh 都會這樣回答),但不會補送那一次 通知。這就是「best effort」的精確意思——所以權威來源必須是 introspect。
refresh token 重放的後果(不只是 invalid_grant)
嚴格 rotation 的意思在上面「Token 與 refresh」已經說了:每次 refresh 都換一張新的, 舊的立刻作廢。重放一張已經用掉的 refresh token,平台當成竊用訊號處理:
- 整個 token family 立刻撤銷;
- 而且那條 family 綁定的整顆登入 session 被結束;
- 這顆 session 上所有第三方 app 都收到 back-channel logout。
也就是說:你一次錯誤的重送,會把使用者從所有第三方 app 登出。
沒有 retry grace。 所以 refresh 呼叫逾時、你不知道成功沒成功時:
- 不可重送同一張 refresh token;
- 拿舊的那一張去 introspect:
active: true→ 那次 refresh 沒生效,可以安全重送;active: false→ 已消耗或已撤,請使用者重新登入; - introspect 也判不了(503)→ 退避重試,不要盲猜。
同一個使用者的 refresh 呼叫一定要序列化:多執行緒或多台機器同時拿同一張去換, 就是製造重放。
/oauth2/introspect(RFC 7662)的限制
| 限制 | 內容 |
|---|---|
| 誰能呼叫 | 只有已啟用的confidential 第三方 client。public client 沒有可認證的東西,一律 401 invalid_client |
| 認證方式 | client_secret_basic 或 client_secret_post,擇一;兩者同時出現是 401 |
| 能查什麼 | 只有你自己的 token。別人的 token、ID token、格式不對的字串都是 {"active": false} |
| 非 active | 一律只回 {"active": false},不分原因(不存在、過期、已消耗、已撤、別人的、session 已結束都長一樣) |
| 判不了 | 503,絕不回 active: true。你這端也要 fail-closed |
| 快取 | 沒有。撤權寫入成功後,下一次 introspect 就是 active: false |
| 限流 | 與登入共用 per-IP 額度,超過回 429 |
| 只適用使用者 token | client_credentials 鑄出來的 service account token 沒有 session,所以 introspect 一律回 {"active": false}——即使那張 token 當下完全有效。機器端要判斷還有沒有權,唯一的權威來源是 Gateway:打 /v1/* 看 200 還是 403(見機器流程) |
active: true 的回應帶 sub、sid、client_id、token_type、exp、iat、
auth_time、acr、tenant_id、scope。幾個容易寫錯的欄位:
| 欄位 | 值 |
|---|---|
token_type |
access token 是 Bearer(RFC 6749 的 token type,不是字串 access_token);refresh token 是 refresh_token |
sid |
32 個小寫十六進位字元(SHA-256 截斷),不是 UUID — 不要拿去 parse 成 UUID |
acr |
目前只有 urn:lightup:loa:1(一般登入)與 urn:lightup:loa:2(做過 step-up) |
auth_time |
使用者當初登入的時間,不是這次 refresh 的時間 |
ID token 不是 access token
登入拿到的 ID token 只用來在你的應用裡確認使用者身分。拿 ID token 呼叫 API 會被擋在第一關(JOSE header typ 不是 at+jwt),回 401 invalid_token。同理,第一方 storefront token 與內部服務的共用 header 也一律 401。
scope 的三層交集
有效 scope = 租戶管理員安裝時核准的能力集合
∩ client 的 allowed_scopes
∩ 使用者當次同意的項目
缺一不可。使用者可以只同意一部分;請以 token 回應裡的 scope 為準,並在少了能力時降級功能,而不是重試。