Hướng dẫn cài đặt OIDC

Hướng dẫn từng bước thiết lập xác thực OpenID Connect trong Digiforce, bao gồm cấu hình IdP phổ biến và kiểm tra kết nối.

Điều kiện tiên quyết

• Digiforce đã cài đặt và chạy ổn định
• Plugin @digiforce-nc/plugin-auth-oidc đã được kích hoạt
• Tài khoản admin trên Identity Provider (Google, Azure AD, Keycloak...)

Bước 1: Tạo authenticator trong Digiforce

1. Vào Settings → Authentication → Add new
2. Chọn loại OIDC
3. Đặt tên authenticator (ví dụ: google-sso, azure-ad)
4. Lưu lại — hệ thống sẽ tạo sẵn Redirect URI

Redirect URI cần đăng ký tại IdP có dạng:

https://your-domain.com/api/oidc:redirect

Bước 2: Cấu hình Identity Provider

Google Workspace

1. Truy cập Google Cloud Console → APIs & Services → Credentials
2. Tạo OAuth 2.0 Client ID loại Web application
3. Thêm Redirect URI: https://your-domain.com/api/oidc:redirect
4. Sao chép Client ID và Client Secret
5. Issuer URL: https://accounts.google.com

Azure AD (Entra ID)

1. Truy cập Azure Portal → App registrations → New registration
2. Redirect URI: chọn Web, nhập https://your-domain.com/api/oidc:redirect
3. Vào Certificates & secrets → New client secret — sao chép giá trị
4. Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0
5. Client ID: lấy từ Application (client) ID trong Overview

Keycloak

1. Tạo Client trong Realm → Clients → Create client
2. Client type: OpenID Connect
3. Valid redirect URIs: https://your-domain.com/api/oidc:redirect
4. Bật Client authentication → sao chép Client Secret từ tab Credentials
5. Issuer URL: https://keycloak.example.com/realms/{realm-name}

Bước 3: Điền thông số vào Digiforce

Quay lại Settings → Authentication → chọn authenticator đã tạo:

Trường	Giá trị
Issuer	URL issuer từ IdP (bắt buộc)
Client ID	Client ID từ IdP
Client Secret	Client Secret từ IdP
Scope	openid email profile (mặc định)

Các trường khác có thể giữ mặc định cho lần cấu hình đầu tiên.

Bước 4: Kiểm tra đăng nhập

1. Mở cửa sổ ẩn danh (incognito) của trình duyệt
2. Truy cập trang đăng nhập Digiforce
3. Nhấn nút Đăng nhập bằng OIDC (tên hiển thị theo authenticator)
4. Hệ thống redirect đến IdP → đăng nhập → quay về Digiforce

Xác minh thành công

• User xuất hiện trong danh sách Users với email từ IdP
• Nếu bật autoSignup, user mới được tạo tự động
• Kiểm tra log server nếu có lỗi: tìm keyword oidc trong console

Bước 5: Tùy chỉnh nâng cao (tùy chọn)

• Auto-redirect: bật autoRedirect nếu chỉ dùng một IdP duy nhất
• Field mapping: cấu hình fieldMap để map custom claims sang local fields
• RP-initiated logout: bật enableRPInitiatedLogout nếu IdP hỗ trợ
• HTTP/Port: điều chỉnh nếu Digiforce chạy sau reverse proxy

Xem chi tiết tại Tham số cấu hình.

Lưu ý bảo mật

• Luôn dùng HTTPS trong production — chỉ bật http khi phát triển local
• Không chia sẻ Client Secret — lưu trữ qua biến môi trường khi có thể
• Bật skipSSLVerification chỉ khi debug, không dùng trong production