Nakonfigurujte protokolování v Microsoft. Identity.Web

Microsoft. Identity.Web se integruje s infrastrukturou protokolování ASP.NET Core. Použijte ho k diagnostice problémů napříč:

• Toky ověřování – přihlášení, odhlášení, ověření tokenu
• Získání tokenu – zásahy/prohřešky mezipaměti tokenů, operace MSAL
• Podřízená volání rozhraní API – požadavky HTTP, získání tokenů pro rozhraní API
• Chybové stavy – Výjimky, chyby ověřování

Porozumění protokolovaným komponentám

Součást	Zdroj protokolu	Purpose
Microsoft. Identity.Web	Základní logika ověřování	Konfigurace, získání tokenu, volání rozhraní API
MSAL.NET	Microsoft.Identity.Client	Operace mezipaměti tokenů, ověření autority
IdentityModel	Ověření tokenu	Analýza JWT, ověření podpisu, extrakce nároků
ASP.NET Core autorizace a autentizace	Microsoft.AspNetCore.Authentication	Operace s cookies, výzva/zákaz akcí

---

Začínáme s protokolováním

Minimální konfigurace

Přidejte následující záznamy úrovně protokolu do appsettings.json pro aktivaci protokolování identity:

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

To umožňuje protokolování na úrovni Information pro Microsoft. Identity.Web a jeho závislosti (MSAL.NET, IdentityModel).

Konfigurace pro vývoj

Podrobná diagnostika během vývoje:

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

Produkční konfigurace

V produkčním prostředí minimalizujte svazek protokolu při zachytávání chyb:

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

---

Konfigurace filtrování protokolů

Filtrování na základě oboru názvů

Řízení úrovně podrobností protokolování podle oboru názvů Následující konfigurace nastavuje podrobné úrovně pro každý obor názvů související s identitou:

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

Zakázat specifické protokolování

Chcete-li mlčet hlučné součásti, aniž by to ovlivnilo ostatní, nastavte jejich úroveň protokolu na None nebo Warning:

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

Konfigurace specifická pro prostředí

Používá se appsettings.{Environment}.json pro nastavení pro jednotlivá prostředí:

appsettings.Development.json:

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

appsettings.Production.json:

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

---

Pochopit úrovně logování

ASP.NET Core definuje následující úrovně logování. Zvolte úroveň, která vyrovnává podrobnosti diagnostiky se svazkem protokolů pro vaše prostředí.

úrovně záznamu ASP.NET Core

Úroveň	Využití	Volume	Výroba?
Trasování	Nejpodrobnější, každá operace	Velmi vysoká	Ne
Debug	Podrobný tok, užitečný pro vývoj	Vysoko	Ne
Informace	Obecný tok, klíčové události	Mírný	Selektivní
Upozornění	Neočekávané, ale řešené podmínky	Nízká úroveň	Ano
Error	Chyby a výjimky	Velmi nízká	Ano
Kritická	Neobnovitelné chyby	Velmi nízká	Ano
Nic	Zakázání protokolování	None	Selektivní

Mapování MSAL.NET na úrovně ASP.NET Core

úroveň MSAL.NET	ASP.NET Core ekvivalent	Description
Verbose	Debug nebo Trace	Nejpodrobnější zprávy
Info	Information	Události ověřování klíčů
Warning	Warning	Neobvyklé, ale řešené podmínky
Error	Error nebo Critical	Chyby a výjimky

Použití doporučených nastavení podle prostředí

Pro každé prostředí použijte následující konfigurace.

Rozvoj:

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

Pracovní:

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

Výroby:

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

---

Konfigurujte protokolování PII

Ve výchozím nastavení Microsoft.Identity.Web odstraňuje osobní údaje (PII) z protokolů. Pokud chcete zobrazit úplné podrobnosti o uživateli, povolte protokolování PII pouze ve vývojových prostředích.

Co je PII?

Identifikovatelné osobní údaje zahrnují :

• Uživatelská jména, e-mailové adresy
• Zobrazované názvy
• ID objektů, ID tenanta
• Adresy IP
• Hodnoty tokenů, nároky

Upozornění zabezpečení

UPOZORNĚNÍ: Vy a vaše aplikace zodpovídáte za dodržování všech platných zákonných požadavků, včetně požadavků stanovených GDPR. Před povolením protokolování PII se ujistěte, že můžete bezpečně zpracovávat potenciálně citlivá data.

Povolit protokolování PII (pouze pro vývoj)

Nastavte EnablePiiLogging na true v souboru konfiguračního nastavení pro vývoj.

appsettings.Development.json:

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

Řízení protokolování PII programově

Přepnout protokolování PII podle hostitelského prostředí.

var builder = WebApplication.CreateBuilder(args);

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

Jaké změny nastanou s povolenými osobními identifikovatelnými informacemi?

Bez protokolování PII:

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

S povoleným PII:

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

Redigování osobních údajů v protokolech

Pokud je protokolování PII zakázané, citlivá data se nahradí tímto:

• {hidden} - Skryje identifikátory uživatelů.
• {hash:XXXX} – Zobrazuje hodnotu hash místo skutečné hodnoty.
• *** - Zakryje tokeny

---

Používejte ID korelace

Identifikátory korelace sledují žádosti o ověřování napříč službami. Zahrňte je do protokolů a lístků podpory, abyste urychlili řešení problémů.

Co jsou ID korelace?

ID korelace je identifikátor GUID, který jednoznačně identifikuje požadavek na ověření nebo získání tokenu napříč:

• Vaše aplikace
• Microsoft Identity Platform
• knihovna MSAL.NET
• Microsoft back-endové služby

Získání ID korelace

Metoda 1: Ze AuthenticationResult

Extrahujte ID korelace z AuthenticationResult po úspěšném získání tokenu:

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

Metoda 2: Z MsalServiceException

Zachyťte ID korelace z MsalServiceException pokud se získání tokenu nezdaří.

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

Metoda 3: Nastavení vlastního ID korelace

Přiřaďte vlastní ID korelace pro propojení trasování aplikací s požadavky Microsoft Entra ID:

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

Poskytněte ID korelace pro podporu

Když se obrátíte na podporu Microsoft, uveďte následující podrobnosti:

1. ID korelace – Ze záznamů nebo výjimek
2. Časové razítko – Kdy došlo k chybě (UTC)
3. ID tenanta – váš tenant Microsoft Entra ID
4. Kód chyby – pokud je k dispozici (např. AADSTS50058)

Příklad žádosti o podporu:

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

---

Povolení protokolování mezipaměti tokenů

Protokolování tokenové mezipaměti vám pomůže pochopit chování při úspěšném/neúspěšném přístupu do mezipaměti a diagnostikovat problémy s výkonem distribuovaných mezipamětí.

Povolení diagnostiky mezipaměti tokenů

Pro aplikace .NET Framework nebo .NET Core pomocí mezipamětí distribuovaných tokenů nakonfigurujte podrobné protokolování:

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

Příklady protokolů mezipaměti tokenů

Cache hit:

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

Neúspěšná mezipaměť:

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

Řešení potíží s distribuovanými mezipaměťmi

Povolte protokolování specifické pro poskytovatele, abyste mohli diagnostikovat problémy s připojením k mezipaměti a výkonem.

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

mezipaměť SQL Server:

Konfigurace SQL Server distribuované mezipaměti pomocí protokolování:

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

---

Řešení běžných potíží

K diagnostice častých problémů s ověřováním a autorizací použijte následující scénáře.

Běžné scénáře protokolování

Scénář 1: Selhání ověřování tokenů

Příznak: 401 Neautorizované odpovědi

Povolte podrobné protokolování:

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

Vyhledejte:

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

Scénář 2: Selhání získávání tokenů

Příznak:MsalServiceException nebo MsalUiRequiredException

Povolte podrobné protokolování:

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

Vyhledejte:

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

Scénář 3: Selhání volání podřízených rozhraní API

Příznak: Chyby HTTP 502 nebo vypršení časového limitu při volání následných rozhraní API

Povolte podrobné protokolování:

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

Přidejte do kontroleru vlastní protokolování pro zaznamenání chyb podřízených rozhraní API:

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

Interpretace vzorů protokolů

Následující příklady ukazují typický výstup protokolu pro běžné události ověřování.

Úspěšný tok ověřování:

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

Vyžaduje se souhlas:

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

Aktualizace tokenu:

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

Agregace protokolů s externími poskytovateli

Přenášejte protokoly identity do centralizované platformy protokolování pro sledování a upozorňování.

Integrace Application Insights:

Odesílání telemetrie identit do Application Insights včetně obohacení ID korelace:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

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

Integrace Serilog:

Nakonfigurujte Serilog tak, aby zachytával identity logy do konzoly a točivých souborových výstupů.

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

---

Dodržujte osvědčené postupy protokolování.

Používejte tyto postupy k zajištění bezpečnosti, užitečnosti a výkonnosti záznamů identity.

Co dělat

1. Používejte strukturované protokolování:

Předejte hodnoty jako pojmenované parametry, aby agregátory protokolů mohly indexovat a dotazovat se na ně:

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

2. Logování ID korelace:

Vždy zahrňte ID korelace do protokolů chyb, aby se zjednodušilo šetření podpory:

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

3. Použijte odpovídající úrovně protokolu:

Porovná úroveň protokolu se závažností a cílovou skupinou:

_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. Sanitizace protokolů v produkčním prostředí:

Před zápisem do produkčních protokolů maskujte citlivé hodnoty:

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

Zakázané činnosti

1. Nepovolujte PII v produkčním prostředí:

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

//  Correct
"EnablePiiLogging": false

2. Nezakládejte tajné kódy:

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

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

3. Nepoužívejte podrobné protokolování v produkčním prostředí:

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

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

Související obsah

• Přizpůsobení ověřování
• Řešení potíží s mezipamětí tokenů
• Volání následných API
• Authorization