Konfigurera loggning i Microsoft. Identity.Web

Microsoft.Identity.Web integreras med ASP.NET Cores loggningsinfrastruktur. Använd den för att diagnostisera problem mellan:

• Autentiseringsflöden – inloggning, utloggning, tokenverifiering
• Tokenhämtning – Token-cache-träffar/missar, MSAL-åtgärder
• Underordnade API-anrop – HTTP-begäranden, tokenförvärv för API:er
• Felvillkor – Undantag, valideringsfel

Förstå loggade komponenter

Kom igång med loggning

Minimal konfiguration

Lägg till följande loggnivåposter i appsettings.json för att aktivera identitetsloggning.

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

Detta möjliggör Informationsnivå loggning för Microsoft. Identity.Web och dess beroenden (MSAL.NET, IdentityModel).

Utvecklingskonfiguration

För detaljerad diagnostik under utveckling:

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

Produktionskonfiguration

För produktion minimerar du loggvolymen och samlar in fel:

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

Konfigurera loggfiltrering

Namnområdesbaserad filtrering

Kontrollera loggens utförlighet efter namnområde. Följande konfiguration anger detaljerade nivåer för varje identitetsrelaterat namnområde:

{
  "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"
    }
  }
}

Inaktivera specifik loggning

Om du vill tysta bullriga komponenter utan att påverka andra anger du loggnivån till None eller Warning:

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

Miljöspecifik konfiguration

Använd appsettings.{Environment}.json för inställningar per miljö:

appsettings.Development.json:

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

appsettings.Production.json:

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

Förstå loggnivåer

ASP.NET Core definierar följande loggnivåer. Välj den nivå som balanserar diagnostikinformation mot loggvolymen för din miljö.

ASP.NET Core loggnivåer

Mappa MSAL.NET till ASP.NET Core nivåer

Tillämpa rekommenderade inställningar efter miljö

Använd följande konfigurationer per miljö.

Utveckling:

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

Iscensättning:

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

Produktion:

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

Konfigurera PII-loggning

Som standard censurerar Microsoft.Identity.Web personligt identifierbar information (PII) från loggar. Aktivera ENDAST PII-loggning i utvecklingsmiljöer för att se fullständig användarinformation.

Vad är PII?

Personligt identifierbar information (PII) omfattar:

• Användarnamn, e-postadresser
• Visningsnamn
• Objekt-ID:n, klient-ID:n
• IP-adresser
• Tokenvärden, anspråk

Säkerhetsvarning

VARNING! Du och ditt program ansvarar för att uppfylla alla tillämpliga regelkrav, inklusive de som anges av GDPR. Innan du aktiverar PII-loggning ska du se till att du på ett säkert sätt kan hantera dessa potentiellt mycket känsliga data.

Aktivera PII-loggning (endast utveckling)

Ange EnablePiiLogging till true i utvecklingskonfigurationsfilen:

appsettings.Development.json:

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

Kontrollera PII-loggning programmatiskt

Växla PII-loggning baserat på värdmiljön:

var builder = WebApplication.CreateBuilder(args);

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

Vilka ändringar med PII aktiverat?

Utan PII-loggning:

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

Med PII aktiverat:

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

PII-redigering i loggar

När PII-loggning är inaktiverad ersätts känsliga data med:

• {hidden} – Döljer användaridentifierare
• {hash:XXXX} – Visar hash i stället för verkligt värde
• *** – Döljer token

Använda korrelations-ID:t

Korrelations-ID:er spårar autentiseringsbegäranden mellan tjänster. Inkludera dem i loggar och supportärenden för att påskynda problemlösningen.

Vad är korrelations-ID:t?

Ett korrelations-ID är ett GUID som unikt identifierar en autentiserings- eller tokeninsamlingsbegäran över:

• Din ansökan
• Microsoft identitetsplattform
• MSAL.NET bibliotek
• Microsoft serverdelstjänster

Hämta korrelations-ID:t

Metod 1: Från AuthenticationResult

Extrahera korrelations-ID:t från AuthenticationResult efter ett lyckat tokenförvärv:

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

Metod 2: Från MsalServiceException

Samla in korrelations-ID:t från MsalServiceException när tokenförvärvet misslyckas:

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

Metod 3: Ange ett anpassat korrelations-ID

Tilldela ett anpassat korrelations-ID för att länka programspårningar med Microsoft Entra ID begäranden:

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

Ange korrelations-ID:t för support

När du kontaktar Microsoft support anger du följande information:

1. Korrelations-ID – från loggar eller undantag
2. Tidsstämpel – när felet inträffade (UTC)
3. Kundorganisation-ID – din Microsoft Entra ID kundorganisation
4. Felkod – om tillämpligt (t.ex. AADSTS50058)

Exempel på supportbegäran:

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

Aktivera loggning av tokencache

Tokencacheloggning hjälper dig att förstå beteendet för cacheträffar och diagnostisera prestandaproblem med distribuerade cacheminnen.

Aktivera tokencachediagnostik

Konfigurera detaljerad loggning för .NET Framework- eller .NET Core-appar med hjälp av distribuerade tokencacheminnen:

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

Exempel på tokencache-logg

Cacheträff:

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

Cache-miss:

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

Felsöka distribuerade cacheminnen

Aktivera providerspecifik loggning för att diagnostisera problem med cacheanslutning och prestanda.

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:

Konfigurera SQL Server distribuerad cache med loggning:

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

Felsökning av vanliga problem

Använd följande scenarier för att diagnostisera vanliga autentiserings- och auktoriseringsproblem.

Vanliga loggningsscenarier

Scenario 1: Tokenverifieringsfel

Symptom: 401 Otillåtna svar

Aktivera detaljerad loggning:

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

Sök efter:

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

Scenario 2: Problem vid förvärv av token

Symptom:MsalServiceException Eller MsalUiRequiredException

Aktivera detaljerad loggning:

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

Sök efter:

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

Scenario 3: Fel vid api-anrop nedströms

Symptom: HTTP 502- eller timeoutfel vid anrop av nedströms-API:er

Aktivera detaljerad loggning:

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

Lägg till anpassad loggning i kontrollern för att samla in nedströms API-fel.

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

Tolka loggmönster

I följande exempel visas vanliga loggutdata för vanliga autentiseringshändelser.

Lyckat autentiseringsflöde:

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

Medgivande krävs:

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

Tokenförnyelse:

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

Aggregera loggar med externa leverantörer

Vidarebefordra identitetsloggar till en centraliserad loggningsplattform för övervakning och aviseringar.

Application Insights-integrering:

Skicka identitetstelemetri till Application Insights med korrelations-ID-berikning:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

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

Serilog-integrering:

Konfigurera Serilog för att samla in identitetsloggar till konsolutmatningar och rullande filutmatningar.

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

Följ metodtips för loggning

Använd dessa metoder för att hålla dina identitetsloggar säkra, användbara och effektiva.

Saker att göra

1. Använd strukturerad loggning:

Skicka värden som namngivna parametrar så att loggaggregatorer kan indexera och fråga dem:

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

2. Loggningskorrelations-ID:

Inkludera alltid korrelations-ID i felloggar för att förenkla supportundersökningar:

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

3. Använd lämpliga loggnivåer:

Anpassa loggnivån med allvarlighetsgraden och målgruppen:

_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. Anonymisera loggar i produktion:

Maskera känsliga värden innan du skriver dem till produktionsloggar:

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

Förbud

1. Aktivera inte PII i produktion:

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

//  Correct
"EnablePiiLogging": false

2. Logga inte hemligheter:

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

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

3. Använd inte utförlig loggning i produktion:

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

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

Relaterat innehåll

• Anpassa autentisering
• Felsökning av tokencache
• Anropa nedströms API:er
• Behörighet