登記與憑證
第三方應用要能呼叫 API,需要三樣東西:應用(application)、client、service account(只有機器流程需要)。
誰做什麼
| 角色 | 做什麼 |
|---|---|
| 發布者(你) | 提供應用名稱、用途、redirect URI、要用的能力清單、聯絡窗口 |
| 平台團隊 | 開通租戶(見下)、必要時以內部路由代填設定 |
| 租戶管理員(租戶 owner) | 在 LightUp Dashboard 的「整合」頁完成登記與日常管理 |
租戶管理員在「整合」頁做什麼
Dashboard 的「整合」頁已經上線,下面每一件事都是租戶管理員自己按的,不再是人工流程:
| 動作 | 說明 |
|---|---|
| 登記應用 | 填名稱與用途,選這支應用是使用者登入、機器對機器還是兩者。選了使用者登入就要給 redirect URI;選了機器對機器,這支 client 才拿得到 client_credentials |
| 維護網址 | 登記之後可以改 redirect URI、post-logout redirect URI 與 back-channel logout URI(規則見使用者流程的「logout 登記」) |
| 核准與撤回能力 | 逐項勾選能力索引裡的 id;撤回在下一個請求生效 |
| Service account | 建立、輪替 secret、停用,以及重新啟用 |
| 用量 | 看這支應用各 service account 的使用情形 |
「整合」頁打不開開關,表示這個租戶的方案不含第三方整合(頁面會寫明目前方案與門檻),或平台暫停了這個租戶。方案夠的租戶,由租戶 owner 在同一頁自己打開;開啟後才能登記應用與建立 service account(停用與撤回不受開關限制)。見起步。
發布者(你)要提供的是下面「登記需要的資料」;實際按下去的人是租戶管理員。
Client
- client id 由平台配發,形狀
tp_<租戶標籤>_<slug>,全域唯一。不接受自選字串直接寫入。 - 第三方 client 有幾條硬性限制,註冊時就會被拒,不是默默忽略:
- redirect URI 一律精確比對;不支援子網域萬用字元。public client 另外允許 loopback(RFC 8252 §7.3)。
- 不得使用
native_credentialgrant、web handoff,或任何 refresh 放寬(reuse grace/sliding/absolute-max 一律視為 0)。 - 不得標記為平台第一方。
- 同一支應用可以同時有互動(使用者)與背景(機器)授權,但兩者必須分開可辨認。互動授權失敗不可以改用背景憑證完成同一個操作。
Service account(機器流程)
- 主體是 service account,不是 client。client 憑證證明「哪支程式」,service account 才是「誰在平台裡做事」,id 形狀
acc_…。 - 每個租戶為每一項整合建立可獨立停用的 service account。不共用一張跨租戶的高權限帳號。
- 憑證輪替:建立
nextsecret → 兩把並存最長 7 天 → promote(next變current,舊的立即失效)。兩把並存期間,平台分別記錄哪一把被用到,所以輪替是可驗收的,不是盲切。 - 撤銷:停用帳號,或推進 actor epoch。在途 token 在下一個請求就失效(見撤權語意)。停用之後可以由租戶管理員在「整合」頁重新啟用。
- service account 的 token 不能用 introspect 判斷有效性:它沒有 session,
/oauth2/introspect一律回{"active": false},即使那張 token 當下完全可用。要知道機器端還有沒有權,就打一次/v1/*看回 200 還是 403(見撤權語意)。
登記需要的資料
| 欄位 | 說明 |
|---|---|
| 應用名稱與發布者 | 會顯示在使用者同意頁上 |
| 用途說明 | 一句話說明這支應用拿這些資料做什麼 |
| 能力清單 | 從能力索引挑,逐項列出,不要寫「全部」 |
| Client 型態 | public(行動/桌面/SPA,強制 PKCE)或 confidential(有伺服器端) |
| Redirect URI | 精確值,逐一列出;只有使用者流程需要 |
| 技術窗口 | 處理撤權、輪替、事故通知 |
| extension 需求 | 若要寫 metadata,說明用途、欄位與預估筆數(見 Metadata) |
憑證的保管
- client secret 與 service account secret 只在伺服器端保存。行動 App 與瀏覽器前端不得內嵌任何機器憑證——要代表使用者,就走 authorization code + PKCE。
- 不要把憑證放進版本控制、log、錯誤回報或本文件的範例設定檔。範例用的
.env.example只有合成值。 - 懷疑外洩:立刻要求撤銷(停用帳號或推進 epoch),再輪替。撤銷在下一個請求生效,不必等 token 過期。