假設使用者有 ORDER_VIEWER 角色，可以查訂單。那麼，他能查所有公司的訂單，還是只有自己廠區的資料？

本篇名詞小筆記

• RBAC：角色型存取控制（Role-Based Access Control），依角色決定使用者可執行哪些功能。
• Scope：Token 中描述授權範圍的欄位，常用來表示呼叫端獲准使用哪些 API 能力。
• Claim：Token 內的一項身分或權限聲明，例如使用者、角色、發行者與有效期限。
• Data Range：資料範圍，進一步限制使用者可以存取哪些公司、廠區、客戶或資料列。
• Authority：Spring Security 把 Token 角色轉成的內部權限字串；hasRole 會自動加 ROLE_ 前綴再比對，hasAuthority 則直接比對原字串。

今天要解決的問題

規格如果只寫「訂單查詢」，實作時還是會遇到很多選擇：全公司的、自己建立的，還是負責客戶的訂單？如果沒有先確認，不同的人很可能做出不同結果，而只有一組廠區資料的測試，也不容易發現。我覺得，這個問題要在寫程式之前就先談清楚。

所以，我會把授權拆成三層，分別確認：

架構師視角：哪一層由誰判斷

角色與部分政策可以由 Keycloak 管理。至於這筆資料屬於誰、使用者能不能操作，往往還要看組織、負責單位與交易狀態。我會把這些判斷留給掌握資料的業務服務。

圖 Day 12-1：三層授權模型。

我會用「做這個決定需要哪些資訊」來安排責任。角色與 scope 可以放進 Token；需要即時確認的組織關係、代理設定或交易狀態，則要另外查。也要想好權限異動後，舊 Token 裡的值還能使用多久。

要注意的是，Data Range 不只是查詢條件。若只在 SQL 加上廠區過濾，那是「查不到」而不是「無權存取」；兩者在稽核與錯誤處理上的意義不同。明確的做法是先判斷授權、再執行查詢，讓拒絕成為可記錄的決定。

工程師視角：權限矩陣、claim 對應與稽核

準備權限矩陣時，我會把角色、API、動作、資料範圍、核准者與複核週期一起列出來。後端先預設拒絕，確認符合規則再放行，大家也比較知道每一項權限是怎麼開出來的。

以 Keycloak 為例，realm 層級角色與 client 層級角色是兩個不同來源：realm 角色通常對應到框架慣例的 ROLE_ 前綴形式，client 角色則保留原始值。兩者混用會出現「權限明明給了卻檢查不到」的情況，因此授權判斷要清楚區分它來自哪一個來源，Token claim 到應用權限的對應也要明確定義。

這條規則我不會散在各個檢查點，而是直接寫進 JWT 轉換器。下面是目前實作的簡化版：

/**
 * Keycloak JWT → Spring Security authorities 對應規則：
 * - realm_access.roles[]        → ROLE_<大寫>（供 hasRole 用）＋ 原始值（供 hasAuthority 用）
 * - resource_access.<*>.roles[] → 原始值（只能用 hasAuthority）
 *
 * 例：realm 角色 EXTERNAL_PARTNER
 *   hasRole("EXTERNAL_PARTNER")      → 比對 ROLE_EXTERNAL_PARTNER
 *   hasAuthority("EXTERNAL_PARTNER") → 比對 EXTERNAL_PARTNER
 *
 * Gateway 為 WebFlux，另有一份 Reactive 版（gateway SecurityConfig.extractAuthorities），
 * 兩邊無法共用；修改本規則時需同步修改該處。
 */
public class KeycloakJwtConverter implements Converter<Jwt, AbstractAuthenticationToken> {

    @Override
    public AbstractAuthenticationToken convert(Jwt jwt) {
        List<GrantedAuthority> authorities = new ArrayList<>();

        // realm_access.roles[] → ROLE_<大寫>，同時保留原始值
        Map<String, Object> realm = jwt.getClaim("realm_access");
        for (String role : rolesOf(realm)) {
            authorities.add(new SimpleGrantedAuthority("ROLE_" + role.toUpperCase()));
            authorities.add(new SimpleGrantedAuthority(role));
        }

        // resource_access.<client>.roles[] → 原始值，不加前綴
        Map<String, Object> resources = jwt.getClaim("resource_access");
        if (resources != null) {
            resources.forEach((clientId, value) -> {
                if (value instanceof Map<?, ?> client) {
                    rolesOf(client).forEach(r -> authorities.add(new SimpleGrantedAuthority(r)));
                }
            });
        }
        return new JwtAuthenticationToken(jwt, authorities);
    }

    @SuppressWarnings("unchecked")
    private static List<String> rolesOf(Map<?, ?> access) {
        if (access == null || access.get("roles") == null) return List.of();
        return (List<String>) access.get("roles");
    }
}

為什麼 realm 角色要輸出兩次？Spring Security 的 hasRole 會自己補 ROLE_ 前綴再找，hasAuthority 不補直接找。只輸出其中一種，就會有一種寫法永遠找不到。兩種都輸出，兩種寫法都能命中。client 角色只輸出原值，檢查時就只能用 hasAuthority。

用一個假設的 token 走一遍，比較容易看出每一行在做什麼（以外部夥伴角色 EXTERNAL_PARTNER 為例）：

{
  "sub": "partner-001",
  "realm_access": { "roles": ["EXTERNAL_PARTNER", "user"] },
  "resource_access": {
    "external-client": { "roles": ["EXTERNAL_PARTNER"] },
    "account":         { "roles": ["view-profile"] }
  }
}

轉換後 authorities 這個 List 裡有六筆（去掉重複後剩五種不同字串）：

再拿幾種常見的檢查寫法對照：

因為 ROLE_ 版本被強制大寫，hasRole 的參數一律要用大寫。角色可能掛在 realm，也可能掛在 client，兩種情況都要能放行，所以 Gateway 對外部夥伴的路徑選用 hasAuthority("EXTERNAL_PARTNER") 而不是 hasRole。這些差別我直接寫在轉換器的類別註解裡，查權限的人不用翻實作就知道該用哪種寫法。註解最後那段也提醒了 Gateway 另有一份 Reactive 版本要同步改。

政策會修改，之後要能知道當時為什麼做出這個決定，所以被拒絕的請求，也要留下能追查的紀錄，尤其要保留政策版本。使用者識別、資源、動作、政策版本與 correlation ID 都很有幫助，但敏感內容要避開。

策略取捨與限制

角色開得太大，容易多給權限；拆得太細，日常維護又會很辛苦。我會一起看使用者因權限求助的情況，再確認角色是不是符合實際分工，避免大家一直靠人工補開權限才能工作。

驗證方式與衡量指標

測試時，我會準備不同公司、不同廠區的資料，再加上停權與撤銷權限的情境。除了確認原本能做的事，也要看看權限改變之後，該擋的操作有沒有真的被擋下來。

今天先整理到這裡

從登入走到資料授權，每一層的責任就比較清楚了。下一篇，回到 ERP 的介接，看看 SOAP 前面加上一層 Adapter，能幫我們整理哪些事情。

參考資料

1. Keycloak, Keycloak Authorization Services，查閱日期：2026-09-25。
2. OWASP, OWASP Authorization Cheat Sheet，查閱日期：2026-09-25。
3. Spring, OAuth 2.0 Resource Server JWT（Reactive），查閱日期：2026-09-25。
4. Spring, Spring WebFlux，查閱日期：2026-09-25。