Role, group, mapper và nội dung token

Bài này lo phần đưa đúng thông tin vào token. Phần Spring đọc claim rồi map thành authority đã có ở 4.4.8.

1. Bài toán

• order-service cần biết customer_id (id trong DB shop) để lọc đơn của khách, không muốn tra bằng email.
• Nhân viên support cần quyền order:read, order:refund; quản lý thêm quyền khác. Có 50 nhân viên.
• payment-service phải từ chối token không dành cho nó.

2. Vấn đề

• Gán role từng user một: 50 người × 5 role, dễ sót khi người chuyển bộ phận.
• Mặc định token chứa mọi role của user ở mọi client: token phình, lộ thông tin thừa.
• Không có claim aud đúng: token cho shop-web dùng được ở mọi service.

3. Giải pháp

4. Code từng bước

Bước 1: Role và group

Clients → order-service → Roles: order:read, order:refund
Realm roles → support (Composite: order-service order:read, order:refund)
Groups → /staff/support → Role mapping: support
Users → bob → Groups: join /staff/support

Bước 2: User attribute + mapper customer_id

Realm settings → User profile → Create attribute: customer_id
   (chỉ admin được sửa, user không tự sửa được)
Client scopes → Create "shop-customer" (type Default)
   → Mappers → By configuration → User Attribute
       User attribute: customer_id
       Token claim name: customer_id
       Claim JSON type: long
       Add to access token: On, Add to ID token: Off
Clients → shop-web → Client scopes → Add "shop-customer" (Default)

Bước 3: Audience

Clients → shop-web → Client scopes → shop-web-dedicated → Add mapper → Audience
   Included Client Audience: order-service
   Add to access token: On

Và giữ token gọn: shop-web → Dedicated scope → Scope tab → Full scope allowed: Off, chỉ thêm customer và role của order-service.

Bước 4: Xem token

# Admin console: Clients → shop-web → Client scopes → Evaluate → chọn user → Generated access token
# Hoặc decode token lấy được:
echo "$ACCESS_TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq

{
  "iss": "http://localhost:8080/realms/shop",
  "aud": ["order-service"],
  "azp": "shop-web",
  "sub": "8f1c...",
  "customer_id": 1042,
  "realm_access": { "roles": ["customer"] },
  "scope": "openid profile email",
  "exp": 1760430000
}

Phía Java chỉ cần đọc claim:

@GetMapping("/orders")
List<OrderDto> myOrders(@AuthenticationPrincipal Jwt jwt) {
    long customerId = ((Number) jwt.getClaim("customer_id")).longValue();
    return orderService.findByCustomer(customerId);
}

5. Cách hoạt động

user bob
  ├─ group /staff/support ── role support (composite)
  │                             ├─ order-service: order:read
  │                             └─ order-service: order:refund
  └─ attribute customer_id
         |
   Keycloak phát token cho client X:
   1. Gom role hiệu lực (trực tiếp + group + composite mở rộng)
   2. Lọc theo scope của client X (Full scope allowed? client scope role mappings)
   3. Chạy mapper của các client scope được yêu cầu → thêm claim
   4. Ký JWT bằng key realm

6. So sánh: token lifetime (Realm settings → Tokens / Sessions)

Session và refresh token chi tiết ở bài 12.5.

7. Khi nào nên dùng / không nên dùng

• Nên: gán role qua group; claim nghiệp vụ nhỏ, ổn định (id) qua mapper; audience cho từng service.
• Không nên: nhét danh sách đơn hàng, quyền theo từng record, hay dữ liệu hay đổi vào token. Quyền theo dữ liệu (đơn này của ai) kiểm tra ở service.

Tăng buffer chỉ là chữa cháy. Cách đúng là bớt thứ không cần:

1. Full scope allowed: Off cho mọi client, chỉ thêm role client đó dùng.
2. Bỏ mapper Group Membership nếu không ai đọc claim groups; group dùng để gán role, không cần trong token.
3. Dùng composite role thay vì hàng chục role nhỏ, nếu service chỉ cần quyền gộp.
4. Bỏ claim profile thừa khỏi access token (để ở ID token hoặc userinfo).
5. Gỡ client scope roles khỏi client không cần role (ví dụ client chỉ cần đăng nhập).

Thông tin lớn hoặc hay đổi thì service tự tra (cache) theo sub.

Không lỗi. Role được "chụp" vào access token lúc phát. Service verify JWT offline, không hỏi lại Keycloak, nên token cũ còn hiệu lực tới exp (5 phút). Lần refresh tiếp theo token mới sẽ không còn role.

• Chấp nhận độ trễ = access token lifespan; đó là lý do giữ nó ngắn.
• Thao tác nhạy cảm (refund lớn): service gọi token introspection hoặc kiểm tra thêm ở DB.
• Muốn cắt ngay: logout session của bob (bài 12.5).

Q1. Bạn gán quyền cho user trong Keycloak thế nào?

🇻🇳 Tiếng Việt:

Quyền chi tiết là client role của từng service, gộp thành composite role theo nghiệp vụ, gán composite role cho group, rồi đưa user vào group. Đổi bộ phận chỉ cần đổi group.

🇬🇧 English:

Fine-grained permissions are client roles per service, grouped into composite roles per job function, assigned to groups, and users join groups. When someone changes team we only change their group.

Q2. Thêm claim tùy biến như customer_id vào token thế nào?

🇻🇳 Tiếng Việt:

Khai báo user attribute trong user profile, tạo client scope có User Attribute mapper, bật add to access token, gán scope cho client. Thêm audience mapper để aud chứa service đích.

🇬🇧 English:

Declare a user attribute in the user profile, create a client scope with a User Attribute mapper that adds it to the access token, and assign the scope to the client. An audience mapper puts the target service into aud.

Q3. Làm sao giữ token nhỏ?

🇻🇳 Tiếng Việt:

Tắt Full scope allowed, chỉ cho role liên quan vào token, bỏ mapper group và claim profile không dùng, không để dữ liệu hay đổi trong token.

🇬🇧 English:

Turn off full scope allowed so only relevant roles are included, remove unused group and profile mappers, and keep frequently changing data out of the token.

Cách nhớ ngắn gọn

• Client role → composite → group → user.
• Claim mới = user attribute + mapper trong client scope.
• Audience mapper cho aud; Full scope allowed Off cho token gọn.
• Đổi role có hiệu lực ở token sau.