Chi tiết luồng xác thực OIDC

Mô tả chi tiết luồng Authorization Code của plugin OIDC, bao gồm CSRF protection, token exchange, user mapping và RP-initiated logout.

Tổng quan luồng

Plugin sử dụng Authorization Code Flow theo chuẩn OIDC. Luồng bao gồm: tạo auth URL → redirect đến IdP → callback với code → exchange token → lấy userinfo → tạo/liên kết user.

Sequence diagram chi tiết

Chi tiết state parameter

State chứa các thông tin cần thiết để xử lý callback:

Field	Mô tả
`token`	CSRF token ngẫu nhiên, so khớp với giá trị trong cookie
`name`	Tên authenticator (phân biệt khi có nhiều OIDC authenticator)
`app`	Tên ứng dụng (`__appName`) — dùng trong kiến trúc multi-app
`redirect`	URL redirect sau khi đăng nhập thành công

State được lưu trong cookie digiforce_oidc với thuộc tính httpOnly. Khi callback trả về, server so sánh token trong state URL với token trong cookie để chống CSRF.

Gateway middleware (multi-app)

Trong kiến trúc multi-app, gateway middleware đóng vai trò giải mã state từ callback URL và chuyển tiếp request đến đúng ứng dụng:

IdP gọi callback URL chung
Gateway đọc state parameter → giải mã ra app name
Gateway forward request đến ứng dụng tương ứng
Ứng dụng xử lý token exchange và user mapping

Field mapping

fieldMap cho phép map OIDC claims sang local user fields. Ví dụ:

json

[
  { "source": "email", "target": "email" },
  { "source": "name", "target": "nickname" },
  { "source": "picture", "target": "avatar" },
  { "source": "preferred_username", "target": "username" }
]

Plugin duyệt qua từng entry trong fieldMap, lấy giá trị từ userinfo response theo source và gán vào local user field theo target.

Luồng RP-initiated logout

Khi bật enableRPInitiatedLogout, plugin thực hiện logout đồng bộ với IdP:

Yêu cầu IdP hỗ trợ end_session_endpoint trong OIDC Discovery metadata.

Xử lý lỗi

Tình huống	Hành vi
State mismatch	Trả 401 — thường do cookie hết hạn hoặc CSRF attack
Token exchange thất bại	Trả lỗi từ IdP (invalid_grant, invalid_client...)
Userinfo thất bại	Trả lỗi tùy theo `accessTokenVia` và IdP response
User không tồn tại + `autoSignup=false`	Trả 401 — yêu cầu admin tạo user trước