Bejelentkezés MSAL.NET

MSAL.NET alkalmazások olyan naplóüzeneteket hoznak létre, amelyek segíthetnek a problémák diagnosztizálásában. A naplózást néhány sornyi kóddal konfigurálhatja, és egyénileg szabályozhatja a részletesség szintjét, valamint azt, hogy a rendszer naplózza-e a személyes és szervezeti adatokat. A naplózás alapértelmezés szerint nincs engedélyezve. Javasoljuk, hogy engedélyezze az MSAL-naplózást, hogy a felhasználók hitelesítési problémák esetén is elküldhessék a naplókat. Vegye figyelembe, hogy az MSAL nem tárol naplókat, és naplókat bocsát ki a naplózó implementációjában megadott célhelyre.

Note

A MSAL.NET 4.58.0-s verziójú fejlesztők is használhatják az OpenTelemetryt a naplók összesítésére és az alkalmazás teljesítményének mérésére.

Naplózási szintek

A naplózás részleteinek több szintje is van:

• LogAlways: Alapszint, amely fontos állapotmetrikák naplóit tartalmazza az MSAL-műveletek diagnosztikájának segítéséhez.
• Critical: Helyreállíthatatlan alkalmazást vagy rendszerösszeomlást leíró naplók, vagy olyan katasztrofális hiba, amely azonnali figyelmet igényel.
• Error: Azt jelzi, hogy valami hiba történt, és hiba keletkezett. Hibakeresésre és problémák azonosítására szolgál.
• Warning: Olyan esetekhez tartozó naplókat tartalmaz, amelyekben nem feltétlenül történt hiba vagy meghibásodás, hanem diagnosztikára és a problémák azonosítására szolgálnak. Ez az ajánlott minimális szint, amelyet az éles alkalmazásokban aktiválni kell.
• Informational: Az MSAL naplózza azokat az eseményeket, amelyek információs célokra szolgálnak, és nem feltétlenül hibakeresésre szolgálnak.
• Verbose: Az MSAL naplózza a kódtár viselkedésének teljes részleteit. Éles környezetben a részletes naplózási szintet csak ideiglenesen szabad engedélyezni, egy adott hibakeresési feladathoz szükséges naplók gyűjtése érdekében.

Személyes és szervezeti adatok

Alapértelmezés szerint az MSAL-naplózó nem rögzíti a bizalmas személyes vagy szervezeti adatokat. A kódtár lehetővé teszi a személyes és szervezeti adatok naplózását, ha úgy dönt, hogy ezt teszi. További részletekért lásd: A személyazonosításra alkalmas adatok kezelése MSAL.NET.

Az MSAL.NET naplózásának konfigurálása

Az MSAL-ben a naplózás az alkalmazás létrehozásakor van beállítva a WithLogging(IIdentityLogger, Boolean) szerkesztő használatával. Ez a módszer a következő paramétereket használja:

• identityLoggeraz MSAL.NET által a naplók hibakeresési vagy állapotellenőrzési célokra történő előállításához használt naplózási implementáció. A naplók csak akkor lesznek elküldve, ha a naplózás engedélyezve van.
• enablePiiLogging lehetővé teszi a személyes és szervezeti adatok (PII) naplózását, ha igaz értékre van állítva. Alapértelmezés szerint ez a paraméter hamis értékre van állítva, így az alkalmazás nem naplózza a bizalmas adatokat.

IIdentityLogger felület

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

A magasabb szintű kódtárak (Microsoft.Identity.Web, Microsoft.IdentityModel) már biztosítják ennek a felületnek a implementációit különböző környezetekhez (különösen ASP.NET Core).

IIdentityLogger implementáció

Naplózási szint egy konfigurációs fájlból

Erősen ajánlott úgy konfigurálni a kódot, hogy egy konfigurációs fájlt használjon a környezetben a naplószint beállításához, mivel lehetővé teszi a kód számára az MSAL naplózási szintjének módosítását anélkül, hogy újra kellene építenie vagy újra kellene indítania az alkalmazást. Ez diagnosztikai szempontból kulcsfontosságú, és lehetővé teszi, hogy gyorsan összegyűjtsük a szükséges naplókat a jelenleg éles környezetben futó alkalmazásból. A részletes naplózás költséges lehet, ezért alapértelmezés szerint a Informational szint használata ajánlott, és a részletes naplózást csak hiba esetén érdemes engedélyezni. Tekintse meg a JSON konfigurációszolgáltatójának példáját, amely bemutatja, hogyan tölthet be adatokat egy konfigurációs fájlból az alkalmazás újraindítása nélkül.

Naplószint környezeti változóból

Egy másik ajánlott lehetőség, ha úgy konfigurálja a kódot, hogy a gépen egy környezeti változót használjon a naplószint beállításához, mivel lehetővé teszi, hogy a kód az alkalmazás újraépítése nélkül módosítsa az MSAL naplózási szintjét.

Az elérhető naplószintek részleteiért lásd 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 használata:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Naplózás elosztott tokengyorsítótárban

Ha a .NET-ben a Microsoft.Identity.Web.TokenCache csomagból származó jogkivonat-gyorsítótár szerializálóit használja, engedélyezheti a további gyorsítótárazási naplózást.

Az elosztott gyorsítótár naplózásának engedélyezéséhez állítsa a MinLevel tulajdonságot Debug értékre.

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

További részletekért lásd : Egyéni naplózási szolgáltató implementálása .

Korrelációs azonosító

A naplók segítenek megérteni az ügyféloldalI MSAL viselkedést. A szolgáltatás oldalán zajló események megértéséhez a csapatnak korrelációs azonosítóra van szüksége. Ez az azonosító egy hitelesítési kérést követ nyomon a különböző háttérszolgáltatásokon keresztül.

A korrelációs azonosító három módon kérhető le:

1. Sikeres hitelesítési eredmény: AuthenticationResult.CorrelationId.
2. Szolgáltatáskivételből: MsalException.CorrelationId.
3. Egy egyéni korrelációs azonosító WithCorrelationId(Guid) átadásával egy jogkivonat-kérés létrehozásakor.

Ha saját korrelációs azonosítót ad meg, minden kéréshez használjon egy másik azonosítóértéket. Ne használjon állandót, mert nem tudunk különbséget tenni a kérések között.

Hálózati nyomkövetések

Important

A hálózati nyomkövetések általában személyazonosításra alkalmas adatokat és hitelesítő adatokat tartalmaznak. A naplók GitHub való közzététele előtt távolítsa el a bizalmas adatokat.

Azokban az esetekben, amikor a részletes naplók nem nyújtanak elegendő információt, hálózati nyomkövetést készíthet olyan eszközökkel, mint például a Fiddler vagy mitmproxy. Beállíthatja, hogy a választott eszköz helyi proxy legyen, és fogadja el a helyi hálózaton lévő eszközökről érkező forgalmat, lehetővé téve a nyomkövetések rögzítését más eszközökről, például iPhone-ról vagy Android-telefonokról. Előfordulhat, hogy a naplók rögzítése előtt platformspecifikus konfigurációra van szükség.

Ha ez az eszköz nem használható, módosíthatja az HttpClient MSAL által használt elemet a HTTP-forgalom naplózásához. Referenciaként tekintse meg ezt az egyéni HttpClient implementációt naplózással.

Warning

Ez a kliens nem használható éles környezetben, kizárólag naplózásra.

Az egyéni HttpClient beállítás a következő módon adható hozzá:

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

Hálózati nyomkövetések WAM használata esetén

A Windows rendszerű Web Account Manager (WAM) hálózati nyomkövetéseinek Fiddlerrel történő gyűjtéséhez néhány további lépésre van szükség.

1. Engedélyezze az AppContainer visszacsatolását a Fiddlerben a WinConfig gombra kattintva, a Kivétel minden elem kiválasztásával és a módosítások mentésével.

2. Engedélyezze a HTTPS-visszafejtést, de zárja ki az ADFS-t (msft.sts.microsoft.com) a HTTPS-visszafejtésből: