# Bee.OAuth2 for .NET：快速整合 OAuth2 登入
>開發 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。
### 使用範例
```csharp
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
```csharp
var options = new GoogleOAuth2Options { ... };
var client = new OAuth2Client(options);
OAuth2Manager.RegisterClient("Google", client);
```
2. 導向授權頁
```csharp
OAuth2Manager.RedirectToAuthorization("Google");
```
3. 處理回呼並取得使用者資訊
```csharp
var result = await OAuth2Manager.ValidateAuthorization();
```
---
## 3️⃣ Bee.OAuth2.AspNetCore – ASP.NET Core 專用
- **目標框架**：.NET 8+
- **用途**：透過 DI 與 OAuth2Manager 集中管理，快速整合多家登入供應商。
### 使用流程
1. Program.cs 註冊
```csharp
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
```csharp
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
- **用途**：在 Windows Forms 應用中整合 OAuth2 登入流程。
- **特色**：在 WinForms 程式中使用 WebView2 進行 OAuth2 登入。
### 使用流程
```csharp
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 登入。
### 使用流程
```csharp
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 編碼，**不保證機密性與完整性**。
```csharp
// 產生 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` 提供兩個方法：
| 方法 | 功能 | 適用情境 |
|-------------------|------|----------|
| **Authorization()** | 僅取得授權碼 (Authorization Code)。 | 前後端分離：前端將授權碼交給後端換取 Token 與身份。 |
| **Login()** | 直接交換 Token 並回傳用戶身份 (`AuthorizationResult`)。 | 桌面應用或單機情境，需立即取得身份。 |
---
## 📦 套件比較總表
| 套件名稱 | 目標框架 | 適用場景 | NuGet 連結 |
|-------------------------|--------------------|--------------------|-----------|
| **Bee.OAuth2** | .NET Standard 2.0 | 核心程式庫、後端服務 | [NuGet](https://www.nuget.org/packages/Bee.OAuth2) |
| **Bee.OAuth2.AspNet** | .NET Framework 4.8 | ASP.NET WebForm/MVC | [NuGet](https://www.nuget.org/packages/Bee.OAuth2.AspNet) |
| **Bee.OAuth2.AspNetCore** | .NET 8+ | ASP.NET Core API/MVC | [NuGet](https://www.nuget.org/packages/Bee.OAuth2.AspNetCore) |
| **Bee.OAuth2.WinForms** | .NET Framework 4.8 | Windows Forms 應用 | [NuGet](https://www.nuget.org/packages/Bee.OAuth2.WinForms) |
| **Bee.OAuth2.Desktop** | .NET 8+ | Windows Forms 應用 | [NuGet](https://www.nuget.org/packages/Bee.OAuth2.Desktop) |
---
## 📚 延伸閱讀
- [GitHub 原始碼](https://github.com/jeff377/bee-oauth2)
- [OAuth 2.0 規格](https://datatracker.ietf.org/doc/html/rfc6749)
- [OAuth2 標準參數對照表](https://hackmd.io/@jeff377/oauth2-parameters)
- [OAuth2 vs OpenID Connect vs SAML 整合認證比較](https://hackmd.io/@jeff377/oauth2-vs-oidc-vs-saml)
---
**📢 歡迎轉載，請註明出處**
**📬 歡迎追蹤我的技術筆記與實戰經驗分享**
[Facebook](https://www.facebook.com/profile.php?id=61574839666569) ｜ [HackMD](https://hackmd.io/@jeff377) ｜ [GitHub](https://github.com/jeff377) ｜ [NuGet](https://www.nuget.org/profiles/jeff377)
Sign in with Wallet
Connect another wallet