Câu hỏi thường gặp (FAQ) — IDP OAuth

Câu hỏi chung

Plugin này khác gì với plugin-auth-oidc?

Tiêu chí	plugin-auth-oidc	plugin-idp-oauth
Vai trò	DigiForce là client	DigiForce là server (IdP)
Mục đích	Đăng nhập bằng provider bên ngoài (Google, Azure AD)	Cho ứng dụng bên ngoài đăng nhập bằng tài khoản DigiForce
Giao thức	OAuth 2.0 / OIDC client	OAuth 2.1 / OIDC provider

Bắt buộc phải dùng HTTPS?

Có. OAuth 2.1 yêu cầu HTTPS để bảo vệ token và authorization code trong quá trình truyền tải. Trong môi trường development, bạn có thể tạm dùng HTTP nhưng không được dùng HTTP trong production.

Có thể tạo nhiều OAuth Application không?

Có. Mỗi ứng dụng bên ngoài nên có OAuth Application riêng với client_id và client_secret riêng. Điều này giúp:

• Kiểm soát quyền truy cập (scopes) cho từng ứng dụng
• Thu hồi quyền cho một ứng dụng mà không ảnh hưởng ứng dụng khác
• Theo dõi hoạt động của từng ứng dụng

Plugin hỗ trợ những protocol nào?

• OAuth 2.1: Phiên bản mới nhất, bắt buộc PKCE cho public client
• OpenID Connect (OIDC): Layer xác thực trên OAuth, cung cấp ID token và UserInfo

Cấu hình

Redirect URI không khớp, báo lỗi?

Redirect URI phải khớp chính xác, bao gồm:

• Protocol: http vs https
• Domain: myapp.com vs www.myapp.com
• Port: myapp.com:3000 vs myapp.com
• Path: /callback vs /callback/
• Trailing slash: có hoặc không

Làm sao tạo PKCE flow cho SPA/Mobile?

Ứng dụng SPA/Mobile dùng code_verifier và code_challenge thay vì client_secret:

1. Client tạo code_verifier (chuỗi ngẫu nhiên 43-128 ký tự)
2. Tính code_challenge = BASE64URL(SHA256(code_verifier))
3. Gửi code_challenge khi authorize
4. Gửi code_verifier khi exchange token

Scopes mặc định hỗ trợ những gì?

Plugin hỗ trợ 4 scope mặc định:

Scope	Dữ liệu	Bắt buộc
openid	Subject identifier (sub)	✅ (cho OIDC)
profile	name, nickname, picture	❌
email	email, email_verified	❌
offline_access	Cấp refresh token	❌

Xử lý lỗi thường gặp

Lỗi "invalid_grant" khi exchange authorization code

Nguyên nhân phổ biến:

1. Code đã được sử dụng — authorization code chỉ dùng được một lần
2. Code hết hạn — mặc định 10 phút
3. Redirect URI không khớp — redirect_uri khi exchange phải giống lúc authorize
4. Client credentials sai — client_id hoặc client_secret không đúng

Token hết hạn, user bị đăng xuất?

Ứng dụng bên ngoài cần implement refresh token flow:

POST /api/idpOAuth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN_VALUE
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

User thay đổi mật khẩu, token có bị vô hiệu hoá không?

Không tự động. Để vô hiệu hoá, cần:

• Thu hồi token thủ công qua revoke endpoint
• Hoặc cấu hình hook để revoke tất cả token khi password thay đổi

Lỗi "invalid_client"

1. Kiểm tra client_id chính xác
2. Kiểm tra client_secret chính xác (lưu ý: secret chỉ hiện một lần khi tạo)
3. Đảm bảo OAuth Application chưa bị xoá hoặc vô hiệu hoá

Discovery endpoint trả về URL sai

Plugin tính toán URL dựa trên API_BASE_PATH (mặc định /api). Nếu DigiForce chạy sau reverse proxy, đảm bảo:

• Header X-Forwarded-Proto được truyền đúng
• API_BASE_PATH khớp với cấu hình proxy