Configureer logboekregistratie in Microsoft. Identity.Web

Microsoft. Identity.Web kan worden geïntegreerd met de logboekregistratie-infrastructuur van ASP.NET Core. Gebruik deze om problemen op te sporen in:

• Verificatiestromen : validatie van aanmelding, afmelden, tokenvalidatie
• Tokenacquisitie - Tokencachetreffers en missen, MSAL-bewerkingen
• Downstream-API-aanroepen - HTTP-aanvragen, tokenverwerving voor API's
• Foutvoorwaarden - Uitzonderingen, validatiefouten

Geregistreerde onderdelen begrijpen

Aan de slag met logboekregistratie

Minimale configuratie

Voeg de volgende vermeldingen op logboekniveau toe om identiteitslogboekregistratie in te appsettings.json schakelen:

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

Hierdoor kan Informatieniveau logboekregistratie worden ingeschakeld voor Microsoft.Identity.Web en de bijbehorende afhankelijkheden (MSAL.NET, IdentityModel).

Ontwikkelconfiguratie

Voor gedetailleerde diagnostische gegevens tijdens de ontwikkeling:

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

Productieconfiguratie

Voor productie minimaliseert u het logboekvolume tijdens het vastleggen van fouten:

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

Logboekfiltering configureren

Filteren op basis van naamruimte

Beheer de gedetailleerdheid van logs per naamruimte. Met de volgende configuratie worden gedetailleerde niveaus ingesteld voor elke identiteitsgerelateerde naamruimte:

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

Specifieke logboekregistratie uitschakelen

Als u lawaaierige onderdelen wilt stilzetten zonder dat dit van invloed is op anderen, stelt u het logboekniveau in None op of Warning:

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

Omgevingsspecifieke configuratie

Gebruiken appsettings.{Environment}.json voor instellingen per omgeving:

appsettings.Development.json:

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

appsettings.Production.json:

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

Begrijp logniveaus

ASP.NET Core definieert de volgende logboekniveaus. Kies het niveau dat diagnostische details in balans brengt met het logvolume voor uw omgeving.

ASP.NET Core logboekniveaus

MSAL.NET toewijzen aan ASP.NET Core lagen

Aanbevolen instellingen toepassen op omgeving

Gebruik de volgende configuraties per omgeving.

Ontwikkeling:

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

Stagingomgeving:

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

Productie:

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

PII-logboekregistratie configureren

Standaard verwijdert Microsoft.Identity.Web persoonlijk identificeerbare informatie (PII) uit logboeken. Schakel PII-logboekregistratie alleen in ontwikkelomgevingen in om volledige gebruikersdetails te zien.

Wat is PII?

Persoonlijke identificeerbare informatie (PII) omvat:

• Gebruikersnamen, e-mailadressen
• Weergavenamen
• object-ID's, tenant-ID's
• IP-adressen
• Tokenwaarden, toegangsclaims

Beveiligingswaarschuwing

WAARSCHUWING: U en uw toepassing zijn verantwoordelijk voor het voldoen aan alle toepasselijke wettelijke vereisten, inclusief de vereisten die zijn uiteengezet door de AVG. Voordat u PII-logboekregistratie inschakelt, moet u ervoor zorgen dat u deze mogelijk zeer gevoelige gegevens veilig kunt afhandelen.

PII-logboekregistratie inschakelen (alleen ontwikkeling)

Stel EnablePiiLogging in op true in je ontwikkelingsconfiguratiebestand.

appsettings.Development.json:

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

PiI-logboekregistratie programmatisch beheren

PiI-logboekregistratie in-/uitschakelen op basis van de hostingomgeving:

var builder = WebApplication.CreateBuilder(args);

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

Wat verandert er wanneer PII is ingeschakeld?

Zonder PII-logboekregistratie:

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

Met PII ingeschakeld:

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

PII-verwijdering in logboeken

Wanneer PII-logboekregistratie is uitgeschakeld, worden gevoelige gegevens vervangen door:

• {hidden} - Gebruikers-id's verbergen
• {hash:XXXX} - Geeft hash weer in plaats van werkelijke waarde
• *** - Verbergt tokens

Correlatie-id's gebruiken

Correlatie-id's traceren verificatieaanvragen voor services. Neem ze op in logboeken en ondersteuningstickets om het oplossen van problemen te versnellen.

Wat zijn correlatie-id's?

Een correlatie-id is een GUID waarmee een aanvraag voor verificatie of tokenverwerving uniek wordt geïdentificeerd in:

• Uw toepassing
• Microsoft Identity Platform
• MSAL.NET-bibliotheek
• Microsoft backendservices

Correlatie-id's verkrijgen

Methode 1: Van AuthenticationResult

Pak de correlatie-id uit AuthenticationResult na een geslaagde tokenverwerving:

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: Uit MsalServiceException

Leg de correlatie-id vast van MsalServiceException wanneer het ophalen van tokens mislukt.

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: Een aangepaste correlatie-id instellen

Wijs een aangepaste correlatie-id toe om toepassingstraceringen te koppelen aan Microsoft Entra ID aanvragen:

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

Correlatie-id's opgeven voor ondersteuning

Wanneer u contact op neemt met Microsoft ondersteuning, geeft u de volgende gegevens op:

1. Correlatie-id - Uit logboeken of uitzonderingen
2. Tijdstempel : wanneer de fout is opgetreden (UTC)
3. Tenant-id - uw Microsoft Entra ID-tenant
4. Foutcode : indien van toepassing (bijvoorbeeld AADSTS50058)

Voorbeeld van ondersteuningsaanvraag:

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

Tokencachelogging inschakelen

Logregistratie van de tokencache helpt u inzicht te krijgen in het gedrag van cache-hits/misses en prestatieproblemen met gedistribueerde caches op te lossen.

Diagnostiek voor tokencache inschakelen

Configureer gedetailleerde logboekregistratie voor .NET Framework- of .NET Core-apps met behulp van gedistribueerde tokencaches:

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

Voorbeelden van tokencachelogboeken

Cachetreffer:

[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

Problemen met gedistribueerde caches oplossen

Schakel providerspecifieke logboekregistratie in om connectiviteit en prestatieproblemen in de cache vast te stellen.

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:

Configureer SQL Server gedistribueerde cache met logboekregistratie:

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

Veelvoorkomende problemen oplossen

Gebruik de volgende scenario's om veelvoorkomende verificatie- en autorisatieproblemen vast te stellen.

Veelvoorkomende scenario's voor logboekregistratie

Scenario 1: Validatiefouten van tokens

Symptoom: 401 Niet-geautoriseerde reacties

Gedetailleerde logboekregistratie inschakelen:

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

Zoek naar:

[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: Problemen met tokenverwerving

Symptoom:MsalServiceException Of MsalUiRequiredException

Gedetailleerde logboekregistratie inschakelen:

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

Zoek naar:

[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: Fouten bij downstream-API-aanroepen

Symptoom: HTTP 502- of time-outfouten bij het aanroepen van downstream-API's

Gedetailleerde logboekregistratie inschakelen:

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

Voeg aangepaste logboekregistratie toe aan uw controller om downstream-API-fouten vast te leggen:

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

Logboekpatronen interpreteren

In de volgende voorbeelden ziet u typische logboekuitvoer voor veelvoorkomende verificatie-gebeurtenissen.

Geslaagde verificatiestroom:

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

Toestemming vereist:

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

Token vernieuwen:

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

Logboeken aggregeren met externe providers

Identiteitslogboeken doorsturen naar een gecentraliseerd logboekregistratieplatform voor bewaking en waarschuwingen.

Application Insights-integratie:

Identiteitstelemetrie verzenden naar Application Insights met correlatie-id-verrijking:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

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

Serilog-integratie:

Configureer Serilog om identiteitslogboeken vast te leggen voor console- en roterende bestandsuitvoer.

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

Volg beste praktijken voor logboekregistratie

Pas deze procedures toe om uw identiteitslogboeken veilig, nuttig en performant te houden.

Aanbevelingen

1. Gestructureerde logboekregistratie gebruiken:

Geef waarden door als benoemde parameters, zodat logboekaggregators deze kunnen indexeren en er query's op kunnen uitvoeren:

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

2. Correlatie-id's vastleggen:

Neem altijd de correlatie-id op in foutenlogboeken om ondersteuningsonderzoeken te vereenvoudigen:

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

3. Gebruik de juiste logboekniveaus:

Koppel het logboekniveau aan de ernst en doelgroep:

_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. Logboeken in productie saneren:

Masker gevoelige waarden voordat u ze naar productielogboeken schrijft:

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

Dingen die je niet moet doen

1. PiI niet inschakelen in productie:

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

//  Correct
"EnablePiiLogging": false

2. Geen geheimen vastleggen:

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

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

3. Gebruik geen uitgebreide logboekregistratie in productie:

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

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

Verwante inhoud

• Verificatie aanpassen
• Problemen met tokencache oplossen
• Downstream-API's aanroepen
• Authorization