LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

使用者流程(authorization code + PKCE)

使用者本人在你的應用裡操作自己的資料時走這條。發出的 token 是 profile self。

v1 沒有代理。 「A 代表 B 操作」的 delegated profile 是 v2 規劃中的範圍,本版不提供。不要用 self token 加上自訂 header 假裝代理——平台不會承認。

流程

  1. 產生 code_verifier(43–128 字元的高熵隨機字串)與 code_challenge = BASE64URL(SHA256(code_verifier))。
  2. 把使用者導到授權端點:
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
  1. 使用者登入並在同意頁核准。同意頁顯示應用名稱、發布者、請求的能力(用目錄裡的說明文字,不是 raw scope 字串),以及撤銷入口。
  2. 平台導回你的 redirect_uri,帶 code 與 state。先比對 state,不符就中止。
  3. 用 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 是必填

Redirect URI

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)

/oauth2/logout(RP-Initiated Logout)

瀏覽器綁定:不是同一個瀏覽器會先看到確認頁。 發出登出請求的瀏覽器若不是那顆 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 登記表單的欄位裡, 而是一份旁掛的登記值。申請方式:

  1. 把要登記的 URI 交給租戶 owner,由 owner 在 LightUp Dashboard 的「整合」頁送出; 或由平台操作者用內部路由代填。
  2. 第三方不會、也不能直接呼叫這條內部 API——它在 internal 面,需要平台的 internal token。你提供值,平台寫入。
  3. 登記是整份覆寫:每次送出的就是完整清單,省略某一項等於清空它。要改一個 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。

後果講清楚:

驗證方式:登記完成後,在 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,平台當成竊用訊號處理:

  1. 整個 token family 立刻撤銷;
  2. 而且那條 family 綁定的整顆登入 session 被結束;
  3. 這顆 session 上所有第三方 app 都收到 back-channel logout。

也就是說:你一次錯誤的重送,會把使用者從所有第三方 app 登出。

沒有 retry grace。 所以 refresh 呼叫逾時、你不知道成功沒成功時:

同一個使用者的 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 為準,並在少了能力時降級功能,而不是重試。