Konfigurieren Sie die Protokollierung in Microsoft. Identity.Web

Microsoft. Identity.Web ist in die Protokollierungsinfrastruktur ASP.NET Core integriert. Verwenden Sie sie, um Probleme in folgenden Punkten zu diagnostizieren:

• Authentifizierungsflüsse – Anmeldung, Abmelden, Tokenüberprüfung
• Tokenerwerb – Tokencachetreffer und -fehltreffer, MSAL-Vorgänge
• Nachgeschaltete API-Aufrufe – HTTP-Anforderungen , Tokenerwerb für APIs
• Fehlerbedingungen – Ausnahmen, Überprüfungsfehler

Verstehen der protokollierten Komponenten

Erste Schritte mit der Protokollierung

Minimale Konfiguration

Fügen Sie die folgenden Einträge auf Protokollebene hinzu, um die Identitätsprotokollierung zu appsettings.json aktivieren:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity": "Information"
    }
  }
}

Dies ermöglicht Informationsebeneprotokollierung für Microsoft. Identity.Web und seine Abhängigkeiten (MSAL.NET, IdentityModel).

Entwicklungskonfiguration

Detaillierte Diagnose während der Entwicklung:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Identity": "Debug",
      "Microsoft.AspNetCore.Authentication": "Information"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": true  // Development only!
  }
}

Produktionskonfiguration

Minimieren Sie für die Produktion das Protokollvolumen beim Erfassen von Fehlern:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft": "Warning",
      "Microsoft.Identity": "Warning"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": false  // Never true in production
  }
}

Konfigurieren der Protokollfilterung

Namespacebasierte Filterung

Steuerung der Ausführlichkeit des Protokolls nach Namespace. Die folgende Konfiguration legt granulare Ebenen für jeden identitätsbezogenen Namespace fest:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",

      // General Microsoft namespaces
      "Microsoft": "Warning",
      "Microsoft.AspNetCore": "Warning",

      // Identity-specific namespaces
      "Microsoft.Identity": "Information",
      "Microsoft.Identity.Web": "Information",
      "Microsoft.Identity.Client": "Information",

      // ASP.NET Core authentication
      "Microsoft.AspNetCore.Authentication": "Information",
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Information",
      "Microsoft.AspNetCore.Authentication.OpenIdConnect": "Debug",

      // Token validation
      "Microsoft.IdentityModel": "Warning"
    }
  }
}

Deaktivieren der bestimmten Protokollierung

Um laute Komponenten stumm zu halten, ohne andere zu beeinträchtigen, legen Sie deren Protokollebene auf None oder Warning:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "None",  // Completely disable
      "Microsoft.Identity.Client": "Warning"  // Only errors/warnings
    }
  }
}

Umgebungsspezifische Konfiguration

Verwenden Sie appsettings.{Environment}.json für Umgebungseinstellungen.

appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": true
  }
}

appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Warning"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": false
  }
}

Verständnis von Protokollebenen

ASP.NET Core definiert die folgenden Protokollierungsstufen. Wählen Sie die Ebene aus, auf der diagnosedetails mit dem Protokollvolume für Ihre Umgebung ausgeglichen werden.

ASP.NET Core Protokollebenen

Zuordnen MSAL.NET zu ASP.NET Core Ebenen

Anwenden empfohlener Einstellungen nach Umgebung

Verwenden Sie die folgenden Konfigurationen pro Umgebung.

Entwicklung:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug",
      "Microsoft.Identity.Client": "Information"
    }
  }
}

Staging:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Information",
      "Microsoft.Identity.Client": "Warning"
    }
  }
}

Produktion:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Warning",
      "Microsoft.Identity.Client": "Error"
    }
  }
}

Konfigurieren der PII-Protokollierung

Standardmäßig Microsoft. Identity.Web redagiert personenbezogene Informationen (PII) aus Protokollen. Aktivieren Sie die PII-Protokollierung nur in Entwicklungsumgebungen, um vollständige Benutzerdetails anzuzeigen.

Was ist PII?

Personenbezogene Informationen (PERSONALly Identifiable Information, PII) umfassen:

• Benutzernamen, E-Mail-Adressen
• Anzeigenamen
• Objekt-IDs, Mandanten-IDs
• IP-Adressen
• Tokenwerte, Ansprüche

Sicherheitswarnung

WARNUNG: Sie und Ihre Anwendung sind dafür verantwortlich, alle geltenden gesetzlichen Anforderungen, einschließlich der bestimmungen der DSGVO, einzuhalten. Bevor Sie die PII-Protokollierung aktivieren, stellen Sie sicher, dass Sie diese potenziell streng vertraulichen Daten sicher verarbeiten können.

PII-Protokollierung aktivieren (nur für die Entwicklung)

Legen Sie EnablePiiLogging als true in Ihrer Entwicklungskonfigurationsdatei fest.

appsettings.Development.json:

{
  "AzureAd": {
    "EnablePiiLogging": true  //  Development/Testing ONLY
  },
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug"
    }
  }
}

Programmgesteuertes Steuern der PII-Protokollierung

Umschalten der PII-Protokollierung je nach der Hosting-Umgebung.

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    // Only enable PII in Development
    options.EnablePiiLogging = builder.Environment.IsDevelopment();
});

Welche Änderungen mit aktivierter PII?

Ohne PII-Protokollierung:

[Information] Token validation succeeded for user '{hidden}'
[Information] Acquired token from cache for scopes '{hidden}'

Mit aktivierter PII:

[Information] Token validation succeeded for user 'john.doe@contoso.com'
[Information] Acquired token from cache for scopes 'user.read api://my-api/.default'

PII-Redaction in Protokollen

Wenn die PII-Protokollierung deaktiviert ist, werden vertrauliche Daten durch Folgendes ersetzt:

• {hidden} - Blendet Nutzerbezeichner aus
• {hash:XXXX} - Zeigt Hash anstelle des tatsächlichen Werts an.
• *** - Verschleiert Tokens

Verwenden von Korrelations-IDs

Korrelations-IDs verfolgen Authentifizierungsanforderungen über Dienste hinweg. Fügen Sie sie in Protokolle und Supporttickets ein, um die Problembehebung zu beschleunigen.

Was sind Korrelations-IDs?

Eine Korrelations-ID ist eine GUID , die eine Authentifizierungs- oder Tokenakquisitionsanforderung eindeutig identifiziert:

• Ihre Anwendung
• Microsoft-Identitätsplattform
• MSAL.NET-Bibliothek
• Microsoft Back-End-Dienste

Abrufen von Korrelations-IDs

Methode 1: Von AuthenticationResult

Extrahieren Sie die Korrelations-ID aus AuthenticationResult nach einem erfolgreichen Tokenerwerb.

using Microsoft.Identity.Web;

public class TodoController : ControllerBase
{
    private readonly ITokenAcquisition _tokenAcquisition;
    private readonly ILogger<TodoController> _logger;

    public TodoController(
        ITokenAcquisition tokenAcquisition,
        ILogger<TodoController> logger)
    {
        _tokenAcquisition = tokenAcquisition;
        _logger = logger;
    }

    [HttpGet]
    public async Task<IActionResult> GetTodos()
    {
        var result = await _tokenAcquisition.GetAuthenticationResultForUserAsync(
            new[] { "user.read" });

        _logger.LogInformation(
            "Token acquired. CorrelationId: {CorrelationId}, Source: {TokenSource}",
            result.CorrelationId,
            result.AuthenticationResultMetadata.TokenSource);

        return Ok(result.CorrelationId);
    }
}

Methode 2: Mithilfe von MsalServiceException

Erfassen Sie die Korrelations-ID von MsalServiceException, wenn der Tokenerwerb fehlschlägt.

using Microsoft.Identity.Client;

try
{
    var token = await _tokenAcquisition.GetAccessTokenForUserAsync(
        new[] { "user.read" });
}
catch (MsalServiceException ex)
{
    _logger.LogError(ex,
        "Token acquisition failed. CorrelationId: {CorrelationId}, ErrorCode: {ErrorCode}",
        ex.CorrelationId,
        ex.ErrorCode);

    // Return correlation ID to user for support
    return StatusCode(500, new {
        error = "authentication_failed",
        correlationId = ex.CorrelationId
    });
}

Methode 3: Festlegen einer benutzerdefinierten Korrelations-ID

Weisen Sie eine benutzerdefinierte Korrelations-ID zu, um Anwendungsablaufverfolgungen mit Microsoft Entra ID Anforderungen zu verknüpfen:

[HttpGet("{id}")]
public async Task<IActionResult> GetTodo(int id)
{
    // Use request trace ID as correlation ID
    var correlationId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

    var todo = await _downstreamApi.GetForUserAsync<Todo>(
        "TodoListService",
        options =>
        {
            options.RelativePath = $"api/todolist/{id}";
            options.TokenAcquisitionOptions = new TokenAcquisitionOptions
            {
                CorrelationId = Guid.Parse(correlationId)
            };
        });

    _logger.LogInformation(
        "Called downstream API. TraceId: {TraceId}, CorrelationId: {CorrelationId}",
        HttpContext.TraceIdentifier,
        correlationId);

    return Ok(todo);
}

Bereitstellen von Korrelations-IDs zur Unterstützung

Wenn Sie sich an Microsoft Support wenden, geben Sie die folgenden Details an:

1. Korrelations-ID – Aus Protokollen oder Ausnahmen
2. Zeitstempel – Zeitpunkt des Auftretens des Fehlers (UTC)
3. Tenant-ID – Ihr Microsoft Entra ID Mandant
4. Fehlercode – Falls zutreffend (z. B. AADSTS50058)

Beispiel-Supportanfrage:

Subject: Token acquisition failing for user.read scope

Correlation ID: 12345678-1234-1234-1234-123456789012
Timestamp: 2025-01-15 14:32:45 UTC
Tenant ID: contoso.onmicrosoft.com
Error Code: AADSTS50058

Tokencacheprotokollierung aktivieren

Die Tokencacheprotokollierung hilft Ihnen, das Cache-Treffer und -Fehlverhalten zu verstehen und Leistungsprobleme bei verteilten Caches zu diagnostizieren.

Aktivieren der Tokencachediagnose

Konfigurieren Sie für .NET Framework oder .NET Core-Apps mit verteilten Tokencaches die detaillierte Protokollierung:

using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.TokenCacheProviders;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDistributedTokenCaches();

// Enable detailed token cache logging
builder.Services.AddLogging(configure =>
{
    configure.AddConsole();
    configure.AddDebug();
})
.Configure<LoggerFilterOptions>(options =>
{
    options.MinLevel = LogLevel.Debug;  // Detailed cache operations
});

Beispiele für Token-Cache-Protokoll

Cachetreffer:

[Debug] Token cache: Token found in cache for scopes 'user.read'
[Information] Token source: Cache

Cachefehler:

[Debug] Token cache: No token found in cache for scopes 'user.read'
[Information] Token source: IdentityProvider
[Debug] Token cache: Token stored in cache

Problembehandlung für verteilte Caches

Aktivieren Sie die anbieterspezifische Protokollierung, um Cachekonnektivitäts- und Leistungsprobleme zu diagnostizieren.

Redis-Cache:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration["Redis:ConnectionString"];
});

// Enable Redis logging
builder.Services.AddLogging(configure =>
{
    configure.AddFilter("Microsoft.Extensions.Caching", LogLevel.Debug);
});

SQL Server cache:

Konfigurieren sie SQL Server verteilten Cache mit Protokollierung:

builder.Services.AddDistributedSqlServerCache(options =>
{
    options.ConnectionString = builder.Configuration["SqlCache:ConnectionString"];
    options.SchemaName = "dbo";
    options.TableName = "TokenCache";
});

// Enable SQL cache logging
builder.Services.AddLogging(configure =>
{
    configure.AddFilter("Microsoft.Extensions.Caching.SqlServer", LogLevel.Information);
});

Häufige Probleme beheben

Verwenden Sie die folgenden Szenarien, um häufige Authentifizierungs- und Autorisierungsprobleme zu diagnostizieren.

Häufige Protokollierungsszenarien

Szenario 1: Tokenüberprüfungsfehler

Symptom: 401 Nicht autorisierte Reaktionen

Aktivieren der detaillierten Protokollierung:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Debug",
      "Microsoft.IdentityModel": "Information"
    }
  }
}

Suchen nach:

[Information] Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerHandler:
  Failed to validate the token.
[Debug] Microsoft.IdentityModel.Tokens: IDX10230: Lifetime validation failed.
  The token is expired.

Szenario 2: Tokenerwerbsfehler

Symptom:MsalServiceException Oder MsalUiRequiredException

Aktivieren der detaillierten Protokollierung:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity.Web": "Debug",
      "Microsoft.Identity.Client": "Information"
    }
  }
}

Suchen nach:

[Error] Microsoft.Identity.Web: Token acquisition failed.
  ErrorCode: invalid_grant, CorrelationId: {guid}
[Information] Microsoft.Identity.Client: MSAL returned exception:
  AADSTS50058: Silent sign-in failed.

Szenario 3: Nachgeschaltete API-Aufruffehler

Symptom: HTTP 502- oder Timeoutfehler beim Aufrufen von downstream-APIs

Aktivieren der detaillierten Protokollierung:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity.Abstractions": "Debug",
      "System.Net.Http": "Information"
    }
  }
}

Fügen Sie ihrem Controller eine benutzerdefinierte Protokollierung hinzu, um nachgeschaltete API-Fehler zu erfassen:

[HttpGet]
public async Task<IActionResult> GetUserProfile()
{
    try
    {
        _logger.LogInformation("Acquiring token for Microsoft Graph");

        var user = await _downstreamApi.GetForUserAsync<User>(
            "MicrosoftGraph",
            options => options.RelativePath = "me");

        _logger.LogInformation(
            "Successfully retrieved user profile for {UserPrincipalName}",
            user.UserPrincipalName);

        return Ok(user);
    }
    catch (MsalUiRequiredException ex)
    {
        _logger.LogWarning(ex,
            "User interaction required. CorrelationId: {CorrelationId}",
            ex.CorrelationId);
        return Challenge();
    }
    catch (HttpRequestException ex)
    {
        _logger.LogError(ex, "Failed to call Microsoft Graph API");
        return StatusCode(502, "Downstream API error");
    }
}

Interpretieren von Protokollmustern

Die folgenden Beispiele zeigen typische Protokollausgabe für allgemeine Authentifizierungsereignisse.

Erfolgreicher Authentifizierungsfluss:

[Info] Authentication scheme OpenIdConnect: Authorization response received
[Debug] Correlation id: {guid}
[Info] Authorization code received
[Info] Token validated successfully
[Info] Authentication succeeded for user: {user}

Zustimmung erforderlich:

[Warning] Microsoft.Identity.Web: Incremental consent required
[Info] AADSTS65001: User consent is required for scopes: {scopes}
[Info] Redirecting to consent page

Tokenaktualisierung:

[Debug] Token expired, attempting silent token refresh
[Info] Token source: IdentityProvider
[Info] Token refreshed successfully

Protokolle mit externen Anbietern aggregieren

Leiten Sie Identitätsprotokolle zur Überwachung und Warnung an eine zentrale Protokollierungsplattform weiter.

Integration von Application Insights:

Senden von Identitätstelemetrie an Application Insights mit Korrelations-ID-Anreicherung:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

// Enrich telemetry with correlation IDs
builder.Services.AddSingleton<ITelemetryInitializer, CorrelationIdTelemetryInitializer>();

Serilog-Integration:

Konfigurieren Sie Serilog so, dass Authentifizierungsprotokolle in Konsolenausgaben und rollierenden Dateiausgaben erfasst werden.

using Serilog;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft.Identity", Serilog.Events.LogEventLevel.Debug)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("logs/identity-.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

builder.Host.UseSerilog();

Befolgen bewährter Methoden für die Protokollierung

Wenden Sie diese Methoden an, um Ihre Identitätsprotokolle sicher, nützlich und leistungsfähig zu halten.

Empfohlen

1. Verwenden Sie die strukturierte Protokollierung:

Übergeben Sie Werte als benannte Parameter, damit Protokollaggregatoren sie indizieren und abfragen können:

_logger.LogInformation(
    "Token acquired for user {UserId} with scopes {Scopes}",
    userId, string.Join(" ", scopes));

2. Protokollkorrelations-IDs:

Schließen Sie immer die Korrelations-ID in Fehlerprotokolle ein, um Supportuntersuchungen zu vereinfachen:

_logger.LogError(ex,
    "Operation failed. CorrelationId: {CorrelationId}",
    ex.CorrelationId);

3. Verwenden Sie geeignete Loglevel:

Zuordnen der Protokollebene zum Schweregrad und zur Zielgruppe:

_logger.LogDebug("Detailed diagnostic info");      // Development
_logger.LogInformation("Key application events");  // Selective production
_logger.LogWarning("Unexpected but handled");      // Production
_logger.LogError(ex, "Operation failed");          // Production

4. Protokolle in der Produktion sanieren:

Maskieren Sie vertrauliche Werte, bevor Sie sie in Produktionsprotokolle schreiben:

var sanitizedEmail = environment.IsProduction()
    ? MaskEmail(email)
    : email;
_logger.LogInformation("Processing request for {Email}", sanitizedEmail);

DONT‘s

1. Aktivieren Sie piI in der Produktion nicht:

//  Wrong
"EnablePiiLogging": true  // In production config!

//  Correct
"EnablePiiLogging": false

2. Protokollieren Sie keine Geheimnisse:

//  Wrong
_logger.LogInformation("Token: {Token}", accessToken);

//  Correct
_logger.LogInformation("Token acquired, expires: {ExpiresOn}", expiresOn);

3. Verwenden Sie keine ausführliche Protokollierung in der Produktion:

//  Wrong - production appsettings.json
"Microsoft.Identity": "Debug"

//  Correct
"Microsoft.Identity": "Warning"

Verwandte Inhalte

• Anpassen der Authentifizierung
• Fehlerbehebung beim Tokencache
• Aufrufen nachgeschalteter APIs
• Autorisierung