> ## 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.

# Kết nối app desktop và CLI với Keycloak

> Đăng nhập Keycloak từ app desktop bằng redirect loopback 127.0.0.1 theo RFC 8252, và từ CLI không có trình duyệt bằng Device Authorization Grant.

App desktop mở được trình duyệt nên dùng Authorization Code kèm PKCE và nhận kết quả ở một cổng loopback trên `127.0.0.1` (RFC 8252). CLI hoặc thiết bị không có trình duyệt dùng Device Authorization Grant: người dùng đăng nhập trên một máy khác bằng mã ngắn.

## Desktop: redirect về loopback

### Cấu hình cần cung cấp cho client

| Thuộc tính | Giá trị |
| - | - |
| Client authentication | Off (client public), PKCE `S256` |
| Direct access, Implicit, Service account, Device | Off |
| Valid redirect URIs | `http://127.0.0.1/*` |
| Valid post logout redirect URIs | `http://127.0.0.1/*` |
| Web origins | Để trống |

Khai một lần `http://127.0.0.1/*` thì Keycloak nhận mọi cổng (RFC 8252 mục 7.3), ví dụ `http://127.0.0.1:53682/callback` hay `http://127.0.0.1:49152/`.

> [!WARNING]
>
> Dùng `127.0.0.1`, không dùng `localhost`. Khi client chỉ khai `http://127.0.0.1/*`, redirect về `http://localhost:<cong>` bị từ chối với lỗi `Invalid parameter: redirect_uri`.

### Luồng

**1. Mở cổng loopback**

App mở một cổng ngẫu nhiên trên `127.0.0.1`.

**2. Mở trình duyệt**

App mở trình duyệt hệ thống tới trang đăng nhập với `redirect_uri=http://127.0.0.1:<cong>/callback` và `code_challenge`.

**3. Nhận code**

Sau khi người dùng đăng nhập, trình duyệt quay về cổng đó kèm `code`.

**4. Đổi code lấy token**

App gửi `code` và `code_verifier` tới token endpoint, nhận token rồi đóng cổng.

```python desktop_login.py theme={null}
# Python (authlib): mở trình duyệt, nhận code ở loopback
from authlib.integrations.requests_client import OAuth2Session

ISS = "https://<id-host>/realms/<realm>"
s = OAuth2Session("<desktop-client-id>", redirect_uri=f"http://127.0.0.1:{port}/callback",
                  scope="openid", code_challenge_method="S256")
url, state = s.create_authorization_url(f"{ISS}/protocol/openid-connect/auth",
                                        code_verifier=verifier)
# ... mở url, chờ callback trên cổng port, rồi:
tok = s.fetch_token(f"{ISS}/protocol/openid-connect/token",
                    authorization_response=callback_url, code_verifier=verifier)
```

## CLI: Device Authorization Grant

### Cấu hình cần cung cấp cho client

| Thuộc tính | Giá trị |
| - | - |
| Client authentication | Off (client public) |
| OAuth 2.0 Device Authorization Grant | On |
| Standard flow | Có thể Off |

> [!NOTE]
>
> Client dùng device grant cần thêm một bước chuẩn bị phía nền tảng. Báo trước khi gửi yêu cầu.

```bash device-login.sh theme={null}
ISS=https://<id-host>/realms/<realm>

# 1) Xin device code
curl -s -d client_id=<cli-client-id> -d scope=openid \
  $ISS/protocol/openid-connect/auth/device
# -> device_code, user_code, verification_uri_complete, interval, expires_in

# 2) Người dùng mở verification_uri_complete và đăng nhập

# 3) CLI hỏi lại mỗi `interval` giây cho tới khi có token
curl -s -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=<cli-client-id> -d device_code=<device_code> \
  $ISS/protocol/openid-connect/token
```


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