From 70fae47aa70f75c6d06862f9e8275ba37741a66d Mon Sep 17 00:00:00 2001 From: Albireo Date: Tue, 14 Jul 2015 21:33:09 +0200 Subject: [PATCH] Fill XML documentation (part 2) --- .../Imgur/ImgurAuthenticationDefaults.cs | 60 ++++++------ .../Imgur/ImgurAuthenticationHandler.cs | 95 ++++++++++--------- .../Imgur/ImgurAuthenticationMiddleware.cs | 46 ++++----- 3 files changed, 102 insertions(+), 99 deletions(-) diff --git a/Owin.Security.Providers/Imgur/ImgurAuthenticationDefaults.cs b/Owin.Security.Providers/Imgur/ImgurAuthenticationDefaults.cs index b585d8a7..8aaa4bac 100644 --- a/Owin.Security.Providers/Imgur/ImgurAuthenticationDefaults.cs +++ b/Owin.Security.Providers/Imgur/ImgurAuthenticationDefaults.cs @@ -1,87 +1,87 @@ namespace Owin.Security.Providers.Imgur { - /// + /// Configuration strings for the imgur provider. internal static class ImgurAuthenticationDefaults { - /// + /// The error message for user authentication failure. internal const string AccessDeniedErrorMessage = "access_denied"; - /// + /// The name of the access token property in the imgur authentication response. internal const string AccessTokenPropertyName = "access_token"; - /// + /// The name of the account id property in the imgur authentication response. internal const string AccountIdPropertyName = "account_id"; - /// + /// The name of the account username property in the imgur authentication response. internal const string AccountUsernamePropertyName = "account_username"; - /// + /// The name of the provider. internal const string AuthenticationType = "Imgur"; - /// + /// The grant type to be used. internal const string AuthorizationCodeGrantType = "authorization_code"; - /// - internal const string AuthorizationUri = "https://api.imgur.com/oauth2/authorize"; + /// The user authorization endpoint URL. + internal const string AuthorizationUrl = "https://api.imgur.com/oauth2/authorize"; - /// + /// The default callback path. internal const string CallbackPath = "/signin-imgur"; - /// + /// The name of the application client id parameter. internal const string ClientIdParameter = "client_id"; - /// + /// The name of the application client secret parameter. internal const string ClientSecretParameter = "client_secret"; - /// + /// The name of the response code parameter. internal const string CodeParameter = "code"; - /// + /// The code type of the authentication response. internal const string CodeResponseType = "code"; - /// + /// The message for the communication failure error. internal const string CommunicationFailureMessage = "An error occurred while talking with imgur's server."; - /// + /// The message for the authentication response deserialization failure error. internal const string DeserializationFailureMessage = "The deserialization of the imgur's response failed. Perhaps imgur changed the response format?"; - /// + /// The name of the error parameter. internal const string ErrorParameter = "error"; - /// + /// The name of the access token duration property in the imgur authentication response. internal const string ExpiresInPropertyName = "expires_in"; - /// + /// The name of the grant type parameter. internal const string GrantTypeParameter = "grant_type"; - /// + /// The format to use to stringify s. internal const string Int32Format = "D"; - /// + /// The message for the invalid authentication ticket error. internal const string InvalidAuthenticationTicketMessage = "Invalid authentication ticket."; - /// + /// The name of the refresh token property in the imgur authentication response. internal const string RefreshInPropertyName = "refresh_token"; - /// + /// The name of the response type parameter. internal const string ResponseTypeParameter = "response_type"; - /// + /// The name of the scope property in the imgur authentication response. internal const string ScopePropertyName = "scope"; - /// + /// The name of the state parameter. internal const string StateParameter = "state"; - /// + /// The name of the token type property in the imgur authentication response. internal const string TokenTypePropertyName = "token_type"; - /// - internal const string TokenUri = "https://api.imgur.com/oauth2/token"; + /// The token exchange endpoint URL. + internal const string TokenUrl = "https://api.imgur.com/oauth2/token"; - /// + /// The version of the provider. internal const string Version = "v1"; - /// + /// The string value type for s. internal const string XmlSchemaString = "http://www.w3.org/2001/XMLSchema#string"; } } diff --git a/Owin.Security.Providers/Imgur/ImgurAuthenticationHandler.cs b/Owin.Security.Providers/Imgur/ImgurAuthenticationHandler.cs index 62b78341..dd9f2897 100644 --- a/Owin.Security.Providers/Imgur/ImgurAuthenticationHandler.cs +++ b/Owin.Security.Providers/Imgur/ImgurAuthenticationHandler.cs @@ -12,6 +12,7 @@ using Microsoft.Owin.Logging; using Microsoft.Owin.Security; using Microsoft.Owin.Security.Infrastructure; + using Microsoft.Owin.Security.Provider; using Newtonsoft.Json; @@ -23,9 +24,9 @@ public class ImgurAuthenticationHandler : AuthenticationHandler - /// - /// + /// Creates a new . + /// The to be used for back channel calls. + /// The to be used by the . public ImgurAuthenticationHandler(HttpClient httpClient, ILogger logger) { if (httpClient == null) @@ -42,8 +43,8 @@ public ImgurAuthenticationHandler(HttpClient httpClient, ILogger logger) this.logger = logger; } - /// - /// + /// Is called once by common code after initialization. + /// Return true if the request is handled by this , returns false if the request should be passed to the next . public override async Task InvokeAsync() { if (!this.Options.CallbackPath.HasValue) @@ -83,8 +84,8 @@ public override async Task InvokeAsync() return context.IsRequestCompleted; } - /// - /// + /// Handles authentication challenges by intercepting 401 responses. + /// A representing the completed operation. protected override Task ApplyResponseChallengeAsync() { if (this.Response.StatusCode != 401) @@ -114,8 +115,9 @@ protected override Task ApplyResponseChallengeAsync() return Task.FromResult(null); } - /// - /// + /// The core authentication logic which must be provided by the . + /// The ticket data provided by the authentication logic. + /// Will be invoked at most once per request. Do not call directly, call the wrapping Authenticate method instead. protected override async Task AuthenticateCoreAsync() { if (this.Request.Query.Get(ImgurAuthenticationDefaults.ErrorParameter) != null) @@ -152,9 +154,9 @@ protected override async Task AuthenticateCoreAsync() return new AuthenticationTicket(context.Identity, context.Properties); } - /// - /// - /// + /// Gets the payload for the back channel authentication request. + /// The authorization code supplied by imgur. + /// The with the payload for the back channel authentication request. private HttpContent GetAuthenticationRequestContent(string code) { return @@ -179,12 +181,12 @@ private HttpContent GetAuthenticationRequestContent(string code) }); } - /// - /// - /// + /// Gets the from imgur. + /// The authorization code supplied by imgur. + /// The from imgur. private async Task GetAuthenticationResponseAsync(string code) { - using (var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, ImgurAuthenticationDefaults.TokenUri)) + using (var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, ImgurAuthenticationDefaults.TokenUrl)) { httpRequestMessage.Content = this.GetAuthenticationRequestContent(code); @@ -211,12 +213,12 @@ private async Task GetAuthenticationResponseAsync(string } } - /// - /// - /// + /// Gets the authorization URL for the back channel call. + /// The encrypted for the current authentication session. + /// The authorization URL for the back channel call. private string GetAuthorizationUri(string state) { - var authorizationUri = ImgurAuthenticationDefaults.AuthorizationUri; + var authorizationUri = ImgurAuthenticationDefaults.AuthorizationUrl; authorizationUri = WebUtilities.AddQueryString( @@ -239,9 +241,9 @@ private string GetAuthorizationUri(string state) return authorizationUri; } - /// - /// - /// + /// Gets the for the identity of the user. + /// The returned by imgur. + /// The for the identity of the user. private ClaimsIdentity GetIdentity(AuthenticationResponse authenticationResponse) { var identity = @@ -274,11 +276,11 @@ private ClaimsIdentity GetIdentity(AuthenticationResponse authenticationResponse return identity; } - /// - /// - /// - /// - /// + /// Gets the for the current authentication session. + /// The returned by imgur. + /// The for the identity of the user. + /// The for the current authentication session. + /// The for the current authentication session. private ImgurAuthenticatedContext GetImgurAuthenticatedContext(AuthenticationResponse authenticationResponse, ClaimsIdentity identity, AuthenticationProperties properties) { var context = new ImgurAuthenticatedContext(this.Context, this.Options); @@ -295,9 +297,9 @@ private ImgurAuthenticatedContext GetImgurAuthenticatedContext(AuthenticationRes return context; } - /// - /// - /// + /// Gets the for the current authentication session. + /// The for the current authentication session. + /// The for the current authentication session. private ImgurReturnEndpointContext GetImgurReturnEndpointContext(AuthenticationTicket ticket) { var context = new ImgurReturnEndpointContext(this.Context, ticket); @@ -307,9 +309,9 @@ private ImgurReturnEndpointContext GetImgurReturnEndpointContext(AuthenticationT return context; } - /// - /// - private void SignIn(ImgurReturnEndpointContext context) + /// Adds authentication information to the OWIN context to let the appropriate authenticate the user. + /// The for the current authentication session. + private void SignIn(ReturnEndpointContext context) { if (context.SignInAsAuthenticationType == null || context.Identity == null) { @@ -331,10 +333,10 @@ private void SignIn(ImgurReturnEndpointContext context) this.Context.Authentication.SignIn(context.Properties, identity); } - /// - /// - /// - private static string GetRedirectLocation(ImgurReturnEndpointContext context) + /// Gets the URL where the user should be redirect to. + /// The for the current authentication session. + /// The URL where the user should be redirect to. + private static string GetRedirectLocation(ReturnEndpointContext context) { var location = context.RedirectUri; @@ -346,37 +348,38 @@ private static string GetRedirectLocation(ImgurReturnEndpointContext context) ImgurAuthenticationDefaults.ErrorParameter, ImgurAuthenticationDefaults.AccessDeniedErrorMessage); } + return location; } - /// + /// Response payload returned by imgur with the information of the authenticated user. private class AuthenticationResponse { - /// + /// Gets or sets the access token for the authenticated user. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccessTokenPropertyName)] public string AccessToken { get; set; } - /// + /// Gets or sets the account id of the authenticated user. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccountIdPropertyName)] public int AccountId { get; set; } - /// + /// Gets or sets the account username of the authenticated user. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccountUsernamePropertyName)] public string AccountUsername { get; set; } - /// + /// Gets or sets the duration of the access token. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.ExpiresInPropertyName)] public int ExpiresIn { get; set; } - /// + /// Gets or sets the refresh token for the authenticated user. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.RefreshInPropertyName)] public string RefreshToken { get; set; } - /// + /// Gets or sets the scope of the access token. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.ScopePropertyName)] public string Scope { get; set; } - /// + /// Gets or sets the type of the access token. [JsonProperty(PropertyName = ImgurAuthenticationDefaults.TokenTypePropertyName)] public string TokenType { get; set; } } diff --git a/Owin.Security.Providers/Imgur/ImgurAuthenticationMiddleware.cs b/Owin.Security.Providers/Imgur/ImgurAuthenticationMiddleware.cs index 46df6f60..94c89f48 100644 --- a/Owin.Security.Providers/Imgur/ImgurAuthenticationMiddleware.cs +++ b/Owin.Security.Providers/Imgur/ImgurAuthenticationMiddleware.cs @@ -14,7 +14,7 @@ using Owin.Security.Providers.Imgur.Provider; using Owin.Security.Providers.Properties; - /// + /// OWIN authentication middleware for imgur. public class ImgurAuthenticationMiddleware : AuthenticationMiddleware { private readonly HttpClient httpClient; @@ -22,10 +22,10 @@ public class ImgurAuthenticationMiddleware : AuthenticationMiddleware - /// - /// - /// + /// Creates a new . + /// The next in the configuration chain. + /// The OWIN being configured. + /// The to be used to set up the . public ImgurAuthenticationMiddleware(OwinMiddleware next, IAppBuilder appBuilder, ImgurAuthenticationOptions options) : base(next, options) { @@ -51,17 +51,17 @@ public ImgurAuthenticationMiddleware(OwinMiddleware next, IAppBuilder appBuilder this.logger = appBuilder.CreateLogger(); } - /// - /// + /// Creates the to be used by the . + /// The to be used by the . protected override AuthenticationHandler CreateHandler() { return new ImgurAuthenticationHandler(this.httpClient, this.logger); } - /// - private void CheckClientSecret() + /// Checks that the imgur application client id has been set. + private void CheckClientId() { - if (!string.IsNullOrWhiteSpace(this.Options.ClientSecret)) + if (!string.IsNullOrWhiteSpace(this.Options.ClientId)) { return; } @@ -70,15 +70,15 @@ private void CheckClientSecret() string.Format( CultureInfo.InvariantCulture, Resources.Exception_OptionMustBeProvided, - "ClientSecret"); + "ClientId"); throw new ArgumentException(message, "options"); } - /// - private void CheckClientId() + /// Checks that the imgur application client secret has been set. + private void CheckClientSecret() { - if (!string.IsNullOrWhiteSpace(this.Options.ClientId)) + if (!string.IsNullOrWhiteSpace(this.Options.ClientSecret)) { return; } @@ -87,12 +87,12 @@ private void CheckClientId() string.Format( CultureInfo.InvariantCulture, Resources.Exception_OptionMustBeProvided, - "ClientId"); + "ClientSecret"); throw new ArgumentException(message, "options"); } - /// + /// Sets the provider to if it hasn't been set. private void SetProvider() { if (this.Options.Provider != null) @@ -103,8 +103,8 @@ private void SetProvider() this.Options.Provider = new ImgurAuthenticationProvider(); } - /// - /// + /// Sets the name authentication middleware responsible for signing in the user if it hasn't been set. + /// The OWIN being configured. private void SetSignInAsAuthenticationType(IAppBuilder appBuilder) { if (!string.IsNullOrWhiteSpace(this.Options.SignInAsAuthenticationType)) @@ -115,8 +115,8 @@ private void SetSignInAsAuthenticationType(IAppBuilder appBuilder) this.Options.SignInAsAuthenticationType = appBuilder.GetDefaultSignInAsAuthenticationType(); } - /// - /// + /// Sets the data protector to if it hasn't been set. + /// The OWIN being configured. private void SetStateDataFormat(IAppBuilder appBuilder) { if (this.Options.StateDataFormat != null) @@ -133,9 +133,9 @@ private void SetStateDataFormat(IAppBuilder appBuilder) this.Options.StateDataFormat = new PropertiesDataFormat(dataProtector); } - /// - /// - /// + /// Gets the to be used for the back channel calls. + /// The used to configure the . + /// The to be used for the back channel calls. private static HttpMessageHandler ResolveHttpMessageHandler(ImgurAuthenticationOptions options) { var httpMessageHandler = options.BackchannelHttpHandler ?? new WebRequestHandler();