Konfigurasikan pengelogan di Microsoft. Identity.Web

Microsoft. Identity.Web terintegrasi dengan infrastruktur pengelogan ASP.NET Core. Gunakan untuk mendiagnosis masalah di seluruh hal berikut:

  • Alur autentikasi - Masuk, keluar, validasi token
  • Perolehan token - Perhitungan/meleset tembolok token, operasi MSAL
  • Panggilan API hilir - Permintaan HTTP, akuisisi token untuk API
  • Kondisi kesalahan - Pengecualian, kegagalan validasi

Memahami komponen yang dicatat

Komponen Sumber Log Kegunaan
Microsoft. Identity.Web Logika autentikasi inti Konfigurasi, akuisisi token, panggilan API
MSAL.NET Microsoft.Identity.Client Operasi cache token, validasi otoritas
IdentityModel Validasi token Penguraian JWT, validasi tanda tangan, ekstraksi klaim
ASP.NET Core Auth Microsoft.AspNetCore.Authentication Operasi cookie, tantangan/tindakan terlarang

Mulai pengelogan

Konfigurasi minimal

Tambahkan entri tingkat log berikut ke appsettings.json untuk mengaktifkan identitas pengelogan:

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

Ini memungkinkan pencatatan tingkat Informasi untuk Microsoft.Identity.Web dan dependensinya (MSAL.NET, IdentityModel).

Konfigurasi pengembangan

Untuk diagnostik terperinci selama pengembangan:

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

Konfigurasi produksi

Untuk produksi, minimalkan volume log saat menangkap kesalahan:

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

Mengonfigurasi pemfilteran log

Pemfilteran berbasis namespace

Mengontrol verbositas log menurut namespace. Konfigurasi berikut menetapkan tingkat terperinci untuk setiap namespace terkait identitas:

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

Menonaktifkan pengelogan tertentu

Untuk membungkam komponen berisik tanpa memengaruhi orang lain, atur tingkat log mereka ke None atau Warning:

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

Konfigurasi khusus lingkungan

Gunakan appsettings.{Environment}.json untuk pengaturan per lingkungan:

appsettings.Development.json:

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

appsettings.Production.json:

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

Memahami tingkat log

ASP.NET Core menentukan tingkat log berikut. Pilih tingkat yang menyeimbangkan detail diagnostik terhadap volume log untuk lingkungan Anda.

ASP.NET Core tingkatan log

Tingkat Penggunaan Volume Produksi?
Jejak Paling rinci, setiap operasi Sangat Tinggi No
Debug Alur terperinci, berguna untuk dev Tinggi No
Informasi Alur umum, peristiwa utama Menengah Selektif
Peringatan Kondisi yang tidak terduga tetapi ditangani Kurang Penting Yes
Kesalahan Kesalahan dan pengecualian Sangat Rendah Yes
Kritis Kegagalan yang tidak dapat dipulihkan Sangat Rendah Yes
Tidak Menonaktifkan pengelogan Tidak Selektif

Memetakan tingkat MSAL.NET ke ASP.NET Core

Tingkat MSAL.NET ASP.NET Core yang setara Deskripsi
Verbose Debug atau Trace Pesan paling terperinci
Info Information Peristiwa autentikasi kunci
Warning Warning Kondisi abnormal tetapi ditangani
Error Error atau Critical Kesalahan dan pengecualian

Gunakan konfigurasi berikut per lingkungan.

Pengembangan:

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

Pementasan:

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

Produksi:

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

Mengonfigurasi pengelogan PII

Secara default, Microsoft. Identity.Web meredaksi informasi pengidentifikasi pribadi (PII) dari log. Aktifkan pengelogan PII hanya di lingkungan pengembangan untuk melihat detail pengguna lengkap.

Apa itu PII?

Informasi Pengidentifikasi Pribadi (PII) meliputi:

  • Nama pengguna, alamat email
  • Nama tampilan
  • ID obyek, ID penyewa
  • Alamat IP
  • Nilai token, klaim

Peringatan keamanan

PERINGATAN: Anda dan aplikasi Anda bertanggung jawab untuk mematuhi semua persyaratan peraturan yang berlaku termasuk yang ditetapkan oleh GDPR. Sebelum mengaktifkan pengelogan PII, pastikan Anda dapat menangani data yang berpotensi sangat sensitif ini dengan aman.

Mengaktifkan pencatatan PII (pengembangan saja)

Atur EnablePiiLogging ke true dalam file konfigurasi pengembangan Anda:

appsettings.Development.json:

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

Mengontrol pengelogan PII secara terprogram

Aktifkan/matikan pencatatan PII berdasarkan pada lingkungan hosting.

var builder = WebApplication.CreateBuilder(args);

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

Perubahan apa dengan PII diaktifkan?

Tanpa pencatatan PII:

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

Dengan PII diaktifkan:

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

Penyensoran PII dalam log

Saat pengelogan PII dinonaktifkan, data sensitif diganti dengan:

  • {hidden} - Menyembunyikan pengidentifikasi pengguna
  • {hash:XXXX} - Menunjukkan hash alih-alih nilai aktual
  • *** - Mengaburkan token

Menggunakan ID korelasi

ID korelasi melacak permintaan autentikasi di seluruh layanan. Sertakan dalam log dan tiket dukungan untuk mempercepat penyelesaian masalah.

Apa itu ID korelasi?

ID korelasi adalah GUID yang secara unik mengidentifikasi permintaan autentikasi atau akuisisi token di seluruh:

  • Aplikasi Anda
  • Platform Identitas Microsoft
  • pustaka MSAL.NET
  • layanan backend Microsoft

Mendapatkan ID korelasi

Metode 1: Dari AuthenticationResult

Ekstrak ID korelasi dari AuthenticationResult setelah akuisisi token berhasil:

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

Metode 2: Dari MsalServiceException

Ambil ID korelasi dari MsalServiceException saat akuisisi token gagal:

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

Metode 3: Mengatur ID korelasi khusus

Tetapkan ID korelasi kustom untuk menautkan jejak aplikasi dengan permintaan 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);
}

Menyediakan ID korelasi untuk dukungan

Saat Anda menghubungi dukungan Microsoft, berikan detail berikut:

  1. ID Korelasi - Dari log atau pengecualian
  2. Tanda waktu - Ketika kesalahan terjadi (UTC)
  3. ID Penyewa - Penyewa Microsoft Entra ID Anda
  4. Kode kesalahan - Jika berlaku (misalnya, AADSTS50058)

Contoh permintaan dukungan:

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

Mengaktifkan pencatatan cache token

Pengelogan cache token membantu Anda memahami perilaku hit/miss cache dan mendiagnosis masalah performa dengan cache terdistribusi.

Mengaktifkan diagnostik cache token

Untuk aplikasi .NET Framework atau .NET Core menggunakan cache token terdistribusi, konfigurasikan pengelogan terperinci:

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

Contoh log cache token

Tembolok hit:

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

Kegagalan cache:

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

Memecahkan masalah cache terdistribusi

Aktifkan pengelogan khusus penyedia untuk mendiagnosis konektivitas cache dan masalah performa.

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:

Konfigurasikan cache terdistribusi SQL Server dengan pengelogan:

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

Pemecahan Masalah Umum

Gunakan skenario berikut untuk mendiagnosis masalah autentikasi dan otorisasi yang sering terjadi.

Skenario pengelogan umum

Skenario 1: Kegagalan validasi token

Gejala: 401 Respons tidak sah

Aktifkan pengelogan terperinci:

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

Mencari:

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

Skenario 2: Kegagalan akuisisi token

Gejala:MsalServiceException Atau MsalUiRequiredException

Aktifkan pengelogan terperinci:

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

Mencari:

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

Skenario 3: Kegagalan panggilan API hilir

Gejala: KESALAHAN HTTP 502 atau waktu habis memanggil API hilir

Aktifkan pengelogan terperinci:

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

Tambahkan pengelogan kustom di pengontrol Anda untuk menangkap kesalahan API hilir:

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

Menginterpretasikan pola log

Contoh berikut menunjukkan output log umum untuk peristiwa autentikasi umum.

Alur autentikasi berhasil:

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

Persetujuan diperlukan:

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

Pembaruan token:

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

Menggabungkan log dengan penyedia eksternal

Meneruskan log identitas ke platform pengelogan terpusat untuk pemantauan dan pemberitahuan.

Integrasi Application Insights:

Kirim telemetri identitas ke Application Insights dengan pengayaan ID korelasi:

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

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

Integrasi serilog:

Konfigurasikan Serilog untuk mengambil log identitas ke konsol dan output file bergulir:

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

Mengikuti praktik terbaik dalam pencatatan log

Terapkan praktik ini untuk menjaga log identitas Anda tetap aman, berguna, dan berkinerja.

Yang Harus Dilakukan

1. Gunakan pengelogan terstruktur:

Teruskan nilai sebagai parameter bernama sehingga agregator log dapat mengindeks dan mengkuerinya:

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

2. ID log korelasi:

Selalu sertakan ID korelasi dalam log kesalahan untuk menyederhanakan penyelidikan dukungan:

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

3. Gunakan tingkat log yang sesuai:

Sesuaikan tingkat log dengan tingkat keparahan dan audiens:

_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. Membersihkan log dalam produksi:

Menutupi nilai sensitif sebelum menulisnya ke log produksi:

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

Hal-hal yang Tidak Boleh Dilakukan

1. Jangan aktifkan PII dalam lingkungan produksi:

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

//  Correct
"EnablePiiLogging": false

2. Jangan mencatat rahasia:

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

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

3. Jangan gunakan pencatatan verbose dalam lingkungan produksi:

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

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

Konten terkait

  • Last updated on