Merge pull request #79 from owin-middleware/foursquare-improvements

Foursquare improvements

Owin.Security.Providers/Foursquare/FoursquareAuthenticationHandler.cs

@@ -20,6 +20,8 @@ namespace Owin.Security.Providers.Foursquare
         private const string GraphApiEndpoint = "https://api.foursquare.com/v2/users/self";
         private const string XmlSchemaString = "http://www.w3.org/2001/XMLSchema#string";
 
+        private static readonly DateTime VersionDate = new DateTime(2015, 3, 19);
+
         private readonly ILogger _logger;
         private readonly HttpClient _httpClient;
 
@@ -103,7 +105,7 @@ namespace Owin.Security.Providers.Foursquare
                     return new AuthenticationTicket(null, properties);
                 }
 
-                var graphResponse = await this._httpClient.GetAsync(GraphApiEndpoint + "?oauth_token=" + Uri.EscapeDataString(accessToken) + "&m=foursquare&v=" + DateTime.Today.ToString("yyyyyMMdd"), this.Request.CallCancelled);
+                var graphResponse = await this._httpClient.GetAsync(GraphApiEndpoint + "?oauth_token=" + Uri.EscapeDataString(accessToken) + "&m=foursquare&v=" + VersionDate.ToString("yyyyyMMdd"), this.Request.CallCancelled);
                 graphResponse.EnsureSuccessStatusCode();
 
                 var accountstring = await graphResponse.Content.ReadAsStringAsync();
@@ -174,17 +176,13 @@ namespace Owin.Security.Providers.Foursquare
                 // OAuth2 10.12 CSRF
                 this.GenerateCorrelationId(extra);
 
-                // OAuth2 3.3 space separated
-                var scope = string.Join(" ", this.Options.Scope);
-
                 var state = this.Options.StateDataFormat.Protect(extra);
 
                 var authorizationEndpoint = AuthorizationEndpoint +
                         "?client_id=" + Uri.EscapeDataString(this.Options.ClientId) +
                         "&response_type=code" +
                         "&redirect_uri=" + Uri.EscapeDataString(redirectUri) +
-                        "&state=" + Uri.EscapeDataString(state) +
-                        "&scope=" + Uri.EscapeDataString(scope);
+                        "&state=" + Uri.EscapeDataString(state);
 
                 this.Response.Redirect(authorizationEndpoint);
             }

Owin.Security.Providers/Foursquare/FoursquareAuthenticationMiddleware.cs

@@ -51,6 +51,14 @@ namespace Owin.Security.Providers.Foursquare
             this._httpClient.MaxResponseContentBufferSize = 1024 * 1024 * 10; // 10 MB
         }
 
+        /// <summary>
+        ///     Provides the <see cref="T:Microsoft.Owin.Security.Infrastructure.AuthenticationHandler" /> object for processing
+        ///     authentication-related requests.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="T:Microsoft.Owin.Security.Infrastructure.AuthenticationHandler" /> configured with the
+        ///     <see cref="T:Owin.Security.Providers.Foursquare.FoursquareAuthenticationOptions" /> supplied to the constructor.
+        /// </returns>
         protected override AuthenticationHandler<FoursquareAuthenticationOptions> CreateHandler()
         {
             return new FoursquareAuthenticationHandler(this._httpClient, this._logger);

Owin.Security.Providers/Foursquare/FoursquareAuthenticationOptions.cs

@@ -18,7 +18,6 @@ namespace Owin.Security.Providers.Foursquare
             this.CallbackPath = "/signin-foursquare";
             this.AuthenticationMode = AuthenticationMode.Passive;
             this.BackchannelTimeout = TimeSpan.FromSeconds(60);
-            this.Scope = new List<String>();
         }
 
         /// <summary>
@@ -82,11 +81,6 @@ namespace Owin.Security.Providers.Foursquare
         /// </summary>
         public ISecureDataFormat<AuthenticationProperties> StateDataFormat { get; set; }
 
-        /// <summary>
-        /// A list of permissions to request.
-        /// </summary>
-        public IList<string> Scope { get; private set; }
-
         /// <summary>
         ///     Get or sets the text that the user can display on a sign in user interface.
         /// </summary>

Owin.Security.Providers/Foursquare/Provider/FoursquareAuthenticatedContext.cs

@@ -7,8 +7,17 @@ using Newtonsoft.Json.Linq;
 
 namespace Owin.Security.Providers.Foursquare.Provider
 {
+    /// <summary>
+    /// Contains information about the login session as well as the user <see cref="System.Security.Claims.ClaimsIdentity"/>.
+    /// </summary>
     public class FoursquareAuthenticatedContext : BaseContext
     {
+        /// <summary>
+        /// Initializes a <see cref="FoursquareAuthenticatedContext"/>
+        /// </summary>
+        /// <param name="context">The OWIN environment</param>
+        /// <param name="user">The JSON-serialized user</param>
+        /// <param name="accessToken">Foursquare Access token</param>
         public FoursquareAuthenticatedContext(IOwinContext context, JObject user, string accessToken)
             : base(context)
         {
@@ -32,15 +41,15 @@ namespace Owin.Security.Providers.Foursquare.Provider
             this.LastName = TryGetValue(user, "lastName");
             this.Name = this.FirstName + " " + this.LastName;
             this.Gender = TryGetValue(user, "gender");
-            this.Photo = TryGetValue(user, "photo");
+            this.Photo = (JObject)user["photo"];
             this.Friends = TryGetValue(user, "friends");
             this.HomeCity = TryGetValue(user, "homeCity");
             this.Bio = TryGetValue(user, "bio");
-            this.Contact = TryGetValue(user, "contact");
-            this.Phone = TryGetValue(JObject.Parse(this.Contact), "phone");
-            this.Email = TryGetValue(JObject.Parse(this.Contact), "email");
-            this.Twitter = TryGetValue(JObject.Parse(this.Contact), "twitter");
-            this.Facebook = TryGetValue(JObject.Parse(this.Contact), "facebook");
+            this.Contact = (JObject)user["contact"];
+            this.Phone = TryGetValue(Contact, "phone");
+            this.Email = TryGetValue(Contact, "email");
+            this.Twitter = TryGetValue(Contact, "twitter");
+            this.Facebook = TryGetValue(Contact, "facebook");
             this.Badges = TryGetValue(user, "badges");
             this.Mayorships = TryGetValue(user, "mayorships");
             this.Checkins = TryGetValue(user, "checkins");
@@ -49,29 +58,104 @@ namespace Owin.Security.Providers.Foursquare.Provider
             this.Link = "https://foursquare.com/user/" + this.Id;
         }
 
+        /// <summary>
+        /// Gets the JSON-serialized user
+        /// </summary>
+        /// <remarks>
+        /// Contains the Foursquare user obtained from the User Info endpoint https://api.foursquare.com/v2/users/self
+        /// </remarks>
         public JObject User { get; private set; }
+        /// <summary>
+        /// Gets the Foursquare access token
+        /// </summary>
         public string AccessToken { get; private set; }
+        /// <summary>
+        /// Gets the Foursquare user ID
+        /// </summary>
         public string Id { get; private set; }
+        /// <summary>
+        /// Gets the user's first name
+        /// </summary>
         public string FirstName { get; private set; }
+        /// <summary>
+        /// Gets the user's last name
+        /// </summary>
         public string LastName { get; private set; }
+        /// <summary>
+        /// Gets the user's full name
+        /// </summary>
         public string Name { get; private set; }
+        /// <summary>
+        /// Gets the user's gender
+        /// </summary>
         public string Gender { get; private set; }
-        public string Photo { get; private set; }
+        /// <summary>
+        /// Gets the user's photo
+        /// </summary>
+        public JObject Photo { get; private set; }
+        /// <summary>
+        /// Gets the user's friends
+        /// </summary>
         public string Friends { get; private set; }
+        /// <summary>
+        /// Gets the user's home city
+        /// </summary>
         public string HomeCity { get; private set; }
+        /// <summary>
+        /// Gets the user's biography
+        /// </summary>
         public string Bio { get; private set; }
-        public string Contact { get; private set; }
+        /// <summary>
+        /// Gets the user's contact
+        /// </summary>
+        public JObject Contact { get; private set; }
+        /// <summary>
+        /// Gets the user's phone
+        /// </summary>
         public string Phone { get; private set; }
+        /// <summary>
+        /// Gets the user's email
+        /// </summary>
         public string Email { get; private set; }
+        /// <summary>
+        /// Gets the user's Twitter handle
+        /// </summary>
         public string Twitter { get; private set; }
+        /// <summary>
+        /// Gets the user's Facebook id
+        /// </summary>
         public string Facebook { get; private set; }
+        /// <summary>
+        /// Gets the user's badges
+        /// </summary>
         public string Badges { get; private set; }
+        /// <summary>
+        /// Gets the user's mayorships
+        /// </summary>
         public string Mayorships { get; private set; }
+        /// <summary>
+        /// Gets the user's checkins
+        /// </summary>
         public string Checkins { get; private set; }
+        /// <summary>
+        /// Gets the user's photos
+        /// </summary>
         public string Photos { get; private set; }
+        /// <summary>
+        /// Gets the user's scores
+        /// </summary>
         public string Scores { get; private set; }
+        /// <summary>
+        /// Gets the user's link
+        /// </summary>
         public string Link { get; private set; }
+        /// <summary>
+        /// Gets the <see cref="ClaimsIdentity"/> representing the user
+        /// </summary>
         public ClaimsIdentity Identity { get; set; }
+        /// <summary>
+        /// Gets or sets a property bag for common authentication properties
+        /// </summary>
         public AuthenticationProperties Properties { get; set; }
 
         private static string TryGetValue(JObject user, string propertyName)

Owin.Security.Providers/Foursquare/Provider/FoursquareAuthenticationProvider.cs

@@ -3,23 +3,45 @@ using System.Threading.Tasks;
 
 namespace Owin.Security.Providers.Foursquare.Provider
 {
+    /// <summary>
+    /// Default <see cref="IFoursquareAuthenticationProvider"/> implementation.
+    /// </summary>
     public class FoursquareAuthenticationProvider : IFoursquareAuthenticationProvider
     {
+        /// <summary>
+        /// Initializes a <see cref="FoursquareAuthenticationProvider"/>
+        /// </summary>
         public FoursquareAuthenticationProvider()
         {
             this.OnAuthenticated = context => Task.FromResult<object>(null);
             this.OnReturnEndpoint = context => Task.FromResult<object>(null);
         }
 
+        /// <summary>
+        /// Gets or sets the function that is invoked when the Authenticated method is invoked.
+        /// </summary>
         public Func<FoursquareAuthenticatedContext, Task> OnAuthenticated { get; set; }
 
+        /// <summary>
+        /// Gets or sets the function that is invoked when the ReturnEndpoint method is invoked.
+        /// </summary>
         public Func<FoursquareReturnEndpointContext, Task> OnReturnEndpoint { get; set; }
 
+        /// <summary>
+        /// Invoked whenever Foursquare succesfully authenticates a user
+        /// </summary>
+        /// <param name="context">Contains information about the login session as well as the user <see cref="System.Security.Claims.ClaimsIdentity"/>.</param>
+        /// <returns>A <see cref="Task"/> representing the completed operation.</returns>
         public virtual Task Authenticated(FoursquareAuthenticatedContext context)
         {
             return this.OnAuthenticated(context);
         }
 
+        /// <summary>
+        /// Invoked prior to the <see cref="System.Security.Claims.ClaimsIdentity"/> being saved in a local cookie and the browser being redirected to the originally requested URL.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns>A <see cref="Task"/> representing the completed operation.</returns>
         public virtual Task ReturnEndpoint(FoursquareReturnEndpointContext context)
         {
             return this.OnReturnEndpoint(context);

Owin.Security.Providers/Foursquare/Provider/FoursquareReturnEndpointContext.cs

@@ -4,6 +4,9 @@ using Microsoft.Owin.Security.Provider;
 
 namespace Owin.Security.Providers.Foursquare.Provider
 {
+    /// <summary>
+    /// Provides context information to middleware providers.
+    /// </summary>
     public class FoursquareReturnEndpointContext : ReturnEndpointContext
     {
         /// <summary>

Owin.Security.Providers/Foursquare/Provider/IFoursquareAuthenticationProvider.cs

@@ -2,10 +2,23 @@
 
 namespace Owin.Security.Providers.Foursquare.Provider
 {
+    /// <summary>
+    /// Specifies callback methods which the <see cref="FoursquareAuthenticationMiddleware"></see> invokes to enable developer control over the authentication process. />
+    /// </summary>
     public interface IFoursquareAuthenticationProvider
     {
+        /// <summary>
+        /// Invoked whenever Foursquare succesfully authenticates a user
+        /// </summary>
+        /// <param name="context">Contains information about the login session as well as the user <see cref="System.Security.Claims.ClaimsIdentity"/>.</param>
+        /// <returns>A <see cref="Task"/> representing the completed operation.</returns>
         Task Authenticated(FoursquareAuthenticatedContext context);
 
+        /// <summary>
+        /// Invoked prior to the <see cref="System.Security.Claims.ClaimsIdentity"/> being saved in a local cookie and the browser being redirected to the originally requested URL.
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns>A <see cref="Task"/> representing the completed operation.</returns>
         Task ReturnEndpoint(FoursquareReturnEndpointContext context);
     }
 }