MSAL.NET oturum açma

MSAL.NET uygulamalar sorunları tanılamaya yardımcı olabilecek günlük iletileri oluşturur. Günlüğü birkaç kod satırıyla yapılandırabilir ve ayrıntı düzeyi ile kişisel ve kuruluş verilerinin günlüğe kaydedilip kaydedilmediği üzerinde özel denetime sahip olabilirsiniz. Günlükleme varsayılan olarak etkinleştirilmemiştir. Kullanıcıların kimlik doğrulaması sorunları olduğunda günlük göndermeleri için bir yol sağlamak üzere MSAL günlüğünü etkinleştirmenizi öneririz. MSAL'nin herhangi bir günlük depolamadığını ve günlükleri günlük kaydı uygulamasında sağlanan hedefe ilettiğini unutmayın.

Note

MSAL.NET 4.58.0'dan başlayarak geliştiriciler günlükleri toplamak ve uygulama performansını ölçmek için OpenTelemetry'yi de kullanabilir.

Günlük düzeyleri

Birkaç günlükleme ayrıntı düzeyi vardır:

• LogAlways: MSAL işlemlerinin tanılanmasına yardımcı olan önemli sistem durumu ölçümlerinin günlük kayıtlarını içeren temel seviye.
• Critical: Kurtarılamayan bir uygulamayı veya sistem kilitlenmesini ya da acil dikkat gerektiren yıkıcı bir hatayı açıklayan günlükler.
• Error: Bir sorun oluştuğunu ve bir hata oluşturulduğunu gösterir. Hata ayıklama ve sorunları tanımlama için kullanılır.
• Warning: Mutlaka bir hata veya başarısızlık yaşanmadığı, ancak tanılama ve sorunların kaynağını belirleme amacı taşıyan senaryolardaki günlükleri içerir. Bu, üretim uygulamalarında etkinleştirilmesi gereken önerilen en düşük düzeydir.
• Informational: MSAL, hata ayıklamaya yönelik olmasa da bilgilendirme amaçlı olayları günlüğe kaydeder.
• Verbose: MSAL, kitaplık davranışının tüm ayrıntılarını günlüğe kaydeder. Üretim ortamında ayrıntılı düzey yalnızca belirli bir hata ayıklama amacıyla günlükleri toplamak üzere geçici olarak etkinleştirilmelidir.

Kişisel ve kurumsal veriler

Varsayılan olarak, MSAL günlükçü son derece hassas kişisel veya kuruluş verilerini yakalamaz. Kitaplık, siz karar verirseniz kişisel ve kurumsal verilerin günlüğe kaydedilmesini etkinleştirme seçeneği sunar. Ayrıntılar için MSAL.NET'te kişisel olarak tanımlanabilir bilgilerin işlenmesi konusuna bakın.

MSAL.NET'de günlüğe kaydetmeyi yapılandırma

MSAL'de günlüğe kaydetme, uygulama oluşturulurken WithLogging(IIdentityLogger, Boolean) oluşturucusu kullanılarak ayarlanır. Bu yöntem aşağıdaki parametreleri alır:

• identityLogger, hata ayıklama veya sistem durumu denetimi amacıyla günlük oluşturmak üzere MSAL.NET tarafından kullanılan günlük uygulamasıdır. Loglar yalnızca loglama etkinleştirildiğinde gönderilir.
• enablePiiLogging true olarak ayarlandığında kişisel ve kurumsal verilerin (PII) günlüğe kaydedilmesini etkinleştirir. Varsayılan olarak, uygulamanızın hassas verileri günlüğe kaydetmemesi için bu parametre false olarak ayarlanmıştır.

IIdentityLogger arabirimi

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

Üst düzey kitaplıklar (Microsoft.Identity.Web, Microsoft.IdentityModel) çeşitli ortamlar (özellikle ASP.NET Core) için bu arabirimin uygulamalarını zaten sağlar.

IIdentityLogger uygulaması

Bir yapılandırma dosyasından günlükleme düzeyi

Kodunuzu, günlükleme düzeyini ayarlamak için ortamınızdaki bir yapılandırma dosyasını kullanacak biçimde yapılandırmanız şiddetle önerilir; çünkü bu, uygulamayı yeniden derlemeden veya yeniden başlatmadan kodunuzun MSAL günlükleme düzeyini değiştirmesine olanak tanır. Bu, tanılama amacıyla kritik öneme sahiptir ve şu anda üretimde dağıtılmış olan uygulamadan gerekli günlüklerin hızlı bir şekilde toplanmasına olanak tanır. Ayrıntılı günlük kaydı maliyetli olabilir; bu nedenle varsayılan olarak Informational düzeyini kullanmak ve yalnızca bir sorunla karşılaşıldığında ayrıntılı günlük kaydını etkinleştirmek en iyi yaklaşımdır. Uygulamayı yeniden başlatmadan bir yapılandırma dosyasından veri yükleme örneği için bkz. JSON yapılandırma sağlayıcısı .

Ortam değişkeninden günlük kaydı düzeyi

Önerdiğimiz bir diğer seçenek de kodunuzun uygulamayı yeniden derlemeye gerek kalmadan MSAL günlük düzeyini değiştirmesine olanak tanıyacağı için günlük düzeyini ayarlamak için makinede bir ortam değişkeni kullanacak şekilde yapılandırmanızdır.

Kullanılabilir günlük düzeyleriyle ilgili ayrıntılar için bkz EventLogLevel .

Example:

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

MyIdentityLogger kullanımı:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Dağıtılmış belirteç önbelleğinde günlüğe alma

.NET'te Microsoft.Identity.Web.TokenCache paketindeki belirteç önbelleği serileştiricilerini kullanıyorsanız, ek önbellekleme günlüklerini etkinleştirebilirsiniz.

Dağıtılmış önbellek günlüğe kaydını etkinleştirmek için, MinLevel özelliğini Debug olarak ayarlayın.

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

Daha fazla bilgi için bkz. Özel bir günlüğe kaydetme sağlayıcısı uygulama.

Korelasyon Kimliği

Günlükler, istemci tarafındaki MSAL davranışını anlamanıza yardımcı olur. Hizmet tarafında neler olduğunu anlamak için ekibin bir bağıntı kimliğine ihtiyacı vardır. Bu kimlik, çeşitli arka uç hizmetleri aracılığıyla bir kimlik doğrulama isteğini izler.

Bağıntı kimliği üç yolla elde edilebilir:

1. Başarılı bir kimlik doğrulama sonucundan: AuthenticationResult.CorrelationId.
2. Bir hizmet istisnasından: MsalException.CorrelationId.
3. Bir belirteç isteği oluştururken özel bir korelasyon kimliğini WithCorrelationId(Guid) öğesine geçirerek.

Kendi bağıntı kimliğinizi sağlarken, her istek için farklı bir kimlik değeri kullanın. İstekler arasında ayrım yapamayacağımız için sabit kullanmayın.

Ağ izleri

Important

Ağ izlemeleri genellikle kişisel bilgileri ve kimlik bilgilerini içerir. Günlükleri GitHub göndermeden önce hassas ayrıntıları kaldırın.

Ayrıntılı günlüklerin yeterli içgörü sağlamadığı durumlarda , Fiddler veya mitmproxygibi araçları kullanarak bir ağ izlemesi alabilirsiniz. Seçtiğiniz aracı yerel ara sunucu olacak şekilde yapılandırabilir ve yerel ağınızdaki cihazlardan gelen trafiği kabul ederek iPhone veya Android telefonlar gibi diğer cihazlardan izlemeleri yakalamanızı sağlayabilirsiniz. Günlükleri yakalamadan önce platforma özgü yapılandırma gerekebilir.

Böyle bir aracı kullanmak mümkün değilse, HTTP trafiğini günlüğe kaydetmek için MSAL’in kullandığı HttpClient öğesini değiştirebilirsiniz. Referans için, günlük kaydı içeren bu özel HttpClient uygulamaya bakın.

Warning

Bu istemci üretimde kullanılmamalıdır; yalnızca günlükleme için kullanılmalıdır.

Özel HttpClient şu şekilde eklenebilir:

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

WAM kullanırken ağ izleri

Fiddler ile Windows web hesabı yöneticisinin (WAM) ağ izlemelerini toplamak için birkaç ek adım gerekir.

1. WinConfig'e tıklayıp Tümünü Muaf Tut'u seçerek ve değişiklikleri kaydederek Fiddler'da AppContainer geri döngüyü etkinleştirin.

2. HTTPS şifre çözmeyi etkinleştirin, ancak ADFS'yi (msft.sts.microsoft.com) HTTPS şifre çözmeden hariç tutun: