Merge pull request #142 from AzureAD/servicing

Servicing release 2.13.112171830
AzureAD · Dec 18, 2014 · 328bb3d · 328bb3d
2 parents 4460723 + 951e141
commit 328bb3d
Show file tree

Hide file tree

Showing 38 changed files with 535 additions and 173 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,126 @@ Here you can find the source code for the library. You can find the correspondin
 
 [We provide a full suite of sample applications and documentation on GitHub](https://github.com/AzureADSamples) to help you get started with learning the Azure Identity system. This includes tutorials for native clients such as Windows, Windows Phone, iOS, OSX, Android, and Linux. We also provide full walkthroughs for authentication flows such as OAuth2, OpenID Connect, Graph API, and other awesome features. 
 
+## Diagnostics
+
+The following are the primary sources of information for diagnosing issues:
+
++ Exceptions
++ Logs
++ Network traces
+
+Also, note that correlation IDs are central to the diagnostics in the library.  You can set your correlation IDs on a per request basis (by setting `CorrelationId` property on `AuthenticationContext` before calling an acquire token method) if you want to correlate an ADAL request with other operations in your code. If you don't set a correlations id, then ADAL will generate a random one which changes on each request. All log messages and network calls will be stamped with the correlation id.  
+
+### Exceptions
+
+This is obviously the first diagnostic.  We try to provide helpful error messages.  If you find one that is not helpful please file an [issue](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues) and let us know. Please also provide the target platform of your application (e.g. Desktop, Windows Store, Windows Phone).
+
+### Logs
+
+You can configure the library to generate log messages that you can use to help diagnose issues.  You configure logging by setting properties of the static class `AdalTrace`; however, depending on the platform, logging methods and the properties of this class differ. Here is how logging works on each platform:
+
+#### Desktop Applications
+
+ADAL.NET for desktop applications by default logs via `System.Diagnostics.Trace` class. You can add a trace listener to receive those logs. You can also control tracing using this method (e.g. change trace level or turn it off) using `AdalTrace.LegacyTraceSwitch`. 
+
+The following example shows how to add a Console based listener and set trace level to `Information` (the default trace level is `Verbose`):
+
+```
+Trace.Listeners.Add(new ConsoleTraceListener());
+AdalTrace.LegacyTraceSwitch.Level = TraceLevel.Info;
+```
+
+You can achieve the same result by adding the following lines to your application's config file:
+
+```
+  <system.diagnostics>
+    <sharedListeners>
+      <add name="console" 
+        type="System.Diagnostics.ConsoleTraceListener" 
+        initializeData="false"/>
+    </sharedListeners>
+    <trace autoflush="true">
+      <listeners>
+        <add name="console" />
+      </listeners>
+    </trace>    
+    <switches>
+      <add name="ADALLegacySwitch" value="Info"/>
+    </switches>
+  </system.diagnostics>
+```
+
+If you would like to have more control over how tracing is done in ADAL, you can add a `TraceListener` to ADAL's dedicated `TraceSource` with name **"Microsoft.IdentityModel.Clients.ActiveDirectory"**. 
+
+The following example shows how to write ADAL's traces to a text file using this method:
+
+```
+Stream logFile = File.Create("logFile.txt");
+AdalTrace.TraceSource.Listeners.Add(new TextWriterTraceListener(logFile));
+AdalTrace.TraceSource.Switch.Level = SourceLevels.Information;
+```
+
+You can achieve the same result by adding the following lines to your application's config file:
+
+```
+  <system.diagnostics>
+    <trace autoflush="true"/>
+    <sources>
+      <source name="Microsoft.IdentityModel.Clients.ActiveDirectory" 
+        switchName="sourceSwitch" 
+        switchType="System.Diagnostics.SourceSwitch">
+        <listeners>
+          <add name="textListener" 
+            type="System.Diagnostics.TextWriterTraceListener" 
+            initializeData="logFile.txt"/>
+          <remove name="Default" />
+        </listeners>
+      </source>
+    </sources>    
+    <switches>
+      <add name="sourceSwitch" value="Information"/>
+    </switches>
+  </system.diagnostics>
+``` 
+
+#### Windows Store and Windows Phone Applications
+
+Tracing in ADAL for Windows Store and Windows Phone is done via an instance of class `System.Diagnostics.Tracing.EventSource` with name **"Microsoft.IdentityModel.Clients.ActiveDirectory"**. You can define your own ```EventListener```, connect it to the event source and set your desired trace level. Here is an example:
+```
+var eventListener = new SampleEventListener();
+
+class SampleEventListener : EventListener
+{
+    protected override void OnEventSourceCreated(EventSource eventSource)
+    {
+        if (eventSource.Name == "Microsoft.IdentityModel.Clients.ActiveDirectory")
+        {
+            this.EnableEvents(eventSource, EventLevel.Verbose);
+        }
+    }
+
+    protected override void OnEventWritten(EventWrittenEventArgs eventData)
+    {
+	    ...
+    }
+}
+
+```
+
+There is also a default event listener which writes logs to a local file named **"AdalTraces.log"**. You can control the level of tracing to that event listener using the property ```AdalTrace.Level```. By default, trace level for this event listener is set to "None" and to enable tracing to this particular listener, you need to set the above property. This is an example:
+
+```
+AdalTrace.Level = AdalTraceLevel.Informational;
+```
+
+### Network Traces
+
+You can use various tools to capture the HTTP traffic that ADAL generates.  This is most useful if you are familiar with the OAuth protocol or if you need to provide diagnostic information to Microsoft or other support channels.
+
+Fiddler is the easiest HTTP tracing tool.  Use the following links to setup it up to correctly record ADAL network traffic.  In order to be useful it is necessary to configure fiddler to record unencrypted SSL traffic.  
+
+NOTE: Traces generated in this way may contain highly privileged information such as access tokens, usernames and passwords.  If you are using production accounts, do not share these traces with 3rd parties.  If you need to supply a trace to someone in order to get support, reproduce the issue with a temporary account with usernames and passwords that you don't mind sharing.
+
 ## Community Help and Support
 
 We leverage [Stack Overflow](http://stackoverflow.com/) to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browser existing issues to see if someone has had your question before. 
@@ -19,7 +139,7 @@ We recommend you use the "adal" tag so we can see it! Here is the latest Q&A on
 
 ## Contributing
 
-All code is licensed under the Apache 2.0 license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now. 
+All code is licensed under the Apache 2.0 license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now, but check [this document](./contributing.md) first.
 
 
 ## Projects in this repo
@@ -39,8 +159,6 @@ All code is licensed under the Apache 2.0 license and we triage actively on GitH
 ### ADAL.WinPhone
 
 * This project contains the source of ADAL for Windows Phone. ADAL for Windows Phone is packaged as a Windows Runtime Component (.winmd).
-=======
-* This project (under /WinPhone) contains the source of ADAL for Windows Phone 8.1. ADAL for Windows Phone 8.1  is packaged as a Windows Runtime Component. The same /WinPhone folder contains its own tests.
 
 ### Test.ADAL.NET
 

diff --git a/src/ADAL.Common/AcquireTokenForMSAHandler.cs b/src/ADAL.Common/AcquireTokenForMSAHandler.cs
diff --git a/src/ADAL.Common/AcquireTokenHandlerBase.cs b/src/ADAL.Common/AcquireTokenHandlerBase.cs
@@ -33,7 +33,7 @@ protected AcquireTokenHandlerBase(Authenticator authenticator, TokenCache tokenC
         {
             this.Authenticator = authenticator;
             this.CallState = CreateCallState(this.Authenticator.CorrelationId, callSync);
-            Logger.Verbose(this.CallState, 
+            Logger.Information(this.CallState, 
                 string.Format("=== Token Acquisition started:\n\tAuthority: {0}\n\tResource: {1}\n\tClientId: {2}\n\tCacheType: {3}\n\tAuthentication Target: {4}\n\t",
                 authenticator.Authority, resource, clientKey.ClientId,
                 (tokenCache != null) ? tokenCache.GetType().FullName + string.Format(" ({0} items)", tokenCache.Count) : "null",
@@ -44,7 +44,7 @@ protected AcquireTokenHandlerBase(Authenticator authenticator, TokenCache tokenC
             if (string.IsNullOrWhiteSpace(resource))
             {
                 var ex = new ArgumentNullException("resource");
-                Logger.LogException(this.CallState, ex);
+                Logger.Error(this.CallState, ex);
                 throw ex;
             }
 
@@ -127,7 +127,7 @@ public async Task<AuthenticationResult> RunAsync()
             }
             catch (Exception ex)
             {
-                Logger.LogException(this.CallState, ex);
+                Logger.Error(this.CallState, ex);
                 throw;
             }
             finally
@@ -217,6 +217,7 @@ private async Task<AuthenticationResult> RefreshAccessTokenAsync(AuthenticationR
                         throw new AdalServiceException(
                             AdalError.FailedToRefreshToken,
                             AdalErrorMessage.FailedToRefreshToken + ". " + serviceException.Message,
+                            serviceException.ServiceErrorCodes,
                             (WebException)serviceException.InnerException);
                     }
 
@@ -275,17 +276,16 @@ private void LogReturnedToken(AuthenticationResult result)
                     refreshTokenHash = "[No Refresh Token]";
                 }
 
-                Logger.Verbose(this.CallState, "=== Token Acquisition finished successfully. An access token was retuned:\n\tAccess Token Hash: {0}\n\tRefresh Token Hash: {1}\n\tExpiration Time: {2}\n\tUser: {3}\n\t",
+                Logger.Information(this.CallState, "=== Token Acquisition finished successfully. An access token was retuned:\n\tAccess Token Hash: {0}\n\tRefresh Token Hash: {1}\n\tExpiration Time: {2}\n\tUser Hash: {3}\n\t",
                     accessTokenHash, refreshTokenHash, result.ExpiresOn, 
-                    (result.UserInfo != null) ? string.Format("{0} ({1})", result.UserInfo.UniqueId, result.UserInfo.DisplayableId) : "null");
+                    result.UserInfo != null ? PlatformSpecificHelper.CreateSha256Hash(result.UserInfo.UniqueId) : "null");
             }
         }
 
         private void ValidateAuthorityType()
         {
             if (!this.SupportADFS && this.Authenticator.AuthorityType == AuthorityType.ADFS)
             {
-                Logger.Error(this.CallState, "Invalid authority type '{0}'", this.Authenticator.AuthorityType);
                 throw new AdalException(AdalError.InvalidAuthorityType,
                     string.Format(CultureInfo.InvariantCulture, AdalErrorMessage.InvalidAuthorityTypeTemplate, this.Authenticator.Authority));
             }