Giao diện

@digiforce-nc/plugin-auth ​

Plugin xác thực (authentication) — quản lý phương thức đăng nhập, phiên làm việc (session/token), và vòng đời tài khoản.

Plugin này làm gì? ​

Hãy hình dung hệ thống như một tòa nhà có nhiều cửa vào. plugin-auth là hệ thống quản lý cửa — nó không quan tâm bạn dùng thẻ từ, vân tay, hay mật khẩu, nó chỉ đảm bảo: ai vào được, vào bằng cách nào, và phiên làm việc kéo dài bao lâu.

Ba nhiệm vụ chính ​

#Nhiệm vụChi tiết
1Authenticator registryĐăng ký, quản lý nhiều phương thức xác thực (email/password, OIDC, LDAP, SMS...)
2Xác minh danh tínhsignIn, signUp, signOut, lostPassword, resetPassword, changePassword
3Token policyQuản lý JWT, thời hạn token, blacklist token, refresh tự động

Kiến trúc ​

Tổng quan các tầng ​

Thành phầnVai trò
AuthManagerRegistry trung tâm quản lý tất cả authenticator type (từ core @digiforce-nc/auth)
BasicAuthAuthenticator mặc định: email/password, hỗ trợ signup form, lost/reset password
StorerLưu + cache danh sách authenticator từ DB, tự động invalidate khi authenticator thay đổi
TokenControllerQuản lý JWT lifecycle: cấp phát, hết hạn, gia hạn
TokenBlacklistServiceRevoke token đã cấp (DB + Redis Bloom filter)

Luồng đăng nhập ​

Luồng quên mật khẩu ​

API endpoints ​

Xác thực ​

EndpointMethodMô tả
/auth:signInPOSTĐăng nhập, trả về token
/auth:signUpPOSTĐăng ký tài khoản mới
/auth:signOutPOSTĐăng xuất, revoke token
/auth:checkGETKiểm tra phiên hiện tại
/auth:changePasswordPOSTĐổi mật khẩu (cần đăng nhập)
/auth:lostPasswordPOSTYêu cầu reset password (gửi email)
/auth:resetPasswordPOSTReset password bằng token

Authenticator management ​

EndpointMethodMô tả
authenticators:listGETDanh sách authenticator (admin)
authenticators:publicListGETDanh sách authenticator cho trang login (public)
authenticators:listTypesGETCác loại authenticator đã đăng ký
authenticators:createPOSTTạo authenticator mới
authenticators:updatePOSTCập nhật cấu hình
authenticators:destroyPOSTXóa (phải còn ít nhất 1 authenticator enabled)

Database ​

BảngChứa gì
authenticatorsPhương thức xác thực (name, type, enabled, options)
usersAuthenticatorsLiên kết user ↔ authenticator (M2M), lưu UUID/meta cho SSO
tokenControlConfigCấu hình token policy (thời hạn, renew limit)
issuedTokensToken đã cấp (jti, userId, timestamps)
tokenBlacklistToken bị revoke

Token policy ​

Plugin quản lý JWT token với các tham số cấu hình:

Tham sốMặc địnhMô tả
Token expiration1 ngàyThời hạn access token
Refresh token expiration7 ngàyThời hạn refresh token
Renew limit1 ngàyGiới hạn gia hạn token

Client tự động gia hạn token khi nhận header x-new-token từ response. Khi token hết hạn hoặc bị revoke, client redirect về trang đăng nhập.

Mở rộng authenticator ​

Plugin khác có thể đăng ký loại authenticator mới:

typescript
class MyOIDCAuth extends BaseAuth {
  async validate() {
    // Logic xác thực OIDC
  }
}

// Trong plugin.load()
this.app.authManager.registerTypes('oidc', {
  auth: MyOIDCAuth,
  title: 'OIDC Login',
});

Các plugin auth provider có sẵn: plugin-auth-oidc, plugin-auth-ldap, plugin-auth-saml, plugin-auth-sms, plugin-auth-cas, plugin-auth-apple, plugin-auth-telegram.

Thành phần client ​

Thành phầnMô tả
AuthProviderProvider quản lý trạng thái xác thực, inject vào app
AuthLayoutLayout cho các trang /signin, /signup, /forgot-password
Trang SignIn/SignUpForm đăng nhập/đăng ký, hiển thị theo authenticator
Authenticator SettingsUI quản lý authenticator (Settings → Authentication)
Token Policy SettingsUI cấu hình token policy (Settings → Security → Token policy)
Axios interceptorTự động refresh token, redirect 401 về sign-in

Dependencies ​

PackageVai trò
@digiforce-nc/authAuthManager, BaseAuth (core)
@digiforce-nc/serverServer framework
@digiforce-nc/databaseDatabase ORM
@digiforce-nc/clientClient framework
@digiforce-nc/actionsAction context

Mục lục chi tiết ​