> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kiểm access token Keycloak trong API backend

> Những điểm API backend phải kiểm khi nhận access token Keycloak: chữ ký JWKS, iss, aud, azp, hạn dùng, kèm mẫu Python PyJWT và Spring Boot.

API chỉ nhận token do app khác gửi tới (resource server) không cần client riêng. API tự kiểm access token trên mỗi request bằng khoá công khai của Keycloak. Trang này liệt kê các điểm phải kiểm và mẫu cho Python và Spring Boot.

## Các điểm phải kiểm

| Kiểm | Giá trị |
| - | - |
| Chữ ký | JWKS tại `/protocol/openid-connect/certs`, thuật toán RS256. Cache khoá theo `kid`, tải lại khi gặp `kid` lạ vì Keycloak có xoay khoá |
| `iss` | `https://<id-host>/realms/<realm>`, khớp tuyệt đối |
| `exp`, `nbf`, `iat` | Cho phép lệch đồng hồ tối đa 60 giây |
| `aud` | Chứa tên API hoặc client mong đợi |
| `azp` | Thuộc danh sách client được phép gọi API |
| `typ` | `Bearer`, để loại id token và refresh token |
| Quyền | `realm_access.roles` hoặc `groups` |

> [!NOTE]
>
> Mặc định access token của Keycloak chỉ có `aud: account`. Muốn kiểm `aud`, hãy yêu cầu client phát token có audience mapper trỏ tới tên API của bạn.

Nếu nhiều client cùng gọi một API (ví dụ bản web, mobile, desktop của cùng app), quy tắc dễ bảo trì là: chấp nhận khi `aud` chứa tên API, hoặc `azp` nằm trong danh sách được phép. Kiểm cứng một giá trị `azp` duy nhất sẽ chặn các bản còn lại.

## Mẫu Python (PyJWT)

```python verify_token.py theme={null}
import jwt

ISS = "https://<id-host>/realms/<realm>"
jwks = jwt.PyJWKClient(f"{ISS}/protocol/openid-connect/certs", cache_keys=True)
ALLOWED_AZP = {"<client-a>", "<client-b>"}

def verify(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token).key
    claims = jwt.decode(
        token, key, algorithms=["RS256"], issuer=ISS,
        audience="<api-or-client>", leeway=60,
        options={"require": ["exp", "iat", "iss", "aud"]},
    )
    if claims.get("azp") not in ALLOWED_AZP:
        raise PermissionError("azp")
    return claims
```

## Mẫu Spring Boot

```yaml application.yaml theme={null}
spring.security.oauth2.resourceserver.jwt:
  issuer-uri: https://<id-host>/realms/<realm>
  audiences: <api-or-client>
```

Backend chạy cùng hạ tầng với Keycloak có thể tải JWKS qua địa chỉ nội bộ do đội vận hành cung cấp (`jwk-set-uri`), nhưng `issuer-uri` vẫn là địa chỉ công khai.

## Phân biệt token người dùng và token máy

Token của service account có `preferred_username` dạng `service-account-<client-id>` và `azp` là client đó. Nếu API có thao tác chỉ dành cho người dùng thật, hãy kiểm điều này. Xem [Service-to-service](https://docs.dbiz.com/sso/service-to-service.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.