Enhance authentication setup and endpoint clarity

- Ensure roles in `ApiKey` and `Credential` classes are non-optional and add equality/hash code methods.
- Initialize roles and claims with empty lists in settings and validation result classes to prevent null references.
- Simplify role claim addition in authentication handlers by removing null checks.
- Maintain consistency in `SimpleAuthenticationExtensions` by initializing roles with empty lists if null.

Author: marcominerva

samples/Controllers/ApiKeySample/Program.cs

@@ -24,6 +24,7 @@
 //        .Build())
 //    .AddPolicy("ApiKey", builder => builder.AddAuthenticationSchemes(ApiKeyDefaults.AuthenticationScheme).RequireAuthenticatedUser());
 
+// This service is used when there isn't a fixed API Key value in the configuration.
 builder.Services.AddTransient<IApiKeyValidator, CustomApiKeyValidator>();
 
 // Uncomment the following line if you have multiple authentication schemes and

samples/Controllers/BasicAuthenticationSample/Program.cs

@@ -25,6 +25,7 @@
 //        .Build())
 //    .AddPolicy("Basic", builder => builder.AddAuthenticationSchemes(BasicAuthenticationDefaults.AuthenticationScheme).RequireAuthenticatedUser());
 
+// This service is used when there isn't a fixed user/password value in the configuration.
 builder.Services.AddTransient<IBasicAuthenticationValidator, CustomBasicAuthenticationValidator>();
 
 // Uncomment the following line if you have multiple authentication schemes and

samples/MinimalApis/ApiKeySample/Program.cs

@@ -25,6 +25,7 @@
 //        .Build())
 //    .AddPolicy("ApiKey", builder => builder.AddAuthenticationSchemes(ApiKeyDefaults.AuthenticationScheme).RequireAuthenticatedUser());
 
+// This service is used when there isn't a fixed API Key value in the configuration.
 builder.Services.AddTransient<IApiKeyValidator, CustomApiKeyValidator>();
 
 // Uncomment the following line if you have multiple authentication schemes and
@@ -63,10 +64,12 @@
 })
 .RequireAuthorization();
 
-app.MapGet("api/admin", () => "Administrator access granted")
+app.MapGet("api/administrator", () => TypedResults.NoContent())
+.WithDescription("This endpoint requires the user to have the 'Administrator' role.")
 .RequireAuthorization(policy => policy.RequireRole("Administrator"));
 
-app.MapGet("api/user", () => "User access granted")
+app.MapGet("api/user", () => TypedResults.NoContent())
+.WithDescription("This endpoint requires the user to have the 'User' role.")
 .RequireAuthorization(policy => policy.RequireRole("User"));
 
 app.Run();

samples/MinimalApis/BasicAuthenticationSample/Program.cs

@@ -25,6 +25,7 @@
 //        .Build())
 //    .AddPolicy("Basic", builder => builder.AddAuthenticationSchemes(BasicAuthenticationDefaults.AuthenticationScheme).RequireAuthenticatedUser());
 
+// This service is used when there isn't a fixed user/password value in the configuration.
 builder.Services.AddTransient<IBasicAuthenticationValidator, CustomBasicAuthenticationValidator>();
 
 // Uncomment the following line if you have multiple authentication schemes and
@@ -63,10 +64,12 @@
 })
 .RequireAuthorization();
 
-app.MapGet("api/admin", () => "Administrator access granted")
+app.MapGet("api/administrator", () => TypedResults.NoContent())
+.WithDescription("This endpoint requires the user to have the 'Administrator' role.")
 .RequireAuthorization(policy => policy.RequireRole("Administrator"));
 
-app.MapGet("api/user", () => "User access granted")
+app.MapGet("api/user", () => TypedResults.NoContent())
+.WithDescription("This endpoint requires the user to have the 'User' role.")
 .RequireAuthorization(policy => policy.RequireRole("User"));
 
 app.Run();

src/SimpleAuthentication.Abstractions/ApiKey/ApiKey.cs

@@ -5,5 +5,28 @@ namespace SimpleAuthentication.ApiKey;
 /// </summary>
 /// <param name="Value">The API key value</param>
 /// <param name="UserName">The user name associated with the current key</param>
-/// <param name="Roles">The optional list of roles to assign to the user</param>
-public record class ApiKey(string Value, string UserName, IEnumerable<string>? Roles = null);
+/// <param name="Roles">The list of roles to assign to the user</param>
+public record class ApiKey(string Value, string UserName, IEnumerable<string> Roles)
+{
+    /// <inheritdoc />
+    public virtual bool Equals(ApiKey? other)
+    {
+        if (other is null)
+        {
+            return false;
+        }
+
+        if (ReferenceEquals(this, other))
+        {
+            return true;
+        }
+
+        return Value == other.Value && UserName == other.UserName;
+    }
+
+    /// <inheritdoc />
+    public override int GetHashCode()
+    {
+        return HashCode.Combine(Value, UserName);
+    }
+}

src/SimpleAuthentication.Abstractions/ApiKey/ApiKeySettings.cs

@@ -46,7 +46,7 @@ public class ApiKeySettings : AuthenticationSchemeOptions
     /// </summary>
     /// <seealso cref="ApiKeyValue"/>
     /// <seealso cref="UserName"/>
-    public IEnumerable<string>? Roles { get; set; }
+    public IEnumerable<string> Roles { get; set; } = [];
 
     /// <summary>
     /// The collection of valid API keys.
@@ -79,7 +79,7 @@ internal IEnumerable<ApiKey> GetAllApiKeys()
         if (!string.IsNullOrWhiteSpace(ApiKeyValue) && !string.IsNullOrWhiteSpace(UserName))
         {
             // If necessary, add the API Key from the base properties.
-            apiKeys.Add(new(ApiKeyValue, UserName, Roles));
+            apiKeys.Add(new(ApiKeyValue, UserName, Roles ?? []));
         }
 
         return apiKeys;

src/SimpleAuthentication.Abstractions/ApiKey/ApiKeyValidationResult.cs

@@ -23,18 +23,18 @@ public class ApiKeyValidationResult
     /// <summary>
     /// Gets the claim list, if authentication was successful.
     /// </summary>
-    public IList<Claim>? Claims { get; }
+    public IList<Claim> Claims { get; } = [];
 
     /// <summary>
     /// Gets the failure message, if authentication was unsuccessful.
     /// </summary>
     public string? FailureMessage { get; }
 
-    private ApiKeyValidationResult(string userName, IList<Claim>? claims)
+    private ApiKeyValidationResult(string userName, IList<Claim>? claims = null)
     {
         Succeeded = true;
         UserName = userName;
-        Claims = claims;
+        Claims = claims ?? [];
     }
 
     private ApiKeyValidationResult(string failureMessage)

src/SimpleAuthentication.Abstractions/BasicAuthentication/BasicAuthenticationSettings.cs

@@ -35,7 +35,7 @@ public class BasicAuthenticationSettings : AuthenticationSchemeOptions
     /// </summary>
     /// <seealso cref="UserName"/>
     /// <seealso cref="Password"/>
-    public IEnumerable<string>? Roles { get; set; }
+    public IEnumerable<string> Roles { get; set; } = [];
 
     /// <summary>
     /// The collection of authorization credentials.
@@ -68,7 +68,7 @@ internal IEnumerable<Credential> GetAllCredentials()
         if (!string.IsNullOrWhiteSpace(UserName) && !string.IsNullOrWhiteSpace(Password))
         {
             // If necessary, add the Credentials from the base properties.
-            credentials.Add(new(UserName, Password, Roles));
+            credentials.Add(new(UserName, Password, Roles ?? []));
         }
 
         return credentials;

src/SimpleAuthentication.Abstractions/BasicAuthentication/BasicAuthenticationValidationResult.cs

@@ -23,7 +23,7 @@ public class BasicAuthenticationValidationResult
     /// <summary>
     /// Gets the claim list, if authentication was successful.
     /// </summary>
-    public IList<Claim>? Claims { get; }
+    public IList<Claim> Claims { get; } = [];
 
     /// <summary>
     /// Gets the failure message, if authentication was unsuccessful.
@@ -34,7 +34,7 @@ private BasicAuthenticationValidationResult(string userName, IList<Claim>? claim
     {
         Succeeded = true;
         UserName = userName;
-        Claims = claims;
+        Claims = claims ?? [];
     }
 
     private BasicAuthenticationValidationResult(string failureMessage)

src/SimpleAuthentication.Abstractions/BasicAuthentication/Credential.cs

@@ -5,5 +5,28 @@ namespace SimpleAuthentication.BasicAuthentication;
 /// </summary>
 /// <param name="UserName">The user name</param>
 /// <param name="Password">The password</param>
-/// <param name="Roles">The optional list of roles to assign to the user</param>
-public record class Credential(string UserName, string Password, IEnumerable<string>? Roles = null);
+/// <param name="Roles">The list of roles to assign to the user</param>
+public record class Credential(string UserName, string Password, IEnumerable<string> Roles)
+{
+    /// <inheritdoc />
+    public virtual bool Equals(Credential? other)
+    {
+        if (other is null)
+        {
+            return false;
+        }
+
+        if (ReferenceEquals(this, other))
+        {
+            return true;
+        }
+
+        return UserName == other.UserName && Password == other.Password;
+    }
+
+    /// <inheritdoc />
+    public override int GetHashCode()
+    {
+        return HashCode.Combine(UserName, Password);
+    }
+}