> ## 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 web có backend hoặc oauth2-proxy với Keycloak

> Cấu hình client confidential cho web có backend, kèm mẫu oauth2-proxy, Auth.js và Spring Boot để đăng nhập qua Keycloak bằng Authorization Code.

Web có backend giữ được bí mật phía máy chủ, nên dùng client confidential có client secret. App không tự làm đăng nhập thì có thể đặt sau oauth2-proxy. Trang này gồm cấu hình client và mẫu cho oauth2-proxy, Next.js Auth.js và Spring Boot.

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

| Thuộc tính | Giá trị |
| - | - |
| Client authentication | On (client confidential, có secret) |
| Standard flow | On. Nên bật thêm PKCE S256 ở phía app hoặc proxy |
| Direct access, Implicit | Off |
| Service account | Off. Backend cần gọi API bằng danh tính riêng thì xin client riêng, xem [Service-to-service](https://docs.dbiz.com/sso/service-to-service.md) |
| Valid redirect URIs | `https://<app-host>/oauth2/callback` (oauth2-proxy) hoặc callback của framework |
| Valid post logout redirect URIs | Trang quay về sau khi đăng xuất |
| Web origins | `https://<app-host>` nếu frontend gọi Keycloak bằng JavaScript; không cần nếu chỉ chuyển hướng |
| Scope `organization` | Mặc định, nếu app chặn người ngoài organization |

> [!WARNING]
>
> Client secret đọc từ kho secret của nền tảng qua biến môi trường. Không đưa secret vào mã nguồn hay image. App đọc biến môi trường lúc khởi động, nên sau khi xoay secret phải khởi động lại app.

## Mẫu oauth2-proxy

```yaml oauth2-proxy theme={null}
- name: oauth2-proxy
  image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.4
  args:
    - --provider=oidc
    - --oidc-issuer-url=https://<id-host>/realms/<realm>
    - --client-id=<client-id>
    - --redirect-url=https://<app-host>/oauth2/callback
    - --upstream=http://127.0.0.1:<port-app>
    - --http-address=0.0.0.0:4180
    - --reverse-proxy=true
    - --code-challenge-method=S256
    - --scope=openid email profile organization:<org>
    - --oidc-groups-claim=organization
    - --allowed-group=<org>                        # chặn người ngoài organization
    - --email-domain=*
    - --cookie-secure=true
    - --cookie-csrf-per-request=true               # tránh lỗi PKCE khi mở nhiều tab
    - --cookie-csrf-per-request-limit=5
    - --backend-logout-url=https://<id-host>/realms/<realm>/protocol/openid-connect/logout?id_token_hint={id_token}
    - --whitelist-domain=<id-host>
  env:
    - name: OAUTH2_PROXY_CLIENT_SECRET
      valueFrom: { secretKeyRef: { name: <ten-secret>, key: client-secret } }
    - name: OAUTH2_PROXY_COOKIE_SECRET
      valueFrom: { secretKeyRef: { name: <ten-secret>, key: proxy-cookie-secret } }
```

Muốn phân quyền theo group thay vì organization: đặt `--oidc-groups-claim=groups` và `--allowed-group=/nhom-cha/NHOM_CON` (đường dẫn đầy đủ).

`--backend-logout-url` giúp nút đăng xuất của proxy (`/oauth2/sign_out`) kết thúc luôn phiên Keycloak. Xem [Đăng xuất](https://docs.dbiz.com/sso/dang-xuat.md).

> [!NOTE]
>
> oauth2-proxy đọc discovery ngay lúc khởi động. Issuer sai hoặc Keycloak chưa sẵn sàng thì proxy thoát và app phía sau ngừng phục vụ.

## Mẫu Next.js Auth.js

```bash .env theme={null}
AUTH_URL=https://<app-host>
AUTH_KEYCLOAK_ISSUER=https://<id-host>/realms/<realm>
AUTH_KEYCLOAK_ID=<client-id>
AUTH_KEYCLOAK_SECRET=<doc-tu-kho-secret>
```

## Mẫu Spring Boot

```yaml application.yaml theme={null}
spring.security.oauth2.client:
  provider.keycloak.issuer-uri: https://<id-host>/realms/<realm>
  registration.keycloak:
    client-id: <client-id>
    client-secret: ${KEYCLOAK_CLIENT_SECRET}
    authorization-grant-type: authorization_code
    scope: openid
    redirect-uri: "{baseUrl}/login/oauth2/code/keycloak"
```

## Backend chạy cùng hạ tầng với Keycloak

Nếu đội vận hành cung cấp địa chỉ nội bộ của Keycloak, backend có thể tải discovery và JWKS qua địa chỉ đó để không vòng ra Internet. Issuer vẫn khai là địa chỉ công khai `https://<id-host>/realms/<realm>`; chỉ đổi URL tải metadata.


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