Comparaison : Microsoft Entra SDK pour l’ID de l’agent et In-Process Microsoft. Identity.Web

Ce guide vous aide à identifier les différences entre le SDK Microsoft Entra pour l'ID d'agent et la bibliothèque Microsoft.Identity.Web en cours de traitement pour la gestion de l'authentification dans vos applications. La bibliothèque Microsoft.Identity.Web s’intègre directement aux applications .NET pour des performances maximales. Le sdk Microsoft Entra pour l’ID d’agent s’exécute en tant que conteneur distinct et prend en charge n’importe quel langage de programmation via des API HTTP. Le choix de l’approche appropriée dépend de l’architecture, du langage et de l’environnement de déploiement de votre application.

Différences architecturales

La différence fondamentale réside dans l’exécution de la logique d’authentification. Microsoft. Identity.Web s’exécute dans votre processus d’application. Le sdk Microsoft Entra pour l’ID d’agent fonctionne en tant que service indépendant en même temps que votre application. Ce choix architectural a un impact sur des facteurs tels que le flux de travail de développement et la complexité opérationnelle.

Microsoft.Identity.Web (in-process)

Cet extrait de code montre comment Microsoft. Identity.Web s’intègre directement dans une application 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 SDK pour l’ID de l’agent (hors processus)

Cet extrait de code montre comment appeler le KIT de développement logiciel (SDK) Microsoft Entra pour l’ID de l’agent à partir d’une application Node.js à l’aide de HTTP. L'appel à l'endpoint du SDK gère l'acquisition de jetons /DownstreamApi et les appels d'API en aval, y compris la transmission du jeton entrant pour les flux OBO dans l'en-tête Authorization :

// 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);
}

Comparaison des fonctionnalités

Quand utiliser chaque approche

Choix entre Microsoft. Identity.Web et le sdk Microsoft Entra pour l'ID d'agent dépendent des exigences, de l'architecture et de la stratégie de déploiement de votre application. Selon vos besoins, une approche peut être plus appropriée que l’autre. Les instructions suivantes peuvent vous aider à prendre une décision éclairée.

Conseils sur la migration

Migration de Microsoft.Identity.Web vers Microsoft Entra SDK pour AgentID

Dans certains scénarios, vous pouvez migrer une application .NET existante qui utilise Microsoft. Identity.Web pour tirer parti du sdk Microsoft Entra pour l’ID d’agent pour l’authentification. Les raisons de la migration peuvent inclure l’adoption d’une architecture multi-langage, la normalisation de l’authentification entre les services ou le passage à un modèle de déploiement conteneurisé.

Une considération et une planification minutieuses sont requises avant d’apporter cette modification. Cette section fournit un chemin de migration de haut niveau avec des exemples de code pour vous aider à migrer votre application.

Étape 1 : Déployer un conteneur sdk

Tout d’abord, ajoutez le conteneur du Kit de développement logiciel (SDK) à votre pod :

# 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"

Étape 2 : Migrer la configuration

Ensuite, transférez votre configuration de appsettings.json vers les variables d’environnement :

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 / Variables d’environnement)

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"

Étape 3 : Mettre à jour le code de l’application

Recherchez toutes les instances d’appels in-process vers Microsoft.Identity.Web et remplacez-les par des appels HTTP vers le SDK Microsoft Entra pour les points de terminaison de l'ID d'agent.

Avant (C# avec IDownstreamApi) :

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);
    }
}

Après (n’importe quelle langue avec le client HTTP) :

Dans l'extrait de code suivant, vous voyez des appels au SDK Microsoft Entra pour l'ID de l'agent en utilisant le point de terminaison /DownstreamApi pour obtenir des données utilisateur. Des exemples sont fournis en C# et 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

Vous pouvez implémenter la même logique dans TypeScript comme suit :

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;
}

Étape 4 : Supprimer les dépendances Microsoft.Identity.Web

Une fois les étapes précédentes terminées, nettoyez votre application en supprimant les packages NuGet pour Microsoft.Identity.Web à partir de votre projet.

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

Si vous souhaitez toujours valider des jetons dans votre application, vous n’avez pas besoin de supprimer la configuration d’authentification d’origine. Au lieu de cela, vous pouvez déléguer entièrement la validation au SDK Microsoft Entra pour AgentID.

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

Étape 5 : Tester et valider

1. Tests unitaires : Mettez à jour les tests pour simuler des appels HTTP au Kit de développement logiciel (SDK).
2. Tests d’intégration : Tester la communication du Kit de développement logiciel (SDK) en préproduction.
3. Tests de performances : mesurez l’impact de la surcharge HTTP.
4. Tests de sécurité : Valider la gestion des jetons et les stratégies réseau.

Considérations relatives aux performances

Surcharge du Kit de développement logiciel (SDK

Le SDK Microsoft Entra pour l’ID d’agent introduit la surcharge de communication HTTP :

Performance en cours

Utilisation de Microsoft. Identity.Web a une surcharge minimale, car elle s’exécute dans le même processus que votre application. Il fournit des appels de méthode natifs avec une latence microseconde et une mémoire de processus partagé sans limitations HTTP. Lorsque les performances sont critiques, l’intégration in-process est le choix optimal. Toutefois, la flexibilité et la conception indépendante du langage de Microsoft Entra SDK pour AgentID peuvent être préférées aux compromis sur la performance dans de nombreux scénarios.

Le tableau suivant présente des comparaisons de performances et de coûts pour l’utilisation in-process et Microsoft Entra SDK pour l’utilisation de l’ID d’agent (hors processus) :

Considérations relatives aux coûts

Exemple de coût

Pour 10 réplicas avec 128 Mio/100m de configuration SDK :

Support et maintenance

Approche hybride

Vous pouvez combiner les deux approches dans la même architecture. Utilisez Microsoft. Identity.Web pour les services .NET qui nécessitent des performances maximales et qui utilisent le KIT de développement logiciel (SDK) Microsoft Entra pour l’ID d’agent pour les services non .NET ou lorsque vous avez besoin de modèles d’authentification indépendant de la langue. Cette stratégie hybride vous permet d’optimiser les performances où il est essentiel tout en conservant la cohérence et la flexibilité dans l’ensemble de votre écosystème de services.

Voici un exemple d’architecture :

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

Contenu connexe

• Guide d’installation
• Informations de référence sur la configuration
• Appeler l’API en aval
• Aperçu