這個 .NET 8 控制台應用程式示範如何使用 Microsoft Entra ID 認證連接 Azure Managed Redis。 核心價值主張是無 密碼認證 並具備自動令牌更新,提供安全且現代化的 Redis 連線方式。
跳至 GitHub 上的程式碼
將 GitHub 上的 Microsoft.Azure.StackExchangeRedis 儲存庫複製到本地。
Prerequisites
- .NET 8.0 SDK。
- 在你的 Azure 訂閱中配置一個 Azure Managed Redis 實例。
- 你的 Azure 使用者或服務主體必須在快取中新增為 Redis 使用者。 在 Azure 入口網站,點到資源選單的 認證 ,選擇 使用者或服務主體,並新增你的身份。
- Azure CLI 用於本地開發驗證。
必備的 NuGet 套件
| Package | Purpose |
|---|---|
Microsoft.Azure.StackExchangeRedis |
擴充函式庫,為 StackExchange 新增 Microsoft Entra ID 認證功能。Redis |
Azure.Identity |
提供 DefaultAzureCredential 及其他 Azure 身份識別體系實作 |
StackExchange.Redis |
底層的 Redis 客戶端(作為相依性被納入) |
Microsoft.Extensions.Logging.Console |
診斷用的主控台日誌 |
驗證方法
該擴充支援多種身份類型,每種類型都有對應 ConfigureForAzure*() 的擴展方法:
DefaultAzureCredential- 推薦的方法。 它會串連多個憑證來源(環境變數、管理身份、Azure CLI 認證、Visual Studio 憑證等等),並使用第一個有效的憑證來源。 它非常適合同時執行本地和 Azure 的程式碼。使用者指派受管理識別 - 適用於 Azure 託管應用程式,您透過提供用戶端 ID 明確指定要使用的受管理識別。
System-Assigned 受管理身份 - 適用於使用自動指派給資源的身份的Azure託管應用程式。
服務主體(密碼) - 用戶端 ID、租戶 ID 及用於自動化或 CI 情境的密碼。
服務主體(憑證) - 用戶端 ID、租戶 ID 及 X.509 憑證,以提供更高的安全性。
當地運作方式DefaultAzureCredential
當你在本地開發時, DefaultAzureCredential 會嘗試使用以下方法進行驗證:
az login
此方法會透過你的 Microsoft Entra ID 帳號登入 Azure CLI。 SDK 會偵測你快取的憑證,並利用它們取得憑證。 您必須在 Azure 入口網站的資源選單中,透過認證功能,將 Microsoft Entra ID 使用者設定為 Azure 管理 Redis 資源的 Redis 使用者。
關鍵實作模式
連線配置:
ConfigurationOptions configurationOptions = new()
{
Protocol = RedisProtocol.Resp3, // Recommended for seamless re-auth
LoggerFactory = loggerFactory,
AbortOnConnectFail = true, // Fail fast (use false in production)
BacklogPolicy = BacklogPolicy.FailFast
};
Entra ID 設定:
await configurationOptions.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());
var connection = await ConnectionMultiplexer.ConnectAsync(configurationOptions);
基本 Redis 操作:
var database = connection.GetDatabase();
await database.StringSetAsync("key", "value");
var value = await database.StringGetAsync("key");
憑證生命週期與自動重新認證
擴充功能會自動處理 OAuth2 的標記生命週期:
- 初始獲取 ——在連線前會先獲得一個代幣。
- 主動刷新 ——在令牌到期前(大約一小時),它會在背景獲得一個新的令牌。
- 重新驗證 ——它會用新的令牌重新驗證連線,而不丟棄指令。
為了提高可觀察性,你可以訂閱代幣事件:
| Event | Purpose |
|---|---|
TokenRefreshed |
新代幣取得 |
TokenRefreshFailed |
代幣刷新失敗(仍在使用舊代幣) |
ConnectionReauthenticated |
連線成功重新認證 |
ConnectionReauthenticationFailed |
連線重新驗證失敗 |
RESP3 與 RESP2 協議
樣本使用 RESP3 (Protocol = RedisProtocol.Resp3),因為:
- RESP2 會為互動式指令和發佈/訂閱建立獨立連線。
- 只有互動式連線會被主動重新認證。
- 當 Pub/sub 連線的 token 到期時會關閉,導致短暫中斷。
- RESP3 將所有數據多路复用到同一個連線上,避免這些中斷。
Azure 必備條件
- 建立一個 Azure 管理的 Redis 實例。
- 在「資料存取設定」中啟用 Microsoft Entra ID 認證。
- 請以 Redis 使用者身份加入並擁有適當的權限(資料擁有者、資料貢獻者等)。
-
在本機執行
az login以使用您的 Entra ID 帳戶進行驗證。
基本 Redis 概念
| 概念 | Description |
|---|---|
ConnectionMultiplexer |
單例,線程安全的 Redis 連線池。 只建立一次,然後在應用程式的整個生命週期內重複使用。 |
IDatabase |
用於執行指令(StringGet、StringSetHashGet等等)的介面。 |
| 端點格式 |
endpoint:10000(TLS)適用於 Azure Managed Redis。 |
執行範例
az login
cd sample
dotnet run
輸入你的 Redis 端點(例如 <your-redis-name>.<region>.redis.azure.net:10000),選擇驗證方法 1 (DefaultAzureCredential),每當命令成功時,觀察 + 字元每秒印出。 讓它運行超過 60 分鐘,以驗證自動更新權杖是否有效。
生產考量
| Setting | 樣本值 | 生產價值 |
|---|---|---|
AbortOnConnectFail |
true |
false (啟動時重試) |
BacklogPolicy |
FailFast |
Default (在暫態故障期間將指令排入佇列) |
| 連線壽命 | 示範循環 | 辛格爾頓經由DIIConnectionMultiplexer() |
本範例提供完整參考實作,適用於任何使用 Azure Managed Redis 的 .NET 應用程式中安全且無密碼的 Entra ID 認證。