diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs b/src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs index e6d56aa4fa..d102bf11ea 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs @@ -14,7 +14,8 @@ namespace Microsoft.AspNetCore.Authentication public static class AuthenticationHttpContextExtensions { /// - /// Extension method for authenticate using the scheme. + /// Authenticate the current request using the default authentication scheme. + /// The default authentication scheme can be configured using . /// /// The context. /// The . @@ -22,7 +23,7 @@ namespace Microsoft.AspNetCore.Authentication context.AuthenticateAsync(scheme: null); /// - /// Extension method for authenticate. + /// Authenticate the current request using the specified scheme. /// /// The context. /// The name of the authentication scheme. @@ -31,7 +32,8 @@ namespace Microsoft.AspNetCore.Authentication context.RequestServices.GetRequiredService().AuthenticateAsync(context, scheme); /// - /// Extension method for Challenge. + /// Challenge the current request using the specified scheme. + /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication. /// /// The context. /// The name of the authentication scheme. @@ -40,7 +42,9 @@ namespace Microsoft.AspNetCore.Authentication context.ChallengeAsync(scheme, properties: null); /// - /// Extension method for authenticate using the scheme. + /// Challenge the current request using the default challenge scheme. + /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication. + /// The default challenge scheme can be configured using . /// /// The context. /// The task. @@ -48,7 +52,9 @@ namespace Microsoft.AspNetCore.Authentication context.ChallengeAsync(scheme: null, properties: null); /// - /// Extension method for authenticate using the scheme. + /// Challenge the current request using the default challenge scheme. + /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication. + /// The default challenge scheme can be configured using . /// /// The context. /// The properties. @@ -57,7 +63,8 @@ namespace Microsoft.AspNetCore.Authentication context.ChallengeAsync(scheme: null, properties: properties); /// - /// Extension method for Challenge. + /// Challenge the current request using the specified scheme. + /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication. /// /// The context. /// The name of the authentication scheme. @@ -67,7 +74,8 @@ namespace Microsoft.AspNetCore.Authentication context.RequestServices.GetRequiredService().ChallengeAsync(context, scheme, properties); /// - /// Extension method for Forbid. + /// Forbid the current request using the specified scheme. + /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access. /// /// The context. /// The name of the authentication scheme. @@ -76,7 +84,9 @@ namespace Microsoft.AspNetCore.Authentication context.ForbidAsync(scheme, properties: null); /// - /// Extension method for Forbid using the scheme.. + /// Forbid the current request using the default forbid scheme. + /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access. + /// The default forbid scheme can be configured using . /// /// The context. /// The task. @@ -84,7 +94,9 @@ namespace Microsoft.AspNetCore.Authentication context.ForbidAsync(scheme: null, properties: null); /// - /// Extension method for Forbid. + /// Forbid the current request using the default forbid scheme. + /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access. + /// The default forbid scheme can be configured using . /// /// The context. /// The properties. @@ -93,7 +105,8 @@ namespace Microsoft.AspNetCore.Authentication context.ForbidAsync(scheme: null, properties: properties); /// - /// Extension method for Forbid. + /// Forbid the current request using the specified scheme. + /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access. /// /// The context. /// The name of the authentication scheme. @@ -103,7 +116,7 @@ namespace Microsoft.AspNetCore.Authentication context.RequestServices.GetRequiredService().ForbidAsync(context, scheme, properties); /// - /// Extension method for SignIn. + /// Sign in a principal for the specified scheme. /// /// The context. /// The name of the authentication scheme. @@ -113,7 +126,8 @@ namespace Microsoft.AspNetCore.Authentication context.SignInAsync(scheme, principal, properties: null); /// - /// Extension method for SignIn using the . + /// Sign in a principal for the default authentication scheme. + /// The default scheme for signing in can be configured using . /// /// The context. /// The user. @@ -122,7 +136,8 @@ namespace Microsoft.AspNetCore.Authentication context.SignInAsync(scheme: null, principal: principal, properties: null); /// - /// Extension method for SignIn using the . + /// Sign in a principal for the default authentication scheme. + /// The default scheme for signing in can be configured using . /// /// The context. /// The user. @@ -132,7 +147,7 @@ namespace Microsoft.AspNetCore.Authentication context.SignInAsync(scheme: null, principal: principal, properties: properties); /// - /// Extension method for SignIn. + /// Sign in a principal for the specified scheme. /// /// The context. /// The name of the authentication scheme. @@ -143,14 +158,16 @@ namespace Microsoft.AspNetCore.Authentication context.RequestServices.GetRequiredService().SignInAsync(context, scheme, principal, properties); /// - /// Extension method for SignOut using the . + /// Sign out a principal for the default authentication scheme. + /// The default scheme for signing out can be configured using . /// /// The context. /// The task. public static Task SignOutAsync(this HttpContext context) => context.SignOutAsync(scheme: null, properties: null); /// - /// Extension method for SignOut using the . + /// Sign out a principal for the default authentication scheme. + /// The default scheme for signing out can be configured using . /// /// The context. /// The properties. @@ -158,7 +175,7 @@ namespace Microsoft.AspNetCore.Authentication public static Task SignOutAsync(this HttpContext context, AuthenticationProperties? properties) => context.SignOutAsync(scheme: null, properties: properties); /// - /// Extension method for SignOut. + /// Sign out a principal for the specified scheme. /// /// The context. /// The name of the authentication scheme. @@ -166,7 +183,7 @@ namespace Microsoft.AspNetCore.Authentication public static Task SignOutAsync(this HttpContext context, string? scheme) => context.SignOutAsync(scheme, properties: null); /// - /// Extension method for SignOut. + /// Sign out a principal for the specified scheme. /// /// The context. /// The name of the authentication scheme. @@ -176,21 +193,22 @@ namespace Microsoft.AspNetCore.Authentication context.RequestServices.GetRequiredService().SignOutAsync(context, scheme, properties); /// - /// Extension method for getting the value of an authentication token. + /// Authenticates the request using the specified scheme and returns the value for the token. /// /// The context. /// The name of the authentication scheme. /// The name of the token. - /// The value of the token. + /// The value of the token if present. public static Task GetTokenAsync(this HttpContext context, string? scheme, string tokenName) => context.RequestServices.GetRequiredService().GetTokenAsync(context, scheme, tokenName); /// - /// Extension method for getting the value of an authentication token. + /// Authenticates the request using the default authentication scheme and returns the value for the token. + /// The default authentication scheme can be configured using . /// /// The context. /// The name of the token. - /// The value of the token. + /// The value of the token if present. public static Task GetTokenAsync(this HttpContext context, string tokenName) => context.RequestServices.GetRequiredService().GetTokenAsync(context, tokenName); } diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs b/src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs index d6648f90aa..2bf6327af0 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs @@ -9,6 +9,9 @@ using Microsoft.AspNetCore.Http; namespace Microsoft.AspNetCore.Authentication { + /// + /// Options to configure authentication. + /// public class AuthenticationOptions { private readonly IList _schemes = new List(); @@ -93,7 +96,8 @@ namespace Microsoft.AspNetCore.Authentication public string? DefaultForbidScheme { get; set; } /// - /// If true, SignIn should throw if attempted with a ClaimsPrincipal.Identity.IsAuthenticated = false. + /// If true, SignIn should throw if attempted with a user is not authenticated. + /// A user is considered authenticated if returns for the associated with the HTTP request. /// public bool RequireAuthenticatedSignIn { get; set; } = true; } diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs b/src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs index 3195bfe0ec..89768d6d53 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs @@ -3,7 +3,6 @@ using System; using System.Collections.Generic; -using System.Diagnostics.CodeAnalysis; using System.Globalization; namespace Microsoft.AspNetCore.Authentication @@ -122,10 +121,10 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Set a string value in the collection. + /// Set or remove a string value from the collection. /// /// Property key. - /// Value to set or null to remove the property. + /// Value to set or to remove the property. public void SetString(string key, string? value) { if (value != null) @@ -157,10 +156,10 @@ namespace Microsoft.AspNetCore.Authentication => Parameters[key] = value; /// - /// Get a bool value from the collection. + /// Get a nullable from the collection. /// /// Property key. - /// Retrieved value or null if the property is not set. + /// Retrieved value or if the property is not set. protected bool? GetBool(string key) { if (Items.TryGetValue(key, out var value) && bool.TryParse(value, out var boolValue)) @@ -171,10 +170,10 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Set a bool value in the collection. + /// Set or remove a value in the collection. /// /// Property key. - /// Value to set or null to remove the property. + /// Value to set or to remove the property. protected void SetBool(string key, bool? value) { if (value.HasValue) @@ -188,10 +187,10 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Get a DateTimeOffset value from the collection. + /// Get a nullable value from the collection. /// /// Property key. - /// Retrieved value or null if the property is not set. + /// Retrieved value or if the property is not set. protected DateTimeOffset? GetDateTimeOffset(string key) { if (Items.TryGetValue(key, out var value) @@ -203,10 +202,10 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Set a DateTimeOffset value in the collection. + /// Sets or removes a value in the collection. /// /// Property key. - /// Value to set or null to remove the property. + /// Value to set or to remove the property. protected void SetDateTimeOffset(string key, DateTimeOffset? value) { if (value.HasValue) diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs b/src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs index 2749c2daa2..4aaa864a74 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs @@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Authentication public class AuthenticationScheme { /// - /// Constructor. + /// Initializes a new instance of . /// /// The name for the authentication scheme. /// The display name for the authentication scheme. diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs b/src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs index aef5417376..0b36756b0c 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs @@ -21,17 +21,17 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// The name of the scheme being built. + /// Gets the name of the scheme being built. /// public string Name { get; } /// - /// The display name for the scheme being built. + /// Gets or sets the display name for the scheme being built. /// public string? DisplayName { get; set; } /// - /// The type responsible for this scheme. + /// Gets or sets the type responsible for this scheme. /// [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] public Type? HandlerType { get; set; } @@ -39,7 +39,7 @@ namespace Microsoft.AspNetCore.Authentication /// /// Builds the instance. /// - /// + /// The . public AuthenticationScheme Build() { if (HandlerType is null) diff --git a/src/Http/Authentication.Abstractions/src/AuthenticationTicket.cs b/src/Http/Authentication.Abstractions/src/AuthenticationTicket.cs index e756566855..11d0d327dc 100644 --- a/src/Http/Authentication.Abstractions/src/AuthenticationTicket.cs +++ b/src/Http/Authentication.Abstractions/src/AuthenticationTicket.cs @@ -16,7 +16,7 @@ namespace Microsoft.AspNetCore.Authentication /// /// the that represents the authenticated user. /// additional properties that can be consumed by the user or runtime. - /// the authentication middleware that was responsible for this ticket. + /// the authentication scheme that was responsible for this ticket. public AuthenticationTicket(ClaimsPrincipal principal, AuthenticationProperties? properties, string authenticationScheme) { if (principal == null) @@ -33,13 +33,13 @@ namespace Microsoft.AspNetCore.Authentication /// Initializes a new instance of the class /// /// the that represents the authenticated user. - /// the authentication middleware that was responsible for this ticket. + /// the authentication scheme that was responsible for this ticket. public AuthenticationTicket(ClaimsPrincipal principal, string authenticationScheme) : this(principal, properties: null, authenticationScheme: authenticationScheme) { } /// - /// Gets the authentication type. + /// Gets the authentication scheme that was responsible for this ticket. /// public string AuthenticationScheme { get; } @@ -55,8 +55,10 @@ namespace Microsoft.AspNetCore.Authentication /// /// Returns a copy of the ticket. - /// Note: the claims principal will be cloned by calling Clone() on each of the Identities. /// + /// + /// The method clones the by calling on each of the . + /// /// A copy of the ticket public AuthenticationTicket Clone() { diff --git a/src/Http/Authentication.Abstractions/src/IAuthenticationHandler.cs b/src/Http/Authentication.Abstractions/src/IAuthenticationHandler.cs index 8287274a8f..d34f2b512b 100644 --- a/src/Http/Authentication.Abstractions/src/IAuthenticationHandler.cs +++ b/src/Http/Authentication.Abstractions/src/IAuthenticationHandler.cs @@ -12,31 +12,28 @@ namespace Microsoft.AspNetCore.Authentication public interface IAuthenticationHandler { /// - /// The handler should initialize anything it needs from the request and scheme here. + /// Initialize the authentication handler. The handler should initialize anything it needs from the request and scheme as part of this method. /// /// The scheme. /// The context. - /// Task InitializeAsync(AuthenticationScheme scheme, HttpContext context); /// - /// Authentication behavior. + /// Authenticate the current request. /// /// The result. Task AuthenticateAsync(); /// - /// Challenge behavior. + /// Challenge the current request. /// /// The that contains the extra meta-data arriving with the authentication. - /// A task. Task ChallengeAsync(AuthenticationProperties? properties); /// - /// Forbid behavior. + /// Forbid the current request. /// /// The that contains the extra meta-data arriving with the authentication. - /// A task. Task ForbidAsync(AuthenticationProperties? properties); } } diff --git a/src/Http/Authentication.Abstractions/src/IAuthenticationHandlerProvider.cs b/src/Http/Authentication.Abstractions/src/IAuthenticationHandlerProvider.cs index 43e2438f13..cbf8e8691d 100644 --- a/src/Http/Authentication.Abstractions/src/IAuthenticationHandlerProvider.cs +++ b/src/Http/Authentication.Abstractions/src/IAuthenticationHandlerProvider.cs @@ -14,7 +14,7 @@ namespace Microsoft.AspNetCore.Authentication /// /// Returns the handler instance that will be used. /// - /// The context. + /// The . /// The name of the authentication scheme being handled. /// The handler instance. Task GetHandlerAsync(HttpContext context, string authenticationScheme); diff --git a/src/Http/Authentication.Abstractions/src/IAuthenticationRequestHandler.cs b/src/Http/Authentication.Abstractions/src/IAuthenticationRequestHandler.cs index d0013725c6..6e8a8da10d 100644 --- a/src/Http/Authentication.Abstractions/src/IAuthenticationRequestHandler.cs +++ b/src/Http/Authentication.Abstractions/src/IAuthenticationRequestHandler.cs @@ -11,7 +11,12 @@ namespace Microsoft.AspNetCore.Authentication public interface IAuthenticationRequestHandler : IAuthenticationHandler { /// - /// Returns true if request processing should stop. + /// Gets a value that determines if the request should stop being processed. + /// + /// This feature is supported by the Authentication middleware + /// which does not invoke any subsequent or middleware configured in the request pipeline + /// if the handler returns . + /// /// /// if request processing should stop. Task HandleRequestAsync(); diff --git a/src/Http/Authentication.Abstractions/src/IAuthenticationService.cs b/src/Http/Authentication.Abstractions/src/IAuthenticationService.cs index 14a53b6f4a..334ffbbf67 100644 --- a/src/Http/Authentication.Abstractions/src/IAuthenticationService.cs +++ b/src/Http/Authentication.Abstractions/src/IAuthenticationService.cs @@ -22,6 +22,7 @@ namespace Microsoft.AspNetCore.Authentication /// /// Challenge the specified authentication scheme. + /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication. /// /// The . /// The name of the authentication scheme. @@ -31,6 +32,7 @@ namespace Microsoft.AspNetCore.Authentication /// /// Forbids the specified authentication scheme. + /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access. /// /// The . /// The name of the authentication scheme. diff --git a/src/Http/Authentication.Abstractions/src/Microsoft.AspNetCore.Authentication.Abstractions.csproj b/src/Http/Authentication.Abstractions/src/Microsoft.AspNetCore.Authentication.Abstractions.csproj index 47f69cf497..f126750fba 100644 --- a/src/Http/Authentication.Abstractions/src/Microsoft.AspNetCore.Authentication.Abstractions.csproj +++ b/src/Http/Authentication.Abstractions/src/Microsoft.AspNetCore.Authentication.Abstractions.csproj @@ -3,7 +3,7 @@ ASP.NET Core common types used by the various authentication components. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security false diff --git a/src/Http/Authentication.Abstractions/src/TokenExtensions.cs b/src/Http/Authentication.Abstractions/src/TokenExtensions.cs index e40bda6715..63b9f3e324 100644 --- a/src/Http/Authentication.Abstractions/src/TokenExtensions.cs +++ b/src/Http/Authentication.Abstractions/src/TokenExtensions.cs @@ -80,6 +80,13 @@ namespace Microsoft.AspNetCore.Authentication return properties.Items.TryGetValue(tokenKey, out var value) ? value : null; } + /// + /// Updates the value of a token if already present. + /// + /// The to update. + /// The token name. + /// The token value. + /// if the token was updated, otherwise . public static bool UpdateTokenValue(this AuthenticationProperties properties, string tokenName, string tokenValue) { if (properties == null) @@ -101,7 +108,7 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Returns all of the AuthenticationTokens contained in the properties. + /// Returns all of the instances contained in the properties. /// /// The properties. /// The authentication tokens. @@ -130,23 +137,23 @@ namespace Microsoft.AspNetCore.Authentication } /// - /// Extension method for getting the value of an authentication token. + /// Authenticates the request using the specified authentication scheme and returns the value for the token. /// /// The . /// The context. /// The name of the token. - /// The value of the token. + /// The value of the token if present. public static Task GetTokenAsync(this IAuthenticationService auth, HttpContext context, string tokenName) => auth.GetTokenAsync(context, scheme: null, tokenName: tokenName); /// - /// Extension method for getting the value of an authentication token. + /// Authenticates the request using the specified authentication scheme and returns the value for the token. /// /// The . /// The context. /// The name of the authentication scheme. /// The name of the token. - /// The value of the token. + /// The value of the token if present. public static async Task GetTokenAsync(this IAuthenticationService auth, HttpContext context, string? scheme, string tokenName) { if (auth == null) diff --git a/src/Http/Authentication.Core/src/AuthenticationSchemeProvider.cs b/src/Http/Authentication.Core/src/AuthenticationSchemeProvider.cs index d9adda97d1..813caeb589 100644 --- a/src/Http/Authentication.Core/src/AuthenticationSchemeProvider.cs +++ b/src/Http/Authentication.Core/src/AuthenticationSchemeProvider.cs @@ -201,6 +201,7 @@ namespace Microsoft.AspNetCore.Authentication } } + /// public virtual Task> GetAllSchemesAsync() => Task.FromResult(_schemesCopy); } diff --git a/src/Http/Authentication.Core/src/Microsoft.AspNetCore.Authentication.Core.csproj b/src/Http/Authentication.Core/src/Microsoft.AspNetCore.Authentication.Core.csproj index e139c7a973..3101dfc830 100644 --- a/src/Http/Authentication.Core/src/Microsoft.AspNetCore.Authentication.Core.csproj +++ b/src/Http/Authentication.Core/src/Microsoft.AspNetCore.Authentication.Core.csproj @@ -4,7 +4,7 @@ ASP.NET Core common types used by the various authentication middleware components. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;authentication;security false