feat(authentication): Implement email verification, two-factor authentication, and social login features

- Added endpoints for sending and confirming email verification, enhancing user account security. - Integrated two-factor authentication (2FA) with TOTP support, including enabling, verifying, and disabling 2FA. - Implemented social login functionality for Google and Facebook, allowing users to authenticate using their existing accounts. - Updated dependency injection to include services for email, 2FA, and social login. - Enhanced documentation to reflect new features and usage examples for email verification and 2FA.
2026-01-12 23:07:53 +07:00
parent 83b007c8ef
commit 928a22fe3e
124 changed files with 9569 additions and 24 deletions
--- a/docs/en/architecture/security-architecture.md
+++ b/docs/en/architecture/security-architecture.md
@@ -89,10 +89,24 @@ sequenceDiagram
 - Refresh: Database SHA-256 hash
 - Rotation: New refresh token on each use

-**4. MFA Support**:
- TOTP (Time-based One-Time Password)
- Backup codes (10 single-use)
- Recovery email verification
+**4. MFA Support (Two-Factor Authentication)**:
+- TOTP (Time-based One-Time Password) using RFC 6238
+- QR code generation for authenticator apps (Google Authenticator, Authy)
+- Recovery codes (10 single-use codes)
+- Secret key storage: UserManager.SetAuthenticationTokenAsync
+
+**5. Email Verification**:
+- SMTP-based verification emails via MailKit
+- Token generation using UserManager.GenerateEmailConfirmationTokenAsync
+- Verification link with token and userId
+- EmailConfirmed flag set true upon confirmation
+
+**6. Social Login (OAuth2 Providers)**:
+- Google OAuth 2.0 integration
+- Facebook OAuth integration
+- Account linking for existing users (by email match)
+- Auto email confirmation for social logins
+- Provider info stored via UserManager.AddLoginAsync

 ## Authorization Model

--- a/docs/en/guides/iam-authentication.md
+++ b/docs/en/guides/iam-authentication.md
@@ -4,10 +4,13 @@

 ## Overview

-The IAM Service provides OAuth2/OIDC authentication using OpenIddict:
+The IAM Service provides OAuth2/OIDC authentication using Duende IdentityServer:
 - **Password Grant** - User login with email/password
 - **Refresh Token** - Token renewal without re-authentication
 - **Client Credentials** - Service-to-service authentication
+- **Email Verification** - SMTP-based email confirmation
+- **Two-Factor Authentication (2FA)** - TOTP with QR code and recovery codes
+- **Social Login** - Google and Facebook OAuth integration

 ## Quick Start

@@ -142,6 +145,29 @@ curl -X POST http://localhost:5001/connect/token \
 | `POST` | `/api/v1/auth/change-password` | Change password (auth required) |
 | `POST` | `/api/v1/auth/logout` | Revoke tokens (auth required) |

+### Email Verification
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v1/auth/send-verification-email` | Send email verification link (auth required) |
+| `POST` | `/api/v1/auth/confirm-email` | Confirm email with token |
+
+### Two-Factor Authentication (2FA)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v1/auth/2fa/enable` | Enable 2FA (get QR code) (auth required) |
+| `POST` | `/api/v1/auth/2fa/verify` | Verify TOTP code & activate (auth required) |
+| `POST` | `/api/v1/auth/2fa/disable` | Disable 2FA (auth required) |
+
+### Social Login
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/auth/external-login/{provider}` | Initiate OAuth flow (Google/Facebook) |
+| `GET` | `/api/v1/auth/external-callback` | Handle OAuth callback |
+| `GET` | `/api/v1/auth/linked-accounts` | Get linked OAuth providers (auth required) |
+
 ### User Management

 | Method | Endpoint | Description |
@@ -197,6 +223,94 @@ client.DefaultRequestHeaders.Authorization =
 var user = await client.GetFromJsonAsync<UserDto>("/api/v1/users/me");
 ```

+## Email Verification
+
+### Send Verification Email
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/send-verification-email \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+### Confirm Email
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/confirm-email \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user-guid", "token": "confirmation-token"}'
+```
+
+## Two-Factor Authentication (2FA)
+
+### Enable 2FA
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/enable \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "secretKey": "JBSWY3DPEHPK3PXP",
+    "qrCodeBase64": "data:image/png;base64,...",
+    "recoveryCodes": ["code1", "code2", "code3"]
+  }
+}
+```
+
+### Verify 2FA Code
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/verify \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "123456"}'
+```
+
+### Disable 2FA
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/disable \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "123456"}'
+```
+
+## Social Login
+
+### Initiate OAuth Flow
+
+Redirect user to:
+```
+GET http://localhost:5001/api/v1/auth/external-login/Google?returnUrl=http://your-app/callback
+GET http://localhost:5001/api/v1/auth/external-login/Facebook?returnUrl=http://your-app/callback
+```
+
+### Get Linked Accounts
+
+```bash
+curl http://localhost:5001/api/v1/auth/linked-accounts \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "linkedProviders": [
+      {"provider": "Google", "providerDisplayName": "Google"},
+      {"provider": "Facebook", "providerDisplayName": "Facebook"}
+    ]
+  }
+}
+```
+
 ## Error Responses

 ### Common Errors
--- a/docs/vi/architecture/security-architecture.md
+++ b/docs/vi/architecture/security-architecture.md
@@ -112,10 +112,24 @@ sequenceDiagram
 - Refresh: Database SHA-256 hash
 - Rotation: Refresh token mới mỗi lần sử dụng

-**4. MFA Support**:
- TOTP (Time-based One-Time Password)
- Backup codes (10 single-use)
- Recovery email verification
+**4. MFA Support (Xác thực Hai yếu tố)**:
+- TOTP (RFC 6238) cho authenticator apps
+- QR code để thiết lập (Google Authenticator, Authy)
+- Recovery codes (10 mã dùng một lần)
+- Secret key lưu qua UserManager.SetAuthenticationTokenAsync
+
+**5. Email Verification (Xác minh Email)**:
+- Gửi email xác minh qua SMTP (MailKit)
+- Token generation: UserManager.GenerateEmailConfirmationTokenAsync
+- Link xác minh với token và userId
+- Đặt EmailConfirmed = true khi xác nhận
+
+**6. Social Login (Đăng nhập Mạng xã hội)**:
+- Tích hợp Google OAuth 2.0
+- Tích hợp Facebook OAuth
+- Liên kết tài khoản cho users hiện có (theo email)
+- Tự động xác nhận email cho social logins
+- Lưu provider info qua UserManager.AddLoginAsync

 ### EN: Authentication Details

@@ -135,10 +149,24 @@ sequenceDiagram
 - Refresh: Database SHA-256 hash
 - Rotation: New refresh token on each use

-**4. MFA Support**:
- TOTP (Time-based One-Time Password)
- Backup codes (10 single-use)
- Recovery email verification
+**4. MFA Support (Two-Factor Authentication)**:
+- TOTP (Time-based One-Time Password) using RFC 6238
+- QR code generation for authenticator apps (Google Authenticator, Authy)
+- Recovery codes (10 single-use codes)
+- Secret key storage: UserManager.SetAuthenticationTokenAsync
+
+**5. Email Verification**:
+- SMTP-based verification emails via MailKit
+- Token generation using UserManager.GenerateEmailConfirmationTokenAsync
+- Verification link with token and userId
+- EmailConfirmed flag set true upon confirmation
+
+**6. Social Login (OAuth2 Providers)**:
+- Google OAuth 2.0 integration
+- Facebook OAuth integration
+- Account linking for existing users (by email match)
+- Auto email confirmation for social logins
+- Provider info stored via UserManager.AddLoginAsync

 ## Mô hình Phân quyền / Authorization Model

--- a/docs/vi/guides/iam-authentication.md
+++ b/docs/vi/guides/iam-authentication.md
@@ -4,10 +4,13 @@

 ## Tổng Quan

-IAM Service cung cấp xác thực OAuth2/OIDC sử dụng OpenIddict:
+IAM Service cung cấp xác thực OAuth2/OIDC sử dụng Duende IdentityServer:
 - **Password Grant** - Đăng nhập user với email/password
 - **Refresh Token** - Làm mới token mà không cần xác thực lại
 - **Client Credentials** - Xác thực service-to-service
+- **Email Verification** - Xác minh email qua SMTP
+- **Two-Factor Authentication (2FA)** - TOTP với QR code và recovery codes
+- **Social Login** - Tích hợp OAuth Google và Facebook

 ## Bắt Đầu Nhanh

@@ -142,6 +145,29 @@ curl -X POST http://localhost:5001/connect/token \
 | `POST` | `/api/v1/auth/change-password` | Đổi mật khẩu (cần auth) |
 | `POST` | `/api/v1/auth/logout` | Thu hồi tokens (cần auth) |

+### Xác Minh Email
+
+| Method | Endpoint | Mô tả |
+|--------|----------|-------|
+| `POST` | `/api/v1/auth/send-verification-email` | Gửi link xác minh email (cần auth) |
+| `POST` | `/api/v1/auth/confirm-email` | Xác nhận email với token |
+
+### Xác Thực Hai Yếu Tố (2FA)
+
+| Method | Endpoint | Mô tả |
+|--------|----------|-------|
+| `POST` | `/api/v1/auth/2fa/enable` | Bật 2FA (lấy QR code) (cần auth) |
+| `POST` | `/api/v1/auth/2fa/verify` | Xác minh mã TOTP & kích hoạt (cần auth) |
+| `POST` | `/api/v1/auth/2fa/disable` | Tắt 2FA (cần auth) |
+
+### Đăng Nhập Mạng Xã Hội
+
+| Method | Endpoint | Mô tả |
+|--------|----------|-------|
+| `GET` | `/api/v1/auth/external-login/{provider}` | Khởi tạo OAuth flow (Google/Facebook) |
+| `GET` | `/api/v1/auth/external-callback` | Xử lý OAuth callback |
+| `GET` | `/api/v1/auth/linked-accounts` | Lấy danh sách OAuth providers đã liên kết (cần auth) |
+
 ### Quản Lý User

 | Method | Endpoint | Mô tả |
@@ -197,6 +223,94 @@ client.DefaultRequestHeaders.Authorization =
 var user = await client.GetFromJsonAsync<UserDto>("/api/v1/users/me");
 ```

+## Xác Minh Email
+
+### Gửi Email Xác Minh
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/send-verification-email \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+### Xác Nhận Email
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/confirm-email \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user-guid", "token": "confirmation-token"}'
+```
+
+## Xác Thực Hai Yếu Tố (2FA)
+
+### Bật 2FA
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/enable \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "secretKey": "JBSWY3DPEHPK3PXP",
+    "qrCodeBase64": "data:image/png;base64,...",
+    "recoveryCodes": ["code1", "code2", "code3"]
+  }
+}
+```
+
+### Xác Minh Mã 2FA
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/verify \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "123456"}'
+```
+
+### Tắt 2FA
+
+```bash
+curl -X POST http://localhost:5001/api/v1/auth/2fa/disable \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "123456"}'
+```
+
+## Đăng Nhập Mạng Xã Hội
+
+### Khởi Tạo OAuth Flow
+
+Chuyển hướng user đến:
+```
+GET http://localhost:5001/api/v1/auth/external-login/Google?returnUrl=http://your-app/callback
+GET http://localhost:5001/api/v1/auth/external-login/Facebook?returnUrl=http://your-app/callback
+```
+
+### Lấy Danh Sách Tài Khoản Liên Kết
+
+```bash
+curl http://localhost:5001/api/v1/auth/linked-accounts \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "linkedProviders": [
+      {"provider": "Google", "providerDisplayName": "Google"},
+      {"provider": "Facebook", "providerDisplayName": "Facebook"}
+    ]
+  }
+}
+```
+
 ## Xử Lý Lỗi

 ### Các Lỗi Thường Gặp