比較：Microsoft Entra ID Auth SDK (sidecar) 與進程內 Microsoft.Identity.Web

本指南可協助你辨識 Microsoft Entra ID Auth SDK（sidecar）與同處理序 Microsoft.Identity.Web 程式庫在應用程式中處理驗證時的差異。 Microsoft。Identity.Web 函式庫可直接整合至 .NET 應用程式中，以提升最大效能。 Microsoft Entra ID Auth SDK（側車）作為獨立容器運行，並透過 HTTP API 支援任何程式語言。 選擇正確的方法取決於你應用程式的架構、語言和部署環境。

架構差異

根本區別在於 身份驗證邏輯的執行位置。 Microsoft。Identity.Web 運行在您的申請流程中。 Microsoft Entra ID 驗證 SDK（sidecar）會作為獨立服務，與您的應用程式並行運作。 這種架構選擇會影響開發工作流程和操作複雜性等因素。

Microsoft。Identity.Web（進行中）

這段程式碼片段展示了如何將 Microsoft.Identity.Web 直接整合到 ASP.NET Core 應用程式中：

// Startup configuration
services.AddMicrosoftIdentityWebApiAuthentication(Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("Graph", Configuration.GetSection("DownstreamApis:Graph"))
    .AddInMemoryTokenCaches();

// Usage in controller
public class MyController : ControllerBase
{
    private readonly IDownstreamApi _downstreamApi;
    
    public MyController(IDownstreamApi downstreamApi)
    {
        _downstreamApi = downstreamApi;
    }
    
    public async Task<ActionResult> GetUserData()
    {
        var user = await _downstreamApi.GetForUserAsync<User>("Graph", 
            options => options.RelativePath = "me");
        return Ok(user);
    }
}

Microsoft Entra ID 身分驗證 SDK（Sidecar）（處理序外）

這段程式碼片段示範如何在 Node.js 應用程式中透過 HTTP 呼叫 Microsoft Entra ID Auth SDK（Sidecar）。 對 SDK 的端點 /DownstreamApi 的呼叫將會處理權杖的取得以及下游的 API 呼叫，其中包括在標頭 Authorization 中傳遞 OBO 流程的傳入權杖。

// Configuration
const SidecarUrl = process.env.SIDECAR_URL || "http://localhost:5000";

// Usage in application
async function getUserData(incomingToken: string) {
  const response = await fetch(
    `${SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me`,
    {
      headers: {
        'Authorization': `Bearer ${incomingToken}`
      }
    }
  );
  
  const result = await response.json();
  return JSON.parse(result.content);
}

特徵比較

何時使用每種方法

在 Microsoft.Identity.Web 與 Microsoft Entra ID Auth SDK（sidecar）之間做選擇，取決於您應用程式的需求、架構和部署策略。 根據你的需求，其中一種方式可能比另一種更合適。 以下指引能幫助你做出明智的決定。

移轉指引

從 Microsoft.Identity.Web 遷移至 Microsoft Entra ID Auth SDK (sidecar)

在某些情況下，你可能會想將使用 Microsoft.Identity.Web 的現有 .NET 應用程式遷移為使用 Microsoft Entra ID Auth SDK（Sidecar）進行驗證。 遷移的原因可能包括採用多語言架構、跨服務標準化認證，或轉向容器化部署模式。

在做出這項變更前，需要仔細考慮與規劃。 本節提供高階移轉路徑，其中包含程式碼範例，以協助您轉換應用程式。

步驟 1：部署 SDK 容器

首先，將 SDK 容器加入你的 pod：

# Before: Single ASP.NET Core container
containers:
- name: app
  image: myregistry/myapp:latest

# After: App + Microsoft Entra ID Auth SDK (sidecar)
containers:
- name: app
  image: myregistry/myapp:latest
  env:
  - name: SIDECAR_URL
    value: "http://localhost:5000"

- name: sidecar
  image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
  env:
  - name: AzureAd__TenantId
    value: "your-tenant-id"
  - name: AzureAd__ClientId
    value: "your-client-id"

步驟 2：移轉組態

接著，將你的設定從appsettings.json轉移到環境變數：

之前（appsettings.json）

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id"
  },
  "DownstreamApis": {
    "Graph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": "User.Read Mail.Read", 
      "RelativePath": "/me"
    }
  }
}

之後（Kubernetes ConfigMap / 環境變數）

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "your-tenant-id"
  AzureAd__ClientId: "your-client-id"
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  DownstreamApis__Graph__RelativePath: "/me"

步驟3：更新申請碼

找出所有對 Microsoft.Identity.Web 的處理序內呼叫，並將其替換為對 Microsoft Entra ID Auth SDK（sidecar）端點發出的 HTTP 呼叫：

之前 （具有 IDownstreamApi 的 C#）：

public class UserController : ControllerBase
{
    private readonly IDownstreamApi _downstreamApi;
    
    public UserController(IDownstreamApi downstreamApi)
    {
        _downstreamApi = downstreamApi;
    }
    
    [HttpGet]
    public async Task<ActionResult<User>> GetMe()
    {
        var user = await _downstreamApi.GetForUserAsync<User>(
            "Graph",
            options => options.RelativePath = "me"
        );
        return Ok(user);
    }
}

之後（任何具有 HTTP 用戶端的語言）：

在以下程式碼片段中，你會看到呼叫 Microsoft Entra ID Auth SDK（sidecar）並透過 /DownstreamApi 端點取得使用者資料。 範例以 C# 和 TypeScript 提供。

public class UserController : ControllerBase
{
    private readonly HttpClient _httpClient;
    private readonly string _SidecarUrl;
    
    public UserController(IHttpClientFactory httpClientFactory, IConfiguration config)
    {
        _httpClient = httpClientFactory.CreateClient();
        _SidecarUrl = config["SIDECAR_URL"];
    }
    
    [HttpGet]
    public async Task<ActionResult<User>> GetMe()
    {
        var inboundAuthorizationHeader = Request.Headers["Authorization"].ToString();
        // this validates the inbound authorization header and calls the downstream API.
        // If you don't call a downstream API, Do validate the inbound authorization header 
        // (calling the /Validate endpoint)
        var request = new HttpRequestMessage(
            HttpMethod.Get,
            $"{_SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me"
        );
        request.Headers.Add("Authorization", inboundAuthorizationHeader);
        
        var response = await _httpClient.SendAsync(request);
        var result = await response.Content.ReadFromJsonAsync<SidecarResponse>();
        var user = JsonSerializer.Deserialize<User>(result.Content);
        return Ok(user);
    }
}

TypeScript

你可以在 TypeScript 中實作相同的邏輯如下：

export async function getMe(incomingToken: string): Promise<User> {
  const SidecarUrl = process.env.SIDECAR_URL!;
  
  const response = await fetch(
    `${SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me`,
    {
      headers: {
        'Authorization': incomingToken
      }
    }
  );
  
  const result = await response.json();
  return JSON.parse(result.content) as User;
}

步驟四：移除 Microsoft。Identity.Web 相依關係

完成前述步驟後，從你的專案中移除 Microsoft.Identity.Web 的 NuGet 套件來整理你的應用程式。

<!-- Remove these from .csproj -->
<PackageReference Include="Microsoft.Identity.Web" Version="..." />
<PackageReference Include="Microsoft.Identity.Web.MicrosoftGraph" Version="..." />
<PackageReference Include="Microsoft.Identity.Web.DownstreamApi" Version="..." />

如果你還想在應用程式中驗證憑證，就不需要移除原本的認證設定。 相反地，你可以將驗證完全交由 Microsoft Entra ID Auth SDK（sidecar）處理。

// Remove from Program.cs or Startup.cs
services.AddMicrosoftIdentityWebApiAuthentication(Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("Graph", Configuration.GetSection("DownstreamApis:Graph"))
    .AddInMemoryTokenCaches();

步驟五：測試與驗證

1. 單元測試：更新測試以模擬 HTTP 呼叫給 SDK。
2. 整合測試：測試 SDK 在預備環境中的溝通。
3. 效能測試：衡量 HTTP 開銷影響。
4. 安全測試：驗證憑證處理與網路政策。

效能考量

SDK 開銷

Microsoft Entra ID 驗證 SDK（sidecar）會產生 HTTP 通訊開銷：

過程中表現

使用 Microsoft。Identity.Web 的開銷很低，因為它和你的應用程式在同一個流程中運作。 它提供原生方法呼叫，具備微秒延遲與共享程序記憶體，且不受 HTTP 限制。 當效能至關重要時，進行中整合是最佳選擇。 然而，Microsoft Entra ID Auth SDK（側車）的彈性與其與程式語言無關的設計，在許多情況下可能勝過效能上的權衡。

下表顯示同處理序使用與 Microsoft Entra ID Auth SDK（Sidecar，處理序外）使用的部分效能和成本比較：

成本考量

成本範例

對於 10 個副本，配備 128 MiB/100m SDK 配置：

支援與維護

混合式方法

你可以在同一架構中結合這兩種方法。 對於要求最高效能的 .NET 服務，請使用 Microsoft.Identity.Web；對於非 .NET 服務，或在需要與程式語言無關的驗證模式時，請使用 Microsoft Entra ID Auth SDK（sidecar）。 這種混合策略幫助您在關鍵時刻優化效能，同時維持整個服務生態系統的一致性與彈性。

以下是一個範例架構：

graph TB
    subgraph cluster["Kubernetes Cluster"]
        subgraph netpod["<b>.NET API Pod</b>"]
            netapi["<b>.NET API</b><br/>(Microsoft.Identity.Web)"]
            style netapi fill:#0078d4,stroke:#005a9e,stroke-width:2px,color:#fff
        end
        subgraph nodepod["<b>Node.js API Pod</b>"]
            nodeapi["<b>Node.js API</b>"]
            sidecar["<b>Microsoft Entra ID Auth SDK (sidecar)</b>"]
            style nodeapi fill:#68a063,stroke:#4a7c45,stroke-width:2px,color:#fff
            style sidecar fill:#f2711c,stroke:#d85e10,stroke-width:2px,color:#fff
        end
    end
    style cluster fill:#f0f0f0,stroke:#333,stroke-width:3px
    style netpod fill:#e8f4f8,stroke:#0078d4,stroke-width:2px
    style nodepod fill:#e8f4e8,stroke:#68a063,stroke-width:2px

相關內容

• 安裝指南
• 組態參考
• 呼叫下游 API
• 概觀