Aufrufen von Azure SDKs mit MicrosoftIdentityTokenCredential

Verwenden Sie MicrosoftIdentityTokenCredential aus Microsoft.Identity.Web.Azure, um Azure SDK-Clients (Speicher, Key Vault, Service Bus und mehr) mit Microsoft Entra ID zu authentifizieren.

Grundlegendes zu MicrosoftIdentityTokenCredential

Die klasse MicrosoftIdentityTokenCredential implementiert die schnittstelle Azure SDK TokenCredential. Mit dieser Integration können Sie die gleiche Authentifizierungskonfigurations- und Tokenzwischenspeicherungsinfrastruktur in der gesamten Anwendung verwenden.

Überprüfen der Vorteile

MicrosoftIdentityTokenCredential bietet die folgenden Vorteile:

Unified Authentication: Verwenden Sie dieselbe Authentifizierungskonfiguration für Web-Apps, APIs und Azure Dienste
Token Caching: Automatisches Zwischenspeichern und Auffrischen von Token
Delegierte & App-Berechtigungen: Unterstützung für Benutzer- und Anwendungstoken
Agentidentitäten: Kompatibel mit dem Feature "Agentidentitäten"
Managed Identity: Nahtlose Integration in Azure Managed Identity

Installieren der Pakete

Installieren Sie das Azure Integrationspaket:

dotnet add package Microsoft.Identity.Web.Azure

Installieren Sie dann die Azure SDK Clientpakete, die Sie benötigen:

# Examples
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Messaging.ServiceBus
dotnet add package Azure.Data.Tables

Einrichten von ASP.NET Core

1. Konfigurieren von Diensten

Der folgende Code registriert die Authentifizierung und fügt Ihrer Anwendung Unterstützung für Azure-Tokenanmeldeinformationen hinzu.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Add Azure token credential support
builder.Services.AddMicrosoftIdentityAzureTokenCredential();

builder.Services.AddControllersWithViews();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

2. Konfigurieren von appsettings.json

Fügen Sie der datei appsettings.json die Microsoft Entra konfiguration hinzu:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Verwenden von MicrosoftIdentityTokenCredential

Einfügen und Verwenden mit Azure SDK Clients

Das folgende Beispiel zeigt, wie sie MicrosoftIdentityTokenCredential einfügen und mit Azure Blob Storage verwenden. Der gleiche Ansatz gilt für alle Azure SDK Clients.

using Azure.Storage.Blobs;
using Microsoft.Identity.Web;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize]
public class StorageController : Controller
{
    private readonly MicrosoftIdentityTokenCredential _credential;
    private readonly IConfiguration _configuration;
    
    public StorageController(
        MicrosoftIdentityTokenCredential credential,
        IConfiguration configuration)
    {
        _credential = credential;
        _configuration = configuration;
    }
    
    public async Task<IActionResult> ListBlobs()
    {
        // Create Azure SDK client with credential
        var blobClient = new BlobServiceClient(
            new Uri($"https://{_configuration["StorageAccountName"]}.blob.core.windows.net"),
            _credential);
        
        var container = blobClient.GetBlobContainerClient("mycontainer");
        var blobs = new List<string>();
        
        await foreach (var blob in container.GetBlobsAsync())
        {
            blobs.Add(blob.Name);
        }
        
        return View(blobs);
    }
}

Delegierte Berechtigungen verwenden

Rufen Sie Azure Dienste im Namen des angemeldeten Benutzers mithilfe delegierter Berechtigungen auf.

Hochladen von Dateien mit Azure Storage

Der folgende Controller veranschaulicht, wie eine Datei mithilfe eines delegierten Tokens in Azure Blob Storage hochgeladen wird:

using Azure.Storage.Blobs;
using Microsoft.Identity.Web;

[Authorize]
public class FileController : Controller
{
    private readonly MicrosoftIdentityTokenCredential _credential;
    
    public FileController(MicrosoftIdentityTokenCredential credential)
    {
        _credential = credential;
    }
    
    public async Task<IActionResult> UploadFile(IFormFile file)
    {
        // Credential will automatically acquire delegated token
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            _credential);
        
        var container = blobClient.GetBlobContainerClient("uploads");
        await container.CreateIfNotExistsAsync();
        
        var blob = container.GetBlobClient(file.FileName);
        await blob.UploadAsync(file.OpenReadStream(), overwrite: true);
        
        return Ok($"File {file.FileName} uploaded");
    }
}

Verwenden von Anwendungsberechtigungen

Rufen Sie Azure Dienste mit Anwendungsberechtigungen auf, wenn kein Benutzerkontext verfügbar ist.

Konfigurieren von App-Only-Token

Setzen Sie RequestAppToken bei den Anmeldeinformationsoptionen auf true, um ein Nur-App-Token zu erhalten.

public class AzureService
{
    private readonly MicrosoftIdentityTokenCredential _credential;
    
    public AzureService(MicrosoftIdentityTokenCredential credential)
    {
        _credential = credential;
    }
    
    public async Task<List<string>> ListBlobsAsync()
    {
        // Configure credential for app-only token
        _credential.Options.RequestAppToken = true;
        
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            _credential);
        
        var container = blobClient.GetBlobContainerClient("data");
        var blobs = new List<string>();
        
        await foreach (var blob in container.GetBlobsAsync())
        {
            blobs.Add(blob.Name);
        }
        
        return blobs;
    }
}

Erstellen einer Daemon-Anwendung

Das folgende Beispiel zeigt, wie Sie eine eigenständige Daemonanwendung erstellen, die mit Nur-App-Berechtigungen auf Azure Blob Storage zugreift:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Azure.Storage.Blobs;

class Program
{
    static async Task Main(string[] args)
    {
        // Build service provider
        var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
        tokenAcquirerFactory.Services.AddMicrosoftIdentityAzureTokenCredential();
        var sp = tokenAcquirerFactory.Build();
        
        // Get credential
        var credential = sp.GetRequiredService<MicrosoftIdentityTokenCredential>();
        credential.Options.RequestAppToken = true;
        
        // Use with Azure SDK
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            credential);
        
        var container = blobClient.GetBlobContainerClient("data");
        
        await foreach (var blob in container.GetBlobsAsync())
        {
            Console.WriteLine($"Blob: {blob.Name}");
        }
    }
}

Integrieren von Agentidentitäten

MicrosoftIdentityTokenCredential unterstützt Agentidentitäten über die Options Eigenschaft. Die folgende Dienstklasse zeigt, wie Agent- und Agent-Benutzeridentitäten konfiguriert werden:

using Microsoft.Identity.Web;

public class AgentService
{
    private readonly MicrosoftIdentityTokenCredential _credential;
    
    public AgentService(MicrosoftIdentityTokenCredential credential)
    {
        _credential = credential;
    }
    
    public async Task<List<string>> ListBlobsForAgentAsync(string agentIdentity)
    {
        // Configure for agent identity
        _credential.Options.WithAgentIdentity(agentIdentity);
        _credential.Options.RequestAppToken = true;
        
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            _credential);
        
        var container = blobClient.GetBlobContainerClient("agent-data");
        var blobs = new List<string>();
        
        await foreach (var blob in container.GetBlobsAsync())
        {
            blobs.Add(blob.Name);
        }
        
        return blobs;
    }
    
    public async Task<string> GetSecretForAgentUserAsync(string agentIdentity, Guid userOid, string secretName)
    {
        // Configure for agent user identity
        _credential.Options.WithAgentUserIdentity(agentIdentity, userOid);
        
        var secretClient = new SecretClient(
            new Uri("https://myvault.vault.azure.net"),
            _credential);
        
        var secret = await secretClient.GetSecretAsync(secretName);
        return secret.Value.Value;
    }
}

Weitere Details finden Sie in der Dokumentation zu Agentidentitäten .

Konfigurieren von FIC und verwalteter Identität

MicrosoftIdentityTokenCredential funktioniert mit FIC und Azure verwalteter Identität.

Anmeldeinformationen für Managed Identity konfigurieren

Fügen Sie die folgende Konfiguration hinzu, um verwaltete Identität als Anmeldeinformationsquelle zu verwenden:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Verwenden der vom System zugewiesenen verwalteten Identität

Wenn Sie in Azure bereitstellen, verwenden die Berechtigungsnachweise automatisch die vom System zugewiesene verwaltete Identität. Die folgende Dienstklasse veranschaulicht dieses Muster:

// No additional code needed!
// When deployed to Azure, the credential automatically uses managed identity

public class StorageService
{
    private readonly MicrosoftIdentityTokenCredential _credential;
    
    public StorageService(MicrosoftIdentityTokenCredential credential)
    {
        _credential = credential;
        _credential.Options.RequestAppToken = true;
    }
    
    public async Task<List<string>> ListContainersAsync()
    {
        // Uses managed identity when running in Azure
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            _credential);
        
        var containers = new List<string>();
        await foreach (var container in blobClient.GetBlobContainersAsync())
        {
            containers.Add(container.Name);
        }
        
        return containers;
    }
}

Verwenden der vom Benutzer zugewiesenen verwalteten Identität

Geben Sie in Ihrer Konfiguration ManagedIdentityClientId an, um eine vom Benutzer zugewiesene verwaltete Identität zu verwenden.

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-identity-client-id"
      }
    ]
  }
}

Implementieren der OWIN-Authentifizierung

Registrieren Sie für ASP.NET Anwendungen, die OWIN verwenden, die Azure Tokenanmeldeinformationen in der Startklasse:

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.OWIN;
using Owin;

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
     app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
     app.UseCookieAuthentication(new CookieAuthenticationOptions());

     OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

     app.AddMicrosoftIdentityWebApp(factory);
     factory.Services
        .AddMicrosoftIdentityAzureTokenCredential();
      factory.Build();
    }
}

Bewährte Methoden befolgen

1. Wiederverwenden Azure SDK Clients

Azure SDK-Clients sind threadsicher, daher sollten Sie sie bei Anfragen wiederverwenden. Es ist jedoch ein bereichsbezogener Dienst, sodass Sie ihn nicht mit AddAzureServices() verwenden können, der Singletons erstellt.

2. Verwenden der verwalteten Identität in der Produktion

Bevorzugen Sie die zertifikatlose Authentifizierung mit verwalteter Identität in Produktionsumgebungen:

//  Good: Certificateless auth with managed identity
{
  "ClientCredentials": [
    {
      "SourceType": "SignedAssertionFromManagedIdentity"
    }
  ]
}

3. Umgang mit Ausnahmefehlern des Azure SDK

Schließen Sie Azure SDK-Aufrufe in try-catch-Blöcken ein, um häufige Fehlerszenarien zu behandeln.

using Azure;

try
{
    var blob = await blobClient.DownloadAsync();
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    // Blob not found
}
catch (RequestFailedException ex) when (ex.Status == 403)
{
    // Insufficient permissions
}
catch (RequestFailedException ex)
{
    _logger.LogError(ex, "Azure SDK call failed with status {Status}", ex.Status);
}

5. Konfiguration für URIs verwenden

Speichern Sie Azure Ressourcen-URIs in der Konfiguration, anstatt sie zu codieren:

//  Bad: Hardcoded URIs
var blobClient = new BlobServiceClient(new Uri("https://myaccount.blob.core.windows.net"), credential);

//  Good: Configuration-driven
var storageUri = _configuration["Azure:Storage:Uri"];
var blobClient = new BlobServiceClient(new Uri(storageUri), credential);

Häufige Fehler beheben

Beheben von Fehler bei der Authentifizierung von "ManagedIdentityCredential"

Ursache: Verwaltete Identität ist nicht aktiviert oder falsch konfiguriert.

Lösung:

Aktivieren der verwalteten Identität auf Azure Ressource (App Service, VM usw.)
Geben Sie für die vom Benutzer zugewiesene Identität ManagedIdentityClientId
Identität auf erforderliche Rollenzuweisungen überprüfen

Auflösen von "Diese Anforderung ist nicht zum Ausführen dieses Vorgangs autorisiert"

Cause: Fehlende Azure RBAC-Rollenzuweisung.