Microsoft.Identity.Web'de günlüğe kaydetmeyi yapılandırın.

Microsoft.Identity.Web, ASP.NET Core günlük altyapısıyla entegre olur. Aşağıdakiler arasında sorunları tanılamak için bunu kullanın:

• Kimlik doğrulama akışları - Oturum açma, oturum kapatma, belirteç doğrulama
• Belirteç edinme - Belirteç önbelleği isabetleri/kaçırmaları, MSAL işlemleri
• Aşağı akış API çağrıları - HTTP istekleri, API'ler için belirteç alma
• Hata koşulları - Özel durumlar, doğrulama hataları

Günlüğe kaydedilen bileşenleri anlamak

Bileşen	Kayıt Kaynağı	Amaç
Microsoft. Identity.Web	Çekirdek kimlik doğrulama mantığı	Yapılandırma, belirteç alma, API çağrıları
MSAL.NET	Microsoft.Identity.Client	Belirteç önbelleği işlemleri, yetkili doğrulama
IdentityModel	Jeton doğrulama	JWT ayrıştırma, imza doğrulama, talep ayıklama
ASP.NET Core Kimlik Doğrulaması	Microsoft.AspNetCore.Authentication	Çerez işlemleri, zorluk çıkarma/yasaklama eylemleri

---

Loglamaya başlangıç

En az yapılandırma

Kimlik günlüğünü etkinleştirmek için aşağıdaki günlük seviyesi girdilerini appsettings.json ekleyin:

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

Bu, Microsoft.Identity.Web ve bağımlılıkları (MSAL.NET, IdentityModel) için Bilgi düzeyinde günlüğü etkinleştirir.

Geliştirme yapılandırması

Geliştirme sırasında ayrıntılı tanılama için:

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

Üretim yapılandırması

Prodüksiyon süreçlerinde, hataları yakalarken günlük kaydı hacmini en aza indirin.

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

---

Günlük filtrelemeyi yapılandırma

Ad alanı tabanlı filtreleme

Günlük ayrıntı düzeyini ad alanına göre denetleme. Aşağıdaki yapılandırma, kimlikle ilgili her ad alanı için ayrıntılı düzeyleri ayarlar:

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

Belirli kaydı devre dışı bırakma

Gürültülü bileşenleri diğerlerini etkilemeden susturmak için günlük düzeylerini None veya Warning olarak ayarlayın.

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

Ortama özgü yapılandırma

Ortam başına ayarlar için kullanın appsettings.{Environment}.json :

appsettings.Development.json:

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

appsettings.Production.json:

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

---

Günlük seviyelerini anlamak

ASP.NET Core aşağıdaki kayıt seviyelerini tanımlar. Ortamınız için tanılama ayrıntılarını günlük birimiyle dengeleyen düzeyi seçin.

ASP.NET Core günlük düzeyleri

Seviye	Kullanım	Volume	Üretim?
İzleme	En ayrıntılı, her işlem	Çok Yüksek	Hayır
Hata ayıklama	Ayrıntılı akış, geliştirme için kullanışlıdır	Yüksek	Hayır
Information	Genel akış, önemli olaylar	Orta	Seçici
Uyarı	Beklenmeyen ancak ele alınan koşullar	Low	Evet
Error	Hatalar ve özel durumlar	Çok Düşük	Evet
Kritik	Kurtarılamaz hatalar	Çok Düşük	Evet
Hiçbiri	Günlüğü devre dışı bırakma	Hiçbiri	Seçici

MSAL.NET'i ASP.NET Core düzeyleriyle eşleştirme

MSAL.NET Düzeyi	ASP.NET Core Eşdeğeri	Açıklama
Verbose	Debug veya Trace	En ayrıntılı iletiler
Info	Information	Anahtar kimlik doğrulama olayları
Warning	Warning	Anormal ancak yönetilen koşullar
Error	Error veya Critical	Hatalar ve özel durumlar

Ortama göre önerilen ayarları uygulama

Ortam başına aşağıdaki yapılandırmaları kullanın.

Geliştirme:

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

Hazırlama:

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

Üretim:

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

---

PII günlüğünü yapılandırma

Varsayılan olarak, Microsoft.Identity.Web kişisel olarak tanımlanabilen bilgileri (PII) günlüklerden gizler. Tüm kullanıcı ayrıntılarını görmek için yalnızca geliştirme ortamlarında PII günlüğünü etkinleştirin.

PII nedir?

Kişisel Bilgiler (PII) şunları içerir:

• Kullanıcı adları, e-posta adresleri
• Görünen adlar
• Nesne Kimlikleri, kiracı kimlikleri
• IP adresleri
• Belirteç değerleri, iddialar

Güvenlik uyarısı

UYARI: Gdpr tarafından belirlenenler de dahil olmak üzere tüm geçerli mevzuat gereksinimlerine uymak sizin ve uygulamanızın sorumluluğundadır. PII günlüğünü etkinleştirmeden önce bu yüksek oranda hassas olabilecek verileri güvenli bir şekilde işleyebileceğinizden emin olun.

PII günlüğünü etkinleştir (yalnızca geliştirme)

Geliştirme yapılandırma dosyanızda EnablePiiLogging'i true olarak ayarlayın.

appsettings.Development.json:

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

PII günlüğünü program aracılığıyla denetleme

Barındırma ortamına göre PII günlüğünü açma/kapatma:

var builder = WebApplication.CreateBuilder(args);

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

PII etkinken hangi değişiklikler var?

PII günlüğü olmadan:

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

PII bilgileri etkinken:

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

Günlüklerde PII gizleme

PII günlüğü devre dışı bırakıldığında hassas veriler şununla değiştirilir:

• {hidden} - Kullanıcı tanımlayıcılarını gizler
• {hash:XXXX} - Gerçek değer yerine karmayı gösterir
• *** - Belirteçleri gizler

---

Bağıntı kimliklerini kullanma

Bağıntı kimlikleri, hizmetler arasında kimlik doğrulama isteklerini izler. Sorun çözümünü hızlandırmak için bunları günlüklere ve destek biletlerine ekleyin.

Bağıntı kimlikleri nedir?

Bağıntı kimliği, aşağıdakiler arasında kimlik doğrulaması veya belirteç alma isteğini benzersiz olarak tanımlayan bir GUID'dir :

• Uygulamanız
• Microsoft Kimlik platformu
• MSAL.NET kitaplığı
• Microsoft arka uç hizmetleri

Bağıntı kimliklerini alma

Yöntem 1: AuthenticationResult'tan

Başarılı bir belirteç alımından sonra korelasyon kimliğini AuthenticationResult içinden ayıklayın.

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

Yöntem 2: MsalServiceException'dan

Belirteç alımı başarısız olduğunda MsalServiceException üzerindeki korrelasyon kimliğini alın.

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

Yöntem 3: Özel bağıntı kimliği ayarlama

Uygulama izlemelerini Microsoft Entra ID isteklerine bağlamak için özel bir bağıntı kimliği atayın:

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

Destek için bağıntı kimlikleri sağlayın

Microsoft desteğe başvurarak aşağıdaki ayrıntıları sağlayın:

1. Bağıntı Kimliği - Günlüklerden veya istisna
2. Zaman damgası - Hatanın oluştuğu zaman (UTC)
3. Tenant Kimliği - Microsoft Entra ID kiracınız
4. Hata kodu - Varsa (örn. AADSTS50058)

Örnek destek isteği:

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

---

Belirteç önbelleği günlüğünü etkinleştirme

Belirteç önbelleği günlüğü, önbellek isabeti/yanıtsız davranışını anlamanıza ve dağıtılmış önbelleklerle ilgili performans sorunlarını tanılamanıza yardımcı olur.

Belirteç önbelleği tanılamasını etkinleştirme

.NET Framework veya .NET Core uygulamalarında dağıtılmış belirteç önbellekleri kullanıldığında, detaylı loglama yapılandırması:

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

Jeton önbellek kaydı örnekleri

Önbellek isabeti:

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

Önbellek hatası:

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

Dağıtılmış önbelleklerle ilgili sorunları giderme

Önbellek bağlantısı ve performans sorunlarını tanılamak için sağlayıcıya özgü günlüğe kaydetmeyi etkinleştirin.

Redis önbellek:

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:

Günlük kaydıyla SQL Server dağıtılmış önbelleği yapılandırı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);
});

---

Yaygın sorunları giderme

Sık karşılaşılan kimlik doğrulama ve yetkilendirme sorunlarını tanılamak için aşağıdaki senaryoları kullanın.

Yaygın loglama senaryoları

Senaryo 1: Belirteç doğrulama hataları

Belirti: 401 Yetkisiz yanıtlar

Ayrıntılı günlük kaydını etkinleştirin:

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

Şunu arayın:

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

Senaryo 2: Belirteç alma hataları

Belirti:MsalServiceException Veya MsalUiRequiredException

Ayrıntılı günlük kaydını etkinleştirin:

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

Şunu arayın:

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

Senaryo 3: Aşağı Akış API çağrısı hataları

Belirti: HTTP 502 veya aşağı akış API'lerine yapılan çağrılardaki zaman aşımı hataları

Ayrıntılı günlük kaydını etkinleştirin:

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

Aşağı akış API hatalarını yakalamak için denetleyicinize özel günlük kaydı ekleyin:

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

Günlük kayıtlarını yorumla

Aşağıdaki örneklerde, yaygın kimlik doğrulama olayları için tipik günlük çıktıları gösterilmektedir.

Başarılı kimlik doğrulama akışı:

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

Onay gerekli:

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

Jeton yenileme:

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

Dış sağlayıcılarla günlükleri toplama

kimlik günlüklerini izleme ve uyarı için merkezi bir günlüğe kaydetme platformuna iletin.

Application Insights tümleştirmesi:

Bağıntı kimliği zenginleştirmesi ile Application Insights'a kimlik telemetrisi gönderin:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

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

Serilog tümleştirmesi:

Serilog'u kimlik günlüklerini konsola ve dönen dosya çıktıları olarak yakalayacak şekilde yapılandırın.

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

---

Kayıt tutma en iyi uygulamalarını izleyin

Kimlik günlüklerinizi güvenli, kullanışlı ve performanslı tutmak için bu uygulamaları uygulayın.

Yapılması Gerekenler

1. Yapılandırılmış günlüklendirmeyi kullanın:

Günlük toplayıcılarının bunları dizinleyip sorgulayabilmesi için değerleri adlandırılmış parametreler olarak geçirin:

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

2. Kayıt bağıntı kimlikleri:

Destek araştırmalarını basitleştirmek için her zaman hata günlüklerine bağıntı kimliğini ekleyin:

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

3. Uygun log seviyelerini kullanın:

Log seviyesini önem derecesi ve hedef kitleyle uygulayın:

_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. Üretimdeki logları arındırma:

Hassas değerleri üretim günlüklerine yazmadan önce maskeleyin:

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

Yapılmaması Gerekenler

1. Üretimde PII'yi etkinleştirmeyin:

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

//  Correct
"EnablePiiLogging": false

2. Gizli bilgileri günlüğe kaydetmeyin:

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

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

3. Üretimde ayrıntılı günlük kaydı kullanmayın:

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

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

İlgili içerik

• Kimlik Doğrulamasını Özelleştirme
• Belirteç önbelleği sorunlarını giderme
• Aşağı akış API'lerini çağırma
• Authorization