Merge pull request #74 from auth0/semantic-cleanup

Semantic cleanup

src/Auth0.OidcClient.Android/ActivityMediator.cs

@@ -1,11 +1,16 @@
 namespace Auth0.OidcClient
 {
+    /// <summary>
+    /// Facilitates communication between the app entry point and the callback function.
+    /// </summary>
     public class ActivityMediator
     {
         private static ActivityMediator _instance;
-
         private ActivityMediator() { }
 
+        /// <summary>
+        /// Singleton instance of this class.
+        /// </summary>
         public static ActivityMediator Instance
         {
             get { return _instance ?? (_instance = new ActivityMediator()); }
@@ -14,11 +19,18 @@ public static ActivityMediator Instance
         public delegate void MessageReceivedEventHandler(string message);
         public event MessageReceivedEventHandler ActivityMessageReceived;
 
+        /// <summary>
+        /// Send a response message to all listeners.
+        /// </summary>
+        /// <param name="response">Response message to send to all listeners.</param>
         public void Send(string response)
         {
             ActivityMessageReceived?.Invoke(response);
         }
 
+        /// <summary>
+        /// Send a cancellation response message "UserCancel" to all listeners.
+        /// </summary>
         public void Cancel()
         {
             Send("UserCancel");

src/Auth0.OidcClient.Android/AndroidWebViewBase.cs → src/Auth0.OidcClient.Android/AndroidBrowserBase.cs

@@ -4,8 +4,12 @@
 
 namespace Auth0.OidcClient
 {
-    public abstract class AndroidWebViewBase : IBrowser
+    /// <summary>
+    /// Provides common IBrowser logic for Android.
+    /// </summary>
+    public abstract class AndroidBrowserBase : IBrowser
     {
+        /// <inheritdoc/>
         public Task<BrowserResult> InvokeAsync(BrowserOptions options)
         {
             if (string.IsNullOrWhiteSpace(options.StartUrl))
@@ -30,11 +34,15 @@ void Callback(string response)
 
             ActivityMediator.Instance.ActivityMessageReceived += Callback;
 
-            LaunchBrowser(Android.Net.Uri.Parse(options.StartUrl));
+            OpenBrowser(Android.Net.Uri.Parse(options.StartUrl));
 
             return tcs.Task;
         }
 
-        protected abstract void LaunchBrowser(Android.Net.Uri uri);
+        /// <summary>
+        /// Open a web browser with the given uri.
+        /// </summary>
+        /// <param name="uri">The uri address to open in the browser.</param>
+        protected abstract void OpenBrowser(Android.Net.Uri uri);
     }
 }

src/Auth0.OidcClient.Android/Auth0.OidcClient.Android.csproj

@@ -47,7 +47,7 @@
   </ItemGroup>
   <ItemGroup>
     <Compile Include="ActivityMediator.cs" />
-    <Compile Include="AndroidWebViewBase.cs" />
+    <Compile Include="AndroidBrowserBase.cs" />
     <Compile Include="Auth0Client.cs" />
     <Compile Include="Auth0ClientActivity.cs" />
     <Compile Include="ChromeCustomTabsBrowser.cs" />

src/Auth0.OidcClient.Android/Auth0Client.cs

@@ -15,7 +15,7 @@ public class Auth0Client : Auth0ClientBase
         public Auth0Client(Auth0ClientOptions options)
             : base(options, "xamarin-android")
         {
-            options.Browser = options.Browser ?? new PlatformWebView();
+            options.Browser = options.Browser ?? new ChromeCustomTabsBrowser();
             var callbackUrl = $"{Context.PackageName}://{options.Domain}/android/{Context.PackageName}/callback".ToLower();
             options.RedirectUri = callbackUrl;
             options.PostLogoutRedirectUri = options.PostLogoutRedirectUri ?? callbackUrl;

src/Auth0.OidcClient.Android/Auth0ClientActivity.cs

@@ -3,6 +3,10 @@
 
 namespace Auth0.OidcClient
 {
+    /// <summary>
+    /// Base class for automatically wiring up the necessary callback hooks required
+    /// to facilitate communication with the Browser implementations.
+    /// </summary>
     public class Auth0ClientActivity : Activity
     {
         protected override void OnResume()

src/Auth0.OidcClient.Android/ChromeCustomTabsBrowser.cs

@@ -4,14 +4,19 @@
 
 namespace Auth0.OidcClient
 {
-    public class ChromeCustomTabsBrowser : AndroidWebViewBase
+    /// <summary>
+    /// Implements browser integration using Chrome Custom Tabs.
+    /// </summary>
+    public class ChromeCustomTabsBrowser : AndroidBrowserBase
     {
-        protected override void LaunchBrowser(Android.Net.Uri uri)
+        protected override void OpenBrowser(Android.Net.Uri uri)
         {
-            var builder = new CustomTabsIntent.Builder();
-            var customTabsIntent = builder.Build();
-            customTabsIntent.Intent.AddFlags(ActivityFlags.NoHistory);
-            customTabsIntent.LaunchUrl(Application.Context, uri);
+            using (var builder = new CustomTabsIntent.Builder())
+            using (var customTabsIntent = builder.Build())
+            {
+                customTabsIntent.Intent.AddFlags(ActivityFlags.NoHistory);
+                customTabsIntent.LaunchUrl(Application.Context, uri);
+            }
         }
     }
 }

src/Auth0.OidcClient.Android/PlatformWebView.cs

@@ -1,10 +1,9 @@
-namespace Auth0.OidcClient
+using System;
+
+namespace Auth0.OidcClient
 {
-    /// <summary>
-    /// PlatformWebView offers the best platform-specific web view implementation
-    /// at a given time. On Android that is the Chrome Custom Tabs at this time.
-    /// </summary>
-    public class PlatformWebView : ChromeCustomTabsBrowser
+    [Obsolete("It is recommended you leave Browser unassigned to accept the library default of ChromeCustomTabsBrowser.")]
+    public class PlatformWebView : SystemBrowser
     {
     }
 }

src/Auth0.OidcClient.Android/SystemBrowser.cs

@@ -3,9 +3,12 @@
 
 namespace Auth0.OidcClient
 {
-    public class SystemBrowser : AndroidWebViewBase
+    /// <summary>
+    /// Implements browser integration using the a regular web browser.
+    /// </summary>
+    public class SystemBrowser : AndroidBrowserBase
     {
-        protected override void LaunchBrowser(Android.Net.Uri uri)
+        protected override void OpenBrowser(Android.Net.Uri uri)
         {
             var intent = new Intent(Intent.ActionView, uri);
             intent.AddFlags(ActivityFlags.NoHistory)

src/Auth0.OidcClient.Core/Auth0ClientOptions.cs

@@ -1,6 +1,5 @@
-using System;
+using IdentityModel.OidcClient.Browser;
 using System.Net.Http;
-using IdentityModel.OidcClient.Browser;
 
 namespace Auth0.OidcClient
 {
@@ -10,7 +9,8 @@ namespace Auth0.OidcClient
     public class Auth0ClientOptions
     {
         /// <summary>
-        /// The <see cref="IBrowser"/> implementation which is responsible for displaying the Auth0 Login screen
+        /// The <see cref="IBrowser"/> implementation responsible for displaying the Auth0 Login screen. Leave this
+        /// unassigned to accept the recommended implementation for platform.
         /// </summary>
         public IBrowser Browser { get; set; }
 
@@ -33,11 +33,11 @@ public class Auth0ClientOptions
         public string Domain { get; set; }
 
         /// <summary>
-        /// Indicates whether telemetry information should be sent to Auth0.
+        /// Indicates whether basic telemetry information should be included with requests to Auth0.
         /// </summary>
         /// <remarks>
-        /// Telemetry simply contains information about the version of the Auth0 OIDC Client being used. No information about your
-        /// application or users are being sent to Auth0.
+        /// The telemetry information is like a browser user agent and includes operating system
+        /// details only to let Auth0 guide engineering resources based on platform popularity.
         /// </remarks>
         public bool EnableTelemetry { get; set; }
 
@@ -55,7 +55,7 @@ public class Auth0ClientOptions
         public string Scope { get; set; }
 
         /// <summary>
-        /// Allow overriding the RetryMessageHandler
+        /// Allow overriding the RetryMessageHandler.
         /// </summary>
         /// <example>
         /// var handler = new HttpClientHandler();
@@ -67,7 +67,7 @@ public class Auth0ClientOptions
         public HttpMessageHandler RefreshTokenMessageHandler { get; set; }
 
         /// <summary>
-        /// Allow overriding the BackchannelHandler
+        /// Allow overriding the BackchannelHandler.
         /// </summary>
         /// <example>
         /// var handler = new HttpClientHandler();
@@ -79,15 +79,15 @@ public class Auth0ClientOptions
         public HttpMessageHandler BackchannelHandler { get; set; }
 
         /// <summary>
-        /// Allow overriding of the Post Logout Redirect URI
+        /// Override the Redirect URI used to return from logout.
         /// </summary>
         /// <remarks>
-        /// This should only be done in exceptional circumstances
+        /// This should only be done in exceptional circumstances.
         /// </remarks>
         public string PostLogoutRedirectUri { get; set; }
 
 		/// <summary>
-		/// Allow overriding of the Redirect URI
+		/// Override the the Redirect URI used to return from login.
 		/// </summary>
 		/// <remarks>
 		/// This should only be done in exceptional circumstances

src/Auth0.OidcClient.Core/IAuth0Client.cs

@@ -72,7 +72,7 @@ public interface IAuth0Client
         /// </summary>
         /// <param name="accessToken">The access token.</param>
         /// <returns>
-        /// User claims
+        /// <returns>A <see cref="UserInfoResult"/> with the user information and claims.</returns>
         /// </returns>
         /// <exception cref="ArgumentNullException">accessToken</exception>
         /// <exception cref="InvalidOperationException">No userinfo endpoint specified</exception>

src/Auth0.OidcClient.UWP/Auth0.OidcClient.UWP.csproj

@@ -110,6 +110,7 @@
   </ItemGroup>
   <ItemGroup>
     <Compile Include="Auth0Client.cs" />
+    <Compile Include="WebAuthenticationBrokerBrowser.cs" />
     <Compile Include="PlatformWebView.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <EmbeddedResource Include="Properties\Auth0.OidcClient.UWP.rd.xml" />

src/Auth0.OidcClient.UWP/PlatformWebView.cs

@@ -1,114 +1,13 @@
-using IdentityModel.OidcClient.Browser;
-using System;
-using System.Threading.Tasks;
-using Windows.Security.Authentication.Web;
+using System;
 
 namespace Auth0.OidcClient
 {
-    public class PlatformWebView : IBrowser
+    [Obsolete("It is recommended you leave Browser unassigned to accept the library default or assign an instance of WebAuthenticationBrokerBrowser if you need to enable Windows authentication.")]
+    public class PlatformWebView : WebAuthenticationBrokerBrowser
     {
-        private readonly bool _enableWindowsAuthentication;
-
         public PlatformWebView(bool enableWindowsAuthentication = false)
+            : base(enableWindowsAuthentication)
         {
-            _enableWindowsAuthentication = enableWindowsAuthentication;
-        }
-
-        public async Task<BrowserResult> InvokeAsync(BrowserOptions options)
-        {
-            if (string.IsNullOrWhiteSpace(options.StartUrl)) throw new ArgumentException("Missing StartUrl", nameof(options));
-
-            var startUri = new Uri(options.StartUrl);
-            if (startUri.AbsolutePath.StartsWith("/v2/logout", StringComparison.OrdinalIgnoreCase))
-                return await InvokeLogoutAsync(startUri);
-
-            try
-            {
-                var authOptions = ConfigureWebAuthOptions(options.DisplayMode);
-                var authResult = await WebAuthenticationBroker.AuthenticateAsync(authOptions, startUri, new Uri(options.EndUrl));
-                return CreateBrowserResult(authResult);
-            }
-            catch (Exception ex)
-            {
-                return new BrowserResult
-                {
-                    ResultType = BrowserResultType.UnknownError,
-                    Error = ex.ToString()
-                };
-            }
-        }
-
-        private async Task<BrowserResult> InvokeLogoutAsync(Uri logoutUri)
-        {
-            try
-            {
-                await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.SilentMode, logoutUri);
-            }
-            catch
-            {
-            }
-
-            return new BrowserResult
-            {
-                ResultType = BrowserResultType.Success,
-                Response = String.Empty
-            };
-        }
-
-        private static BrowserResult CreateBrowserResult(WebAuthenticationResult authResult)
-        {
-            switch (authResult.ResponseStatus)
-            {
-                case WebAuthenticationStatus.Success:
-                    return new BrowserResult
-                    {
-                        ResultType = BrowserResultType.Success,
-                        // Windows IoT Core adds a \0 char at the end of the ResponseData
-                        // when doing response_mode=form_post, so we remove it here
-                        // to avoid breaking the response processor.
-                        Response = authResult.ResponseData?.Replace("\0", string.Empty)
-                    };
-
-                case WebAuthenticationStatus.ErrorHttp:
-                    return new BrowserResult
-                    {
-                        ResultType = BrowserResultType.HttpError,
-                        Error = authResult.ResponseErrorDetail.ToString()
-                    };
-
-                case WebAuthenticationStatus.UserCancel:
-                    return new BrowserResult
-                    {
-                        ResultType = BrowserResultType.UserCancel
-                    };
-
-                default:
-                    return new BrowserResult
-                    {
-                        ResultType = BrowserResultType.UnknownError,
-                        Error = "Invalid response from WebAuthenticationBroker"
-                    };
-            }
-        }
-
-        private WebAuthenticationOptions ConfigureWebAuthOptions(DisplayMode mode)
-        {
-            var options = WebAuthenticationOptions.None;
-
-            if (_enableWindowsAuthentication)
-                options |= WebAuthenticationOptions.UseCorporateNetwork;
-
-            switch (mode)
-            {
-                case DisplayMode.Visible:
-                    return options;
-
-                case DisplayMode.Hidden:
-                    return options | WebAuthenticationOptions.SilentMode;
-
-                default:
-                    throw new ArgumentException("Invalid DisplayMode", nameof(options));
-            }
         }
     }
 }