開發 Web 或桌面應用時，整合第三方登入最常見的方法就是 OAuth2，尤其用於串接 Google、Facebook、LINE、Azure、Auth0 等外部身份服務。需要注意的是：OAuth2 本質上是 授權（Authorization）標準，並不是身份驗證（Authentication）。
實際流程是：先取得授權，再藉由授權去交換 Token 並取回用戶身份資訊。

Bee.OAuth2 套件組包含五個套件，可協助 .NET 開發者快速、安全地整合 OAuth2，無論是在 Web 或 Windows Forms 應用程式中。

• Bee.OAuth2
• Bee.OAuth2.AspNet
• Bee.OAuth2.AspNetCore
• Bee.OAuth2.WinForms
• Bee.OAuth2.Desktop

1️⃣ Bee.OAuth2 – 核心模組

輕量化 .NET OAuth2 函式庫，支援 Google、Facebook、LINE、Azure、Auth0 等供應商的授權流程。

• 目標框架：.NET Standard 2.0
• 用途：取得授權網址、交換 Token、讀取使用者資訊。
• 適用場景：共用程式庫、後端服務。
• 擴充性：原始碼已開放，可自行新增 Provider。

使用範例

var options = new GoogleOAuth2Options {
    ClientId = "...",
    ClientSecret = "...",
    RedirectUri = "http://localhost",
    Scopes = { "openid", "email", "profile" }
};
var provider = new GoogleOAuth2Provider(options);
string authUrl = provider.GetAuthorizationUrl("random_state");

2️⃣ Bee.OAuth2.AspNet – ASP.NET 專用

• 目標框架：.NET Framework 4.8
• 用途：為 ASP.NET WebForms 與 MVC 專案提供簡化的 OAuth2 認證流程。

使用流程

1. 註冊 Client

var options = new GoogleOAuth2Options { ... };
var client  = new OAuth2Client(options);
OAuth2Manager.RegisterClient("Google", client);

2. 導向授權頁

OAuth2Manager.RedirectToAuthorization("Google");

3. 處理回呼並取得使用者資訊

var result = await OAuth2Manager.ValidateAuthorization();

3️⃣ Bee.OAuth2.AspNetCore – ASP.NET Core 專用

• 目標框架：.NET 8+
• 用途：透過 DI 與 OAuth2Manager 集中管理，快速整合多家登入供應商。

使用流程

1. Program.cs 註冊

builder.Services.AddSingleton<OAuth2Manager>(provider => {
    var http = provider.GetRequiredService<IHttpContextAccessor>();
    var options = new GoogleOAuth2Options { ... };
    var client  = new OAuth2Client(options, http);
    var manager = new OAuth2Manager(http);
    manager.RegisterClient("Google", client);
    return manager;
});

2. Controller

public IActionResult Login() {
    _oauth2Manager.RedirectToAuthorization("Google");
    return new EmptyResult();
}

public async Task<IActionResult> Callback() {
    var result = await _oauth2Manager.ValidateAuthorization();
    ...
}

4️⃣ Bee.OAuth2.WinForms – Windows Forms (.NET Framework 4.8)

• 目標框架：.NET Framework 4.8
• 用途：在 WinForms 程式中使用 WebView2 進行 OAuth2 登入。

使用流程

var options = new GoogleOAuth2Options { ... };
var client  = new OAuth2Client(options) {
    Caption = "Google Login",
    Width   = 600,
    Height  = 800
};
OAuth2Manager.RegisterClient("Google", client);
var result = await OAuth2Manager.Login("Google");

5️⃣ Bee.OAuth2.Desktop – Windows Forms (.NET 8+)

• 目標框架：.NET 8+
• 用途：在 Windows Forms (.NET 8+) 應用中整合 OAuth2 登入流程。
• 特色：在 WinForms 程式中使用 WebView2 進行 OAuth2 登入。

使用流程

var options = new GoogleOAuth2Options { ... };
var client  = new OAuth2Client(options) {
    Caption = "Google Login",
    Width   = 600,
    Height  = 800
};
OAuth2Manager.RegisterClient("Google", client);
var result = await OAuth2Manager.Login("Google");

🔑 state 加密機制

在 OAuth2 驗證流程中，state 參數主要用來防止 CSRF 攻擊。
Bee.OAuth2 套件內建 AES-CBC + HMAC 的 state 加密機制：

• 需事先產生 64-byte Base64 金鑰，並設定為 OAUTH2_STATE_KEY 環境變數。
• 若未設定，state 僅做 Base64 編碼，不保證機密性與完整性。

// 產生 Base64 格式的金鑰
var key = Bee.Base.AesCbcHmacKeyGenerator.GenerateCombinedKey();
Console.WriteLine(Convert.ToBase64String(key));

🔍 前後端分離架構下的最佳實踐

若系統採用 前後端分離架構，建議的流程是：
前端僅負責向 Provider 取得授權碼 (Authorization Code)，後端再利用授權碼換取 Token 並取得用戶身份。

這樣可以避免 Client Secret 暴露於前端，並讓身份管理集中於後端，確保安全性與一致性。

流程

1. 前端 (Browser / App)

   • 導向 Google / Facebook / LINE / Azure / Auth0 等授權伺服器。
   • 使用者授權後，伺服器回傳 Authorization Code。

2. 後端 (API Server)

   • 接收授權碼並使用 Client Secret 向 Provider 交換 Access Token / ID Token。
   • 使用 Access Token 呼叫 UserInfo Endpoint 取得用戶資訊。

3. 系統內部

   • 後端確認身份後，產生 Session Token / JWT，回傳給前端使用。

優點

• 安全性：Client Secret 僅在後端保存。
• 一致性：統一身份管理，可整合 RBAC 或內部帳號系統。
• 擴充性：支援多 Provider，最終映射到同一套用戶模型。

Authorization 與 Login 的差異

於 Bee.OAuth2.WinForms 與 Bee.OAuth2.Desktop 套件中，OAuth2Client 提供兩個方法：

📦 套件比較總表

📚 延伸閱讀

• GitHub 原始碼
• OAuth 2.0 規格
• OAuth2 標準參數對照表
• OAuth2 vs OpenID Connect vs SAML 整合認證比較

📢 歡迎轉載，請註明出處
📬 歡迎追蹤我的技術筆記與實戰經驗分享
Facebook ｜ HackMD ｜ GitHub ｜ NuGet