Skip to content

Commit b92364f

Browse files
pwelter34pwelter34
committed
add documentation
1 parent 4dd9132 commit b92364f

17 files changed

Lines changed: 227 additions & 25 deletions

‎src/AspNetCore.SecurityKey/ApplicationBuilderExtensions.cs‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,24 @@
22

33
namespace AspNetCore.SecurityKey;
44

5+
/// <summary>
6+
/// Extension methods for the <see cref="SecurityKeyMiddleware"/>.
7+
/// </summary>
58
public static class ApplicationBuilderExtensions
69
{
7-
public static IApplicationBuilder UseSecurityKey(this IApplicationBuilder app)
10+
/// <summary>
11+
/// Adds middleware for requiring security API key for all requests.
12+
/// </summary>
13+
/// <param name="builder">The <see cref="IApplicationBuilder" /> instance this method extends</param>
14+
/// <returns>
15+
/// The <see cref="IApplicationBuilder" /> for requirirng security API keys
16+
/// </returns>
17+
/// <exception cref="System.ArgumentNullException">builder is null</exception>
18+
public static IApplicationBuilder UseSecurityKey(this IApplicationBuilder builder)
819
{
9-
return app.UseMiddleware<SecurityKeyMiddleware>();
20+
if (builder is null)
21+
throw new ArgumentNullException(nameof(builder));
22+
23+
return builder.UseMiddleware<SecurityKeyMiddleware>();
1024
}
1125
}

‎src/AspNetCore.SecurityKey/AuthenticationBuilderExtensions.cs‎

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,62 @@
11
using Microsoft.AspNetCore.Authentication;
2+
using Microsoft.Extensions.DependencyInjection;
23

34
namespace AspNetCore.SecurityKey;
45

6+
/// <summary>
7+
/// Extension methods to configure security API key authentication.
8+
/// </summary>
59
public static class AuthenticationBuilderExtensions
610
{
11+
/// <summary>
12+
/// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
13+
/// The default scheme is specified by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
14+
/// </summary>
15+
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
16+
/// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
717
public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder)
18+
=> builder.AddSecurityKey(SecurityKeyAuthenticationDefaults.AuthenticationScheme);
19+
20+
/// <summary>
21+
/// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
22+
/// </summary>
23+
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
24+
/// <param name="authenticationScheme">The authentication scheme.</param>
25+
/// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
26+
public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme)
27+
=> builder.AddSecurityKey(authenticationScheme, configureOptions: null!);
28+
29+
/// <summary>
30+
/// Adds security API key authentication to <see cref="AuthenticationBuilder"/> using the default scheme.
31+
/// The default scheme is specified by <see cref="SecurityKeyAuthenticationDefaults.AuthenticationScheme"/>.
32+
/// </summary>
33+
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
34+
/// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
35+
/// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
36+
public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, Action<SecurityKeyAuthenticationSchemeOptions> configureOptions)
37+
=> builder.AddSecurityKey(SecurityKeyAuthenticationDefaults.AuthenticationScheme, configureOptions);
38+
39+
/// <summary>
40+
/// Adds security api key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
41+
/// </summary>
42+
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
43+
/// <param name="authenticationScheme">The authentication scheme.</param>
44+
/// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
45+
/// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
46+
public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme, Action<SecurityKeyAuthenticationSchemeOptions> configureOptions)
47+
=> builder.AddSecurityKey(authenticationScheme, displayName: null, configureOptions: configureOptions);
48+
49+
/// <summary>
50+
/// Adds security api key authentication to <see cref="AuthenticationBuilder"/> using the specified scheme.
51+
/// </summary>
52+
/// <param name="builder">The <see cref="AuthenticationBuilder"/>.</param>
53+
/// <param name="authenticationScheme">The authentication scheme.</param>
54+
/// <param name="displayName">A display name for the authentication handler.</param>
55+
/// <param name="configureOptions">A delegate to configure <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
56+
/// <returns>A reference to <paramref name="builder"/> after the operation has completed.</returns>
57+
public static AuthenticationBuilder AddSecurityKey(this AuthenticationBuilder builder, string authenticationScheme, string? displayName, Action<SecurityKeyAuthenticationSchemeOptions> configureOptions)
858
{
9-
return builder.AddScheme<SecurityKeyAuthenticationSchemeOptions, SecurityKeyAuthenticationHandler>(
10-
SecurityKeyAuthenticationDefaults.AuthenticationScheme,
11-
options => { }
12-
);
59+
builder.Services.AddOptions<SecurityKeyAuthenticationSchemeOptions>(authenticationScheme);
60+
return builder.AddScheme<SecurityKeyAuthenticationSchemeOptions, SecurityKeyAuthenticationHandler>(authenticationScheme, displayName, configureOptions);
1361
}
1462
}

‎src/AspNetCore.SecurityKey/DependencyInjectionExtensions.cs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,19 @@
44

55
namespace AspNetCore.SecurityKey;
66

7+
/// <summary>
8+
/// Extension methods for setting up security API key services
9+
/// </summary>
710
public static class DependencyInjectionExtensions
811
{
12+
/// <summary>
13+
/// Adds the security API key services to the specified <see cref="IServiceCollection"/>.
14+
/// </summary>
15+
/// <param name="services">The <see cref="IServiceCollection"/> to add services.</param>
16+
/// <param name="configure">An action delegate to configure the provided <see cref="SecurityKeyOptions"/>.</param>
17+
/// <returns>
18+
/// The <see cref="IServiceCollection"/> so that additional calls can be chained.
19+
/// </returns>
920
public static IServiceCollection AddSecurityKey(this IServiceCollection services, Action<SecurityKeyOptions>? configure = null)
1021
{
1122
services.AddHttpContextAccessor();

‎src/AspNetCore.SecurityKey/EndpointFilterExtensions.cs‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,25 @@
1+
#if NET7_0_OR_GREATER
12
using Microsoft.AspNetCore.Builder;
23
using Microsoft.AspNetCore.Http;
34

45
namespace AspNetCore.SecurityKey;
56

7+
/// <summary>
8+
/// Extension methods for adding <see cref="IEndpointFilter" /> to a route handler.
9+
/// </summary>
610
public static class EndpointFilterExtensions
711
{
8-
#if NET7_0_OR_GREATER
12+
/// <summary>
13+
/// Registers an endpoint filter requiring security API key for the specified route handler.
14+
/// </summary>
15+
/// <param name="builder">The <see cref="RouteHandlerBuilder"/>.</param>
16+
/// <returns>
17+
/// A <see cref="RouteHandlerBuilder"/> that can be used to further customize the route handler.
18+
/// </returns>
919
public static RouteHandlerBuilder RequireSecurityKey(this RouteHandlerBuilder builder)
1020
{
1121
builder.AddEndpointFilter<SecurityKeyEndpointFilter>();
1222
return builder;
1323
}
14-
#endif
1524
}
25+
#endif

‎src/AspNetCore.SecurityKey/ISecurityKeyExtractor.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,15 @@
22

33
namespace AspNetCore.SecurityKey;
44

5+
/// <summary>
6+
/// An interface for extracting the security API key
7+
/// </summary>
58
public interface ISecurityKeyExtractor
69
{
10+
/// <summary>
11+
/// Gets the security API key from the specified <see cref="HttpContent"/>.
12+
/// </summary>
13+
/// <param name="context">The <see cref="HttpContent"/> to get security key from.</param>
14+
/// <returns>The security API key if found; otherwise null</returns>
715
string? GetKey(HttpContext? context);
816
}

‎src/AspNetCore.SecurityKey/ISecurityKeyValidator.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
namespace AspNetCore.SecurityKey;
22

3+
/// <summary>
4+
/// An interface for validating the security API key
5+
/// </summary>
36
public interface ISecurityKeyValidator
47
{
8+
/// <summary>
9+
/// Validates the specified security API key.
10+
/// </summary>
11+
/// <param name="value">The security API key to validate.</param>
12+
/// <returns>true if security API key is valid; otherwise false</returns>
513
bool Validate(string? value);
614
}

‎src/AspNetCore.SecurityKey/SecurityKeyAttribute.cs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,16 @@
22

33
namespace AspNetCore.SecurityKey;
44

5+
/// <summary>
6+
/// Specifies that the class or method that this attribute is applied to requires security API key authorization.
7+
/// </summary>
8+
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
59
public class SecurityKeyAttribute : ServiceFilterAttribute
610
{
7-
public SecurityKeyAttribute()
8-
: base(typeof(SecurityKeyAuthorizationFilter))
11+
/// <summary>
12+
/// Initializes a new instance of the <see cref="SecurityKeyAttribute"/> class.
13+
/// </summary>
14+
public SecurityKeyAttribute() : base(typeof(SecurityKeyAuthorizationFilter))
915
{
1016
}
1117
}

‎src/AspNetCore.SecurityKey/SecurityKeyAuthenticationDefaults.cs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
namespace AspNetCore.SecurityKey;
1+
namespace AspNetCore.SecurityKey;
22

3+
/// <summary>
4+
/// Default values related to security API key authentication
5+
/// </summary>
36
public static class SecurityKeyAuthenticationDefaults
47
{
8+
/// <summary>
9+
/// The default authentication scheme
10+
/// </summary>
511
public const string AuthenticationScheme = "SecurityKey";
612
}

‎src/AspNetCore.SecurityKey/SecurityKeyAuthenticationHandler.cs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,24 @@
99

1010
namespace AspNetCore.SecurityKey;
1111

12+
/// <summary>
13+
/// Implementation for the cookie-based authentication handler.
14+
/// </summary>
1215
public class SecurityKeyAuthenticationHandler : AuthenticationHandler<SecurityKeyAuthenticationSchemeOptions>
1316
{
1417
private readonly ISecurityKeyExtractor _securityKeyExtractor;
1518
private readonly ISecurityKeyValidator _securityKeyValidator;
1619

1720
#pragma warning disable CS0618 // allow ISystemClock for compatibility
21+
/// <summary>
22+
/// Initializes a new instance of the <see cref="SecurityKeyAuthenticationHandler"/> class.
23+
/// </summary>
24+
/// <param name="options">Accessor to <see cref="SecurityKeyAuthenticationSchemeOptions"/>.</param>
25+
/// <param name="logger">The <see cref="ILoggerFactory"/>.</param>
26+
/// <param name="encoder">The <see cref="UrlEncoder"/>.</param>
27+
/// <param name="clock">The <see cref="ISystemClock"/>.</param>
28+
/// <param name="securityKeyExtractor">The security key extractor.</param>
29+
/// <param name="securityKeyValidator">The security key validator.</param>
1830
public SecurityKeyAuthenticationHandler(
1931
IOptionsMonitor<SecurityKeyAuthenticationSchemeOptions> options,
2032
ILoggerFactory logger,
@@ -29,6 +41,7 @@ public SecurityKeyAuthenticationHandler(
2941
}
3042
#pragma warning restore CS0618
3143

44+
/// <inheritdoc />
3245
protected override Task<AuthenticateResult> HandleAuthenticateAsync()
3346
{
3447
var securityKey = _securityKeyExtractor.GetKey(Context);

‎src/AspNetCore.SecurityKey/SecurityKeyAuthenticationSchemeOptions.cs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1-
using Microsoft.AspNetCore.Authentication;
1+
using Microsoft.AspNetCore.Authentication;
22

33
namespace AspNetCore.SecurityKey;
44

5+
/// <summary>
6+
/// Configuration options for SecurityKeyAuthenticationSchemeOptions.
7+
/// </summary>
8+
/// <seealso cref="Microsoft.AspNetCore.Authentication.AuthenticationSchemeOptions" />
59
public class SecurityKeyAuthenticationSchemeOptions : AuthenticationSchemeOptions
610
{
711

0 commit comments

Comments
 (0)