Skip to content

Commit d858bb0

Browse files
v-regandownerv-regandowner
authored
Merge pull request #208947 from trwalke/trwalke-MSFT-Patch-1
msal-logging-dotnet.md - Updates to MSAL logging documentation
2 parents b4a9913 + d95dbec commit d858bb0

File tree

2 files changed

+99
-28
lines changed

2 files changed

+99
-28
lines changed

‎articles/active-directory/develop/msal-logging-dotnet.md

Lines changed: 90 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,38 +23,104 @@ ms.custom: aaddev
2323

2424
In MSAL, logging is set at application creation using the `.WithLogging` builder modifier. This method takes optional parameters:
2525

26+
- `IIdentityLogger` is the logging implementation used by MSAL.NET to produce logs for debugging or health check purposes. Logs are only sent if logging is enabled.
2627
- `Level` enables you to decide which level of logging you want. Setting it to Errors will only get errors
27-
- `PiiLoggingEnabled` enables you to log personal and organizational data (PII) if set to true. By default, this is set to false, so that your application doesn't log personal data.
28+
- `PiiLoggingEnabled` enables you to log personal and organizational data (PII) if set to true. By default, this parameter is set to false, so that your application doesn't log personal data.
2829
- `LogCallback` is set to a delegate that does the logging. If `PiiLoggingEnabled` is true, this method will receive messages that can have PII, in which case the `containsPii` flag will be set to true.
2930
- `DefaultLoggingEnabled` enables the default logging for the platform. By default it's false. If you set it to true it uses Event Tracing in Desktop/UWP applications, NSLog on iOS and logcat on Android.
3031

31-
```csharp
32-
class Program
32+
### IIdentityLogger Interface
33+
```CSharp
34+
namespace Microsoft.IdentityModel.Abstractions
3335
{
34-
private static void Log(LogLevel level, string message, bool containsPii)
35-
{
36-
if (containsPii)
37-
{
38-
Console.ForegroundColor = ConsoleColor.Red;
39-
}
40-
Console.WriteLine($"{level} {message}");
41-
Console.ResetColor();
42-
}
43-
44-
static void Main(string[] args)
45-
{
46-
var scopes = new string[] { "User.Read" };
47-
48-
var application = PublicClientApplicationBuilder.Create("<clientID>")
49-
.WithLogging(Log, LogLevel.Info, true)
50-
.Build();
51-
52-
AuthenticationResult result = application.AcquireTokenInteractive(scopes)
53-
.ExecuteAsync().Result;
54-
}
36+
public interface IIdentityLogger
37+
{
38+
//
39+
// Summary:
40+
// Checks to see if logging is enabled at given eventLogLevel.
41+
//
42+
// Parameters:
43+
// eventLogLevel:
44+
// Log level of a message.
45+
bool IsEnabled(EventLogLevel eventLogLevel);
46+
47+
//
48+
// Summary:
49+
// Writes a log entry.
50+
//
51+
// Parameters:
52+
// entry:
53+
// Defines a structured message to be logged at the provided Microsoft.IdentityModel.Abstractions.LogEntry.EventLogLevel.
54+
void Log(LogEntry entry);
55+
}
5556
}
5657
```
5758

59+
> [!NOTE]
60+
> Partner libraries (`Microsoft.Identity.Web`, `Microsoft.IdentityModel`) provide implementations of this interface already for various environments (in particular ASP.NET Core)
61+
62+
### IIdentityLogger Implementation
63+
64+
The following code snippets are examples of such an implementation. If you use the .NET core configuration, environment variable driven logs levels can be provided for free, in addition to the configuration file based log levels.
65+
66+
#### Log level from configuration file
67+
68+
It's highly recommended to configure your code to use a configuration file in your environment to set the log level as it will enable your code to change the MSAL logging level without needing to rebuild or restart the application. This is critical for diagnostic purposes, enabling us to quickly gather the required logs from the application that is currently deployed and in production. Verbose logging can be costly so it's best to use the *Information* level by default and enable verbose logging when an issue is encountered. [See JSON configuration provider](https://docs.microsoft.com/aspnet/core/fundamentals/configuration#json-configuration-provider) for an example on how to load data from a configuration file without restarting the application.
69+
70+
#### Log Level as Environment Variable
71+
72+
Another option we recommended is to configure your code to use an environment variable on the machine to set the log level as it will enable your code to change the MSAL logging level without needing to rebuild the application. This is critical for diagnostic purposes, enabling us to quickly gather the required logs from the application that is currently deployed and in production.
73+
74+
See [EventLogLevel](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/blob/dev/src/Microsoft.IdentityModel.Abstractions/EventLogLevel.cs) for details on the available log levels.
75+
76+
Example:
77+
78+
```CSharp
79+
class MyIdentityLogger : IIdentityLogger
80+
{
81+
public EventLogLevel MinLogLevel { get; }
82+
83+
public TestIdentityLogger()
84+
{
85+
//Try to pull the log level from an environment variable
86+
var msalEnvLogLevel = Environment.GetEnvironmentVariable("MSAL_LOG_LEVEL");
87+
88+
if (Enum.TryParse(msalEnvLogLevel, out EventLogLevel msalLogLevel))
89+
{
90+
MinLogLevel = msalLogLevel;
91+
}
92+
else
93+
{
94+
//Recommended default log level
95+
MinLogLevel = EventLogLevel.Informational;
96+
}
97+
}
98+
99+
public bool IsEnabled(EventLogLevel eventLogLevel)
100+
{
101+
return eventLogLevel <= MinLogLevel;
102+
}
103+
104+
public void Log(LogEntry entry)
105+
{
106+
//Log Message here:
107+
Console.WriteLine(entry.message);
108+
}
109+
}
110+
```
111+
112+
Using `MyIdentityLogger`:
113+
```CSharp
114+
MyIdentityLogger myLogger = new MyIdentityLogger(logLevel);
115+
116+
var app = ConfidentialClientApplicationBuilder
117+
.Create(TestConstants.ClientId)
118+
.WithClientSecret("secret")
119+
.WithExperimentalFeatures() //Currently an experimental feature, will be removed soon
120+
.WithLogging(myLogger, piiLogging)
121+
.Build();
122+
```
123+
58124
> [!TIP]
59125
> See the [MSAL.NET wiki](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki) for samples of MSAL.NET logging and more.
60126

‎includes/active-directory-develop-error-logging-introduction.md

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,24 @@ ms.topic: include
88
# Purpose:
99
# Ingested by Microsoft identity platform articles in /articles/active-directory/develop/* that document error logging for the different platforms.
1010
---
11-
The Microsoft Authentication Library (MSAL) apps generate log messages that can help diagnose issues. An app can configure logging with a few lines of code, and have custom control over the level of detail and whether or not personal and organizational data is logged. We recommend you create an MSAL logging callback and provide a way for users to submit logs when they have authentication issues.
11+
The Microsoft Authentication Library (MSAL) apps generate log messages that can help diagnose issues. An app can configure logging with a few lines of code, and have custom control over the level of detail and whether or not personal and organizational data is logged. We recommend you create an MSAL logging implementation and provide a way for users to submit logs when they have authentication issues.
1212

1313
## Logging levels
1414

1515
MSAL provides several levels of logging detail:
1616

17+
- LogAlways: No level filtering is done on this log level. Log messages of all levels will be logged.
18+
- Critical: Logs that describe an unrecoverable application or system crash, or a catastrophic failure that requires immediate attention.
1719
- Error: Indicates something has gone wrong and an error was generated. Used for debugging and identifying problems.
1820
- Warning: There hasn't necessarily been an error or failure, but are intended for diagnostics and pinpointing problems.
19-
- Info: MSAL will log events intended for informational purposes not necessarily intended for debugging.
20-
- Verbose: Default. MSAL logs the full details of library behavior.
21+
- Informational: MSAL will log events intended for informational purposes not necessarily intended for debugging.
22+
- Verbose (Default): MSAL logs the full details of library behavior.
23+
24+
> [!NOTE]
25+
> Not all log levels are available for all MSAL SDK's
2126
2227
## Personal and organizational data
2328

2429
By default, the MSAL logger doesn't capture any highly sensitive personal or organizational data. The library provides the option to enable logging personal and organizational data if you decide to do so.
2530

26-
The following sections provide more details about MSAL error logging for your application.
31+
The following sections provide more details about MSAL error logging for your application.

0 commit comments

Comments
 (0)