ASP.NET Web Pages - WebSecurity 物件完整參考：身分驗證與會員管理核心 API
WebSecurity 物件封裝 ASP.NET SimpleMembership 提供者，整合帳戶建立、登入登出、密碼重設、角色授權等完整身分管理功能。
WebSecurity 核心屬性
| 屬性 | 型別 | 描述 |
|---|
| CurrentUserId | Int | 目前登入使用者 ID (未登入回傳 -1) |
| CurrentUserName | String | 目前登入使用者名稱 (Email) |
| HasUserId | Boolean | 是否有使用者 ID (等同 IsAuthenticated) |
| IsAuthenticated | Boolean | 目前要求是否經過驗證 |
WebSecurity 核心方法完整參考
| 方法 | 描述 | 關鍵參數 |
|---|
| ChangePassword(userName, currentPassword, newPassword) | 變更密碼 (需舊密碼驗證) | 使用者名、舊密碼、新密碼 |
| ConfirmAccount(accountConfirmationToken) | 確認帳戶 (Email 驗證流程) | 驗證 Token |
| CreateAccount(userName, password, requireConfirmation) | 建立帳戶 (舊版 API) | 使用者名、密碼、需確認 |
| CreateUserAndAccount(userName, password, propertyValues, requireConfirmation) | 建立使用者與擴充屬性 (推薦) | 使用者名、密碼、匿名型別屬性、需確認 |
| GeneratePasswordResetToken(userName, tokenExpirationInMinutes) | 產生密碼重設 Token (寄送 Email 連結) | 使用者名、Token 有效分鐘數 |
| GetCreateDate(userName) | 取得帳戶建立日期 | 使用者名 |
| GetPasswordChangeDate(userName) | 取得最後變更密碼日期 | 使用者名 |
| GetUserId(userName) | 依使用者名取得 UserId | 使用者名 |
| InitializeDatabaseConnection(connStringName, userTable, userIdColumn, userNameColumn, autoCreateTables) | 初始化資料庫連線 (必要步驟) | 連線名、使用者表、ID 欄、名稱欄、自動建表 |
| IsConfirmed(userName) | 檢查帳戶是否已確認 | 使用者名 |
| IsCurrentUser(userName) | 檢查是否為目前登入使用者 | 使用者名 |
| Login(userName, password, persistCookie) | 登入使用者 (建立驗證 Cookie) | 使用者名、密碼、記住我 |
| Logout() | 登出 (清除驗證 Cookie) | 無 |
| RequireAuthenticatedUser() | 未驗證則拋 401 (授權攔截) | 無 |
| RequireRoles(roles...) | 非指定角色則拋 401 | 角色名稱陣列 |
| RequireUser(userName) | 非指定使用者則拋 401 | 使用者名 |
| ResetPassword(passwordResetToken, newPassword) | 重設密碼 (Token 驗證後) | 重設 Token、新密碼 |
| UserExists(userName) | 檢查使用者是否存在 | 使用者名 |
技術規格
| 項目 | 值 |
|---|
| 類別完整名稱 | WebMatrix.WebData.WebSecurity |
| 命名空間 | WebMatrix.WebData |
| 組件 | WebMatrix.WebData.dll |
資料庫初始化：_AppStart.cshtml 關鍵設定
@{
WebSecurity.InitializeDatabaseConnection(
connectionStringName: "DefaultConnection", // Web.config 連線字串名稱
userTableName: "UserProfile", // 使用者資料表
userIdColumn: "UserId", // 主鍵欄位
userNameColumn: "Email", // 使用者名稱欄位 (Email)
autoCreateTables: true // 自動建立資料表
);
}
參數詳細說明：
- connectionStringName：對應
Web.config <connectionStrings> 的 name 屬性
- userTableName：儲存使用者基本資料的表格 (預設 UserProfile)
- userIdColumn：主鍵欄位，通常為
UserId (INT IDENTITY)
- userNameColumn：唯一識別使用者的欄位，現代應用建議使用
Email
- autoCreateTables：
true 自動建立 UserProfile 與 webpages_Membership 表，**但不會自動建立資料庫本身** (資料庫必須預先存在)
資料庫結構：SimpleMembership 雙表架構
UserProfile 表 - 使用者基本資料
| UserId (PK) | Email |
|---|
| 1 | john@johnson.net |
| 2 | peter@peterson.com |
| 3 | lars@larson.eut |
webpages_Membership 表 - 會員驗證資料
| UserId | CreateDate | ConfirmationToken | IsConfirmed | Password | PasswordChangeDate |
|---|
| 1 | 2024-01-15 | NULL | True | AHashedValue... | 2024-01-15 |
其他欄位：LastPasswordFailureDate、PasswordFailuresSinceLastSuccess、PasswordVerificationToken、PasswordVerificationTokenExpirationDate 等安全稽核欄位。
常見問題：SimpleMembership 相容性設定
若部署環境與開發環境設定不一致，可能出現初始化錯誤。解決方案：在 Web.config 加入：
<appSettings>
<add key="enableSimpleMembership" value="true" />
<add key="autoFormsAuthentication" value="true" />
</appSettings>
遷移指引：現代專案請使用 ASP.NET Core Identity
| 特性 | WebSecurity (SimpleMembership) | ASP.NET Core Identity |
|---|
| 架構 | WebMatrix 封裝 | 模組化、DI 原生、跨平台 |
| 資料存取 | ADO.NET 直連 | EF Core / 自訂 Store |
| 密碼雜湊 | PBKDF2 (固定) | PBKDF2/Argon2/BCrypt 可換 |
| Two-Factor Auth | 不支援 | 內建 TOTP、SMS、Email |
| 外部登入 | OAuthWebSecurity (舊) | Microsoft.AspNetCore.Authentication 完整支援 |
| Claims-based | 不支援 | 核心架構 |
現有專案可漸進式遷移：新功能採用 Identity，舊模組維持 WebSecurity 並共用 UserProfile 資料表。
