Tham số cấu hình OIDC

Tài liệu chi tiết tất cả tham số cấu hình của plugin @digiforce-nc/plugin-auth-oidc.

Tham số bắt buộc

Tham số	Kiểu	Mặc định	Mô tả
issuer	string	—	URL của OIDC Issuer. Plugin sử dụng OIDC Discovery (/.well-known/openid-configuration) để tự động lấy endpoints. Ví dụ: https://accounts.google.com
clientId	string	—	Client ID được cấp bởi Identity Provider
clientSecret	string	—	Client Secret tương ứng

Tham số scope và token

Tham số	Kiểu	Mặc định	Mô tả
scope	string	openid email profile	Danh sách scope cách nhau bởi dấu cách. Phải bao gồm openid theo chuẩn OIDC
idTokenSignedResponseAlg	string	RS256	Thuật toán ký id_token. Các giá trị phổ biến: RS256, ES256, PS256
stateToken	string	—	Secret key để ký state parameter (CSRF protection). Nếu không đặt, hệ thống sử dụng key mặc định
exchangeBodyKeys	string[]	[]	Danh sách key bổ sung gửi kèm khi exchange authorization code lấy token. Hữu ích khi IdP yêu cầu thêm parameter

Tham số userinfo

Tham số	Kiểu	Mặc định	Mô tả
userInfoMethod	string	GET	Phương thức HTTP gọi userinfo endpoint: GET hoặc POST
accessTokenVia	string	header	Cách gửi access_token khi gọi userinfo: header (Authorization Bearer), body (form body), hoặc query (query string)

Tham số user binding

Tham số	Kiểu	Mặc định	Mô tả
userBindField	string	email	Field dùng để liên kết user từ IdP với local user. Giá trị hỗ trợ: email hoặc username
fieldMap	array	[]	Mảng các object mapping từ OIDC claims sang local user fields. Mỗi phần tử có dạng { source: "claim_name", target: "local_field" }
public.autoSignup	boolean	true	Tự động tạo tài khoản local nếu user chưa tồn tại. Khi false, chỉ user đã có tài khoản mới đăng nhập được

Tham số redirect và network

Tham số	Kiểu	Mặc định	Mô tả
http	boolean	false	Dùng HTTP thay vì HTTPS cho redirect URI. Chỉ bật khi phát triển local
port	string	—	Port tùy chỉnh cho redirect URI. Hữu ích khi chạy sau reverse proxy với port khác
autoRedirect	boolean	false	Tự động redirect đến IdP thay vì hiển thị trang đăng nhập. Phù hợp khi chỉ dùng một authenticator duy nhất
skipSSLVerification	boolean	false	Bỏ qua kiểm tra SSL certificate. Chỉ dùng khi debug, không bao giờ bật trong production

Tham số logout

Tham số	Kiểu	Mặc định	Mô tả
enableRPInitiatedLogout	boolean	false	Bật RP-initiated logout. Khi user logout khỏi Digiforce, plugin gửi yêu cầu logout đến IdP kèm id_token_hint. Yêu cầu IdP hỗ trợ end_session_endpoint

Redirect URI

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

{protocol}://{host}:{port}{API_BASE_PATH}oidc:redirect

Trong đó:

• protocol: https (mặc định) hoặc http nếu bật tham số http
• host: domain của Digiforce
• port: port tùy chỉnh (nếu có)
• API_BASE_PATH: mặc định /api/

Ví dụ: https://app.example.com/api/oidc:redirect

Cấu hình qua biến môi trường

Tất cả tham số đều có thể cấu hình qua biến môi trường với prefix tương ứng. Ví dụ:

OIDC_ISSUER=https://accounts.google.com
OIDC_CLIENT_ID=xxx
OIDC_CLIENT_SECRET=yyy

Ví dụ cấu hình đầy đủ

{
  "issuer": "https://accounts.google.com",
  "clientId": "123456.apps.googleusercontent.com",
  "clientSecret": "GOCSPX-xxxxx",
  "scope": "openid email profile",
  "idTokenSignedResponseAlg": "RS256",
  "userBindField": "email",
  "fieldMap": [
    { "source": "email", "target": "email" },
    { "source": "name", "target": "nickname" },
    { "source": "picture", "target": "avatar" }
  ],
  "autoRedirect": false,
  "enableRPInitiatedLogout": true,
  "public": {
    "autoSignup": true
  }
}

Ví dụ cấu hình Keycloak với tùy chỉnh nâng cao

{
  "issuer": "https://keycloak.example.com/realms/my-realm",
  "clientId": "digiforce-app",
  "clientSecret": "secret-from-keycloak",
  "scope": "openid email profile roles",
  "userInfoMethod": "GET",
  "accessTokenVia": "header",
  "userBindField": "email",
  "http": false,
  "skipSSLVerification": false,
  "enableRPInitiatedLogout": true,
  "public": {
    "autoSignup": true
  }
}