비교: AgentID용 Microsoft Entra SDK 및 In-Process Microsoft.Identity.Web

이 가이드는 에이전트ID용 Microsoft Entra SDK와 애플리케이션에서 인증을 처리하기 위한 In-process Microsoft.Identity.Web 라이브러리 간의 차이점을 식별하는 데 도움이 됩니다. Microsoft.Identity.Web 라이브러리는 성능을 최대화하기 위해 .NET 애플리케이션에 직접 통합되는 반면, AgentID용 Microsoft Entra SDK는 별도의 컨테이너로 실행되며 HTTP API를 통해 프로그래밍 언어를 지원하며 올바른 방법을 선택하는 것은 애플리케이션의 아키텍처, 언어 및 배포 환경에 따라 달라집니다.

아키텍처 차이점

기본적인 차이점은 인증 논리가 실행되는 위치에 있습니다. Microsoft.Identity.Web은 애플리케이션 프로세스 내에서 실행되며, AgentID용 Microsoft Entra SDK는 애플리케이션과 함께 독립적인 서비스로 작동합니다. 이 아키텍처 선택은 개발 워크플로 및 운영 복잡성과 같은 요인에 영향을 줍니다.

Microsoft.Identity.Web(In-Process)

이 코드 조각은 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);
    }
}

AgentID용 Microsoft Entra SDK(Out-of-Process)

이 코드 조각은 HTTP를 사용하여 Node.js 애플리케이션에서 AgentID용 Microsoft Entra SDK를 호출하는 방법을 보여 줍니다. 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과 AgentID용 Microsoft Entra SDK 중에서 결정하는 것은 애플리케이션의 요구 사항, 아키텍처 및 배포 전략에 따라 달라집니다. 요구 사항에 따라 한 가지 방법이 다른 방법보다 더 적합할 수 있으며 다음 지침은 정보에 입각한 결정을 내리는 데 도움이 될 수 있습니다.

마이그레이션 지침

Microsoft.Identity.Web에서 AgentID용 Microsoft Entra SDK로 마이그레이션

특정 시나리오에서는 Microsoft.Identity.Web을 사용하여 기존 .NET 애플리케이션을 마이그레이션하여 인증을 위해 AgentID용 Microsoft Entra SDK를 활용할 수 있습니다. 마이그레이션의 원인으로는 다국어 아키텍처 채택, 서비스 간 인증 표준화 또는 컨테이너화된 배포 모델로의 이동 등이 있습니다.

그렇게 하기 전에 신중한 고려와 계획이 필요합니다. 이 섹션에서는 애플리케이션을 전환하는 데 도움이 되는 코드 예제와 함께 개략적인 마이그레이션 경로를 제공합니다.

1단계: SDK 컨테이너 배포

먼저 Pod에 SDK 컨테이너를 추가해야 합니다.

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

# After: App + Microsoft Entra SDK for AgentID
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에서 환경 변수로 구성을 전송해야 합니다.

Before(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"
    }
  }
}

After(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에 대한 In-Process 호출의 모든 인스턴스를 찾아서 AgentID 엔드포인트용 Microsoft Entra SDK에 대한 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 클라이언트가 있는 모든 언어)

다음 코드 조각에서는 /DownstreamApi 엔드포인트를 사용하여 사용자 데이터를 가져오기 위해 AgentID를 위한 Microsoft Entra SDK 호출을 확인할 수 있습니다. 예제는 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;
}

4단계: 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="..." />

앱에서 토큰의 유효성을 검사하려는 경우에도 유효성 검사를 AgentID용 Microsoft Entra SDK에 완전히 위임할 수 있지만 원래 인증 구성을 완전히 제거할 필요는 없습니다.

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

5단계: 테스트 및 유효성 검사

1. 단위 테스트: SDK에 대한 모의 HTTP 호출로 테스트 업데이트
2. 통합 테스트: 스테이징에서 SDK 통신 테스트
3. 성능 테스트: HTTP 오버헤드 영향 측정
4. 보안 테스트: 토큰 처리 및 네트워크 정책 유효성 검사

성능 고려 사항

SDK 오버헤드

AgentID용 Microsoft Entra SDK에는 HTTP 통신 오버헤드가 발생합니다.

프로세스 내 성능

Microsoft.Identity.Web을 사용하면 애플리케이션과 동일한 프로세스 내에서 실행되므로 최소한의 오버헤드가 발생하므로 네이티브 메서드 호출에 HTTP 제한 없이 마이크로초 대기 시간 및 공유 프로세스 메모리를 제공합니다. 성능이 중요한 경우 프로세스 내 통합이 최적의 선택이지만 AgentID의 유연성 및 언어 불가지론적 설계를 위한 Microsoft Entra SDK는 많은 시나리오에서 성능 장단점보다 클 수 있습니다.

다음은 In-Process 사용량 및 에이전트 ID용 Microsoft Entra SDK(Out-of-Process) 사용에 대한 몇 가지 성능 및 비용 비교입니다.

비용 고려 사항

비용 예제

128Mi/100m SDK 구성을 사용하는 10개의 복제본의 경우:

지원 및 유지 관리

하이브리드 접근 방식

동일한 아키텍처 내에서 두 가지 방법을 결합할 수 있습니다. 최대 성능이 필요한 .NET 서비스에 Microsoft.Identity.Web을 사용하는 동시에 non-.NET 서비스에 대해 또는 언어에 구애받지 않는 인증 패턴이 필요한 경우 AgentID용 Microsoft Entra SDK를 활용합니다. 이 하이브리드 전략을 사용하면 전체 서비스 에코시스템에서 일관성과 유연성을 유지하면서 중요한 성능을 최적화할 수 있습니다.

예제 아키텍처는 다음과 같습니다.

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 SDK for AgentID</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

다음 단계

• 설치 가이드 - AgentID용 Microsoft Entra SDK 배포
• 구성 참조 - SDK 구성
• 시나리오 - 실제 예제
• Microsoft.Identity.Web 설명서 - In-Process 라이브러리에 대해 알아보기