Pengelogan di MSAL.NET

MSAL.NET aplikasi menghasilkan pesan log yang dapat membantu mendiagnosis masalah. Anda dapat mengonfigurasi pengelogan dengan beberapa baris kode, dan memiliki kontrol kustom atas tingkat detail dan apakah data pribadi dan organisasi dicatat atau tidak. Pengelogan tidak diaktifkan secara default. Sebaiknya Aktifkan pengelogan MSAL untuk menyediakan cara bagi pengguna untuk mengirimkan log saat mereka memiliki masalah autentikasi. Perhatikan bahwa MSAL tidak menyimpan log apa pun dan memancarkan log ke tujuan yang disediakan dalam implementasi pencatat.

Note

Mulai MSAL.NET 4.58.0, pengembang juga dapat menggunakan OpenTelemetry untuk mengagregasi log dan mengukur kinerja aplikasi.

Tingkat Pengelogan

Ada beberapa tingkat detail pencatatan log:

• LogAlways: Tingkat dasar yang mencakup log metrik kesehatan penting untuk membantu diagnostik operasi MSAL.
• Critical: Log yang menjelaskan aplikasi atau crash sistem yang tidak dapat dipulihkan, atau kegagalan bencana yang membutuhkan perhatian segera.
• Error: Menunjukkan bahwa telah terjadi kesalahan dan sebuah error dihasilkan. Digunakan untuk debugging dan mengidentifikasi masalah.
• Warning: Menyertakan log dalam skenario ketika belum tentu ada kesalahan atau kegagalan, tetapi ditujukan untuk diagnostik dan menentukan masalah. Ini adalah tingkat minimum yang direkomendasikan yang harus diaktifkan di aplikasi produksi.
• Informational: MSAL akan mencatat kejadian untuk tujuan informatif, tidak selalu ditujukan untuk penelusuran kesalahan.
• Verbose: MSAL mencatat detail lengkap perilaku pustaka. Di lingkungan produksi, tingkat verbose hanya boleh diaktifkan sementara untuk mengumpulkan log untuk tujuan penelusuran kesalahan tertentu.

Data pribadi dan organisasi

Secara default, pencatat MSAL tidak mengambil data pribadi atau organisasi yang sangat sensitif. Pustaka menyediakan opsi untuk mengaktifkan pengelogan data pribadi dan organisasi jika Anda memutuskan untuk melakukannya. Untuk detailnya, lihat Penanganan informasi yang dapat diidentifikasi secara pribadi di MSAL.NET.

Mengonfigurasi pengelogan di MSAL.NET

Di MSAL, pencatatan log diatur saat aplikasi dibuat menggunakan builder WithLogging(IIdentityLogger, Boolean). Metode ini mengambil parameter berikut:

• identityLoggeradalah implementasi pengelogan yang digunakan oleh MSAL.NET untuk menghasilkan log untuk tujuan penelusuran kesalahan atau pemeriksaan kesehatan. Log hanya dikirim jika pengelogan diaktifkan.
• enablePiiLogging memungkinkan pengelogan data pribadi dan organisasi (PII) jika diatur ke true. Secara default, parameter ini diatur ke false, sehingga aplikasi Anda tidak mencatat data sensitif.

Antarmuka IIdentityLogger

namespace Microsoft.IdentityModel.Abstractions
{
    public interface IIdentityLogger
    {
        //
        // Summary:
        //     Checks to see if logging is enabled at given eventLogLevel.
        //
        // Parameters:
        //   eventLogLevel:
        //     Log level of a message.
        bool IsEnabled(EventLogLevel eventLogLevel);

        //
        // Summary:
        //     Writes a log entry.
        //
        // Parameters:
        //   entry:
        //     Defines a structured message to be logged at the provided Microsoft.IdentityModel.Abstractions.LogEntry.EventLogLevel.
        void Log(LogEntry entry);
    }
}

Note

Pustaka tingkat lebih tinggi (Microsoft.Identity.Web, Microsoft.IdentityModel) sudah menyediakan implementasi antarmuka ini untuk berbagai lingkungan (khususnya ASP.NET Core).

Implementasi IIdentityLogger

Tingkat log dari file konfigurasi

Sangat disarankan untuk mengonfigurasi kode Anda untuk menggunakan file konfigurasi di lingkungan Anda untuk mengatur tingkat log karena akan memungkinkan kode Anda untuk mengubah tingkat pengelogan MSAL tanpa perlu membangun kembali atau menghidupkan ulang aplikasi. Ini sangat penting untuk tujuan diagnostik, memungkinkan untuk mengumpulkan log yang diperlukan dengan cepat dari aplikasi yang saat ini disebarkan dalam produksi. Pencatatan log verbose dapat memakan biaya besar, jadi sebaiknya gunakan tingkat Informational secara default dan aktifkan pencatatan log verbose saat terjadi masalah. Lihat penyedia konfigurasi JSON untuk contoh tentang cara memuat data dari file konfigurasi tanpa memulai ulang aplikasi.

Tingkat log dari variabel lingkungan

Opsi lain yang kami rekomendasikan adalah mengonfigurasi kode Anda untuk menggunakan variabel lingkungan pada komputer untuk mengatur tingkat log karena akan memungkinkan kode Anda untuk mengubah tingkat pengelogan MSAL tanpa perlu membangun kembali aplikasi.

Lihat EventLogLevel untuk detail tentang tingkat log yang tersedia.

Contoh:

class MyIdentityLogger : IIdentityLogger
{
    public EventLogLevel MinLogLevel { get; }

    public MyIdentityLogger()
    {
        //Retrieve the log level from an environment variable
        var msalEnvLogLevel = Environment.GetEnvironmentVariable("MSAL_LOG_LEVEL");

        if (Enum.TryParse(msalEnvLogLevel, out EventLogLevel msalLogLevel))
        {
            MinLogLevel = msalLogLevel;
        }
        else
        {
            //Recommended default log level
            MinLogLevel = EventLogLevel.Informational;
        }
    }

    public bool IsEnabled(EventLogLevel eventLogLevel)
    {
        return eventLogLevel <= MinLogLevel;
    }

    public void Log(LogEntry entry)
    {
        //Log Message here:
        Console.WriteLine(entry.Message);
    }
}

Menggunakan MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

var app = ConfidentialClientApplicationBuilder
    .Create(TestConstants.ClientId)
    .WithClientSecret("secret")
    .WithLogging(myLogger, enablePiiLogging)
    .Build();

Pengelogan dalam cache token terdistribusi

Jika Anda menggunakan serializer cache token dari paket Microsoft.Identity.Web.TokenCache di .NET, Anda dapat mengaktifkan log cache tambahan.

Untuk mengaktifkan pengelogan cache terdistribusi, atur properti ke MinLevelDebug.

     app.AddDistributedTokenCache(services =>
     {
          services.AddDistributedMemoryCache();
          services.AddLogging(configure => configure.AddConsole())
               .Configure<LoggerFilterOptions>(options => options.MinLevel = Microsoft.Extensions.Logging.LogLevel.Debug);
     });

Lihat Menerapkan penyedia pengelogan kustom untuk detail selengkapnya.

ID korelasi

Log membantu memahami perilaku MSAL di sisi klien. Untuk memahami apa yang terjadi di sisi layanan, tim memerlukan ID korelasi. ID ini melacak permintaan autentikasi melalui berbagai layanan backend.

ID korelasi dapat diperoleh dengan tiga cara:

1. Dari hasil autentikasi yang berhasil: AuthenticationResult.CorrelationId.
2. Dari pengecualian layanan: MsalException.CorrelationId.
3. Dengan meneruskan ID korelasi kustom ke WithCorrelationId(Guid) saat membuat permintaan token.

Saat memberikan ID korelasi Anda sendiri, gunakan nilai ID yang berbeda untuk setiap permintaan. Jangan gunakan konstanta karena kami tidak akan dapat membedakan antara permintaan.

Jejak jaringan

Important

Jejak jaringan biasanya berisi informasi dan kredensial yang dapat diidentifikasi secara pribadi. Hapus detail sensitif apa pun sebelum memposting log di GitHub.

Jika log verbose tidak memberikan informasi yang memadai, Anda dapat mengambil jejak jaringan menggunakan alat seperti Fiddler atau mitmproxy. Anda dapat mengonfigurasi alat pilihan Anda untuk menjadi proksi lokal dan menerima lalu lintas dari perangkat di jaringan lokal Anda, memungkinkan Anda untuk mengambil jejak dari perangkat lain, seperti ponsel iPhone atau Android. Konfigurasi khusus platform mungkin diperlukan sebelum mengambil log.

Jika alat tersebut tidak memungkinkan untuk digunakan, Anda dapat memodifikasi yang HttpClient digunakan oleh MSAL untuk mencatat lalu lintas HTTP. Untuk referensi, lihat implementasi kustom HttpClient ini dengan pengelogan.

Warning

Klien ini tidak boleh digunakan dalam produksi dan hanya untuk pengelogan.

Kustom HttpClient dapat ditambahkan seperti ini:

var msalPublicClient = PublicClientApplicationBuilder
       .Create(ClientId)
       .WithHttpClientFactory(new HttpSnifferClientFactory())
       .Build();

Jejak jaringan saat menggunakan WAM

Untuk mengumpulkan jejak jaringan untuk Web Account Manager (WAM) pada Windows dengan Fiddler, diperlukan beberapa langkah tambahan.

1. Aktifkan loopback AppContainer di Fiddler dengan mengklik WinConfig, memilih Kecualikan Semua dan simpan perubahan.

2. Aktifkan dekripsi HTTPS, tetapi kecualikan ADFS (msft.sts.microsoft.com) dari dekripsi HTTPS: