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

# Đăng xuất app và kết thúc phiên Keycloak

> Đăng xuất ở app phải kết thúc luôn phiên Keycloak, nếu không lần sau Keycloak tự đăng nhập lại người cũ. Cấu hình cho SPA, oauth2-proxy, Superset, Airflow, Grafana, Spring.

Người dùng đăng nhập một lần trên Keycloak rồi dùng nhiều app. Nếu nút Logout của app chỉ xoá phiên của riêng app, phiên Keycloak vẫn còn: lần sau bấm đăng nhập, Keycloak cho vào ngay bằng tài khoản cũ mà không hỏi gì. Trang này hướng dẫn cấu hình để đăng xuất ở app kết thúc luôn phiên Keycloak (RP-initiated logout).

## Cách hoạt động

Sau khi xoá phiên của mình, app chuyển trình duyệt tới end session endpoint của Keycloak:

```text logout-url theme={null}
https://<id-host>/realms/<realm>/protocol/openid-connect/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=<url-encode của trang quay về>
```

| Tham số | Khi nào dùng |
| - | - |
| `id_token_hint` | App còn giữ id token. Keycloak đăng xuất ngay, không hỏi lại |
| `client_id` | App không giữ id token. Keycloak hiện trang hỏi xác nhận một lần, người dùng bấm Logout |
| `post_logout_redirect_uri` | Trang quay về sau khi đăng xuất. Phải có trong "Valid post logout redirect URIs" của client |

> [!WARNING]
>
> Nếu `post_logout_redirect_uri` không nằm trong danh sách đã khai của client (kể cả khi danh sách trống), Keycloak báo "Invalid redirect uri" và không đăng xuất. Luôn ghi post-logout URI trong [yêu cầu client](https://docs.dbiz.com/sso/yeu-cau-client.md).

## Cấu hình theo loại app

> [tab] SPA
>
> `oidc-client-ts` tự gắn `id_token_hint` và `post_logout_redirect_uri` đã khai trong `UserManager`:
>
> ```ts logout.ts theme={null}
> await userManager.signoutRedirect();
> ```

> [tab] oauth2-proxy
>
> Thêm `--backend-logout-url`. Khi người dùng mở `/oauth2/sign_out`, proxy xoá cookie và gọi logout của Keycloak kèm id token, nên người dùng không phải xác nhận.
>
> ```yaml oauth2-proxy theme={null}
> - --backend-logout-url=https://<id-host>/realms/<realm>/protocol/openid-connect/logout?id_token_hint={id_token}
> - --whitelist-domain=<id-host>
> ```
>
> Nút Logout của app phía sau proxy cần trỏ tới `/oauth2/sign_out`.

> [tab] Superset, Airflow
>
> Superset và Airflow dùng Flask-AppBuilder. Flask-AppBuilder chỉ xoá phiên của app rồi chuyển tới `LOGOUT_REDIRECT_URL`. Đặt giá trị này là logout của Keycloak trong file cấu hình Python của app (`superset_config.py`, `webserver_config.py`):
>
> ```python superset_config.py theme={null}
> from urllib.parse import quote
>
> LOGOUT_REDIRECT_URL = (
>     "https://<id-host>/realms/<realm>/protocol/openid-connect/logout"
>     "?client_id=<client-id>"
>     "&post_logout_redirect_uri=" + quote("https://<app-host>/", safe="")
> )
> ```
>
> Flask-AppBuilder không giữ id token nên Keycloak sẽ hỏi xác nhận một lần. Client cần khai `https://<app-host>/` trong post-logout redirect URIs.

> [tab] Grafana
>
> ```ini grafana.ini theme={null}
> [auth]
> signout_redirect_url = https://<id-host>/realms/<realm>/protocol/openid-connect/logout?client_id=<client-id>&post_logout_redirect_uri=https%3A%2F%2F<app-host>%2Flogin
> ```
>
> Client cần khai `https://<app-host>/login` trong post-logout redirect URIs.

> [tab] Spring Boot
>
> ```java SecurityConfig.java theme={null}
> @Bean
> SecurityFilterChain filterChain(HttpSecurity http, ClientRegistrationRepository repo) throws Exception {
>     var logout = new OidcClientInitiatedLogoutSuccessHandler(repo);
>     logout.setPostLogoutRedirectUri("{baseUrl}/");
>     http.oauth2Login(Customizer.withDefaults())
>         .logout(l -> l.logoutSuccessHandler(logout));
>     return http.build();
> }
> ```

> [tab] Mobile
>
> Gọi end session của thư viện với `idTokenHint` và post-logout URL theo custom scheme, rồi xoá token trên máy. Xem mẫu `logout()` ở trang [Mobile](https://docs.dbiz.com/sso/mobile.md).

## Kiểm post-logout URI đã được khai chưa

Gọi end session không cần phiên đăng nhập và xem mã HTTP:

```bash check-logout.sh theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -G \
  https://<id-host>/realms/<realm>/protocol/openid-connect/logout \
  --data-urlencode client_id=<client-id> \
  --data-urlencode post_logout_redirect_uri=https://<app-host>/
```

* `302`: URI hợp lệ, Keycloak sẽ chuyển về đúng trang.
* `400`: URI chưa được khai cho client, đăng xuất sẽ lỗi.

## Giới hạn

Đăng xuất một app kết thúc phiên Keycloak, nhưng không tự đăng xuất các app khác đang mở. Các app đó vẫn giữ phiên riêng tới khi hết hạn, vì đăng xuất đồng loạt cần app hỗ trợ back-channel logout. Khi phép thử cần đổi tài khoản, đăng xuất từng app hoặc dùng cửa sổ ẩn danh.


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