Merge pull request #166 from marcominerva/copilot/add-roles-parameter-authentication

Add Roles support to ApiKey and Basic Authentication

Author: marcominerva

README.md

@@ -198,6 +198,76 @@ When using API Key or Basic Authentication, you can specify multiple fixed value
 
 With this configuration, authentication will succeed if any of these credentials are provided.
 
+**Assigning roles to API Keys and Basic Authentication credentials**
+
+You can optionally specify roles for each API Key or Basic Authentication credential. When authentication succeeds, the specified roles will be automatically added as role claims to the user's identity.
+
+For single credentials, you can specify roles directly:
+
+```json
+"Authentication": {
+    "ApiKey": {
+        "ApiKeyValue": "f1I7S5GXa4wQDgLQWgz0",
+        "UserName": "ApiUser",
+        "Roles": ["Administrator"]
+    },
+    "Basic": {
+        "UserName": "marco",
+        "Password": "P@$$w0rd",
+        "Roles": ["Administrator"]
+    }
+}
+```
+
+For multiple credentials, you can specify roles for each credential:
+
+```json
+"Authentication": {
+    "ApiKey": {
+        "ApiKeys": [
+            {
+                "Value": "key-1",
+                "UserName": "UserName1",
+                "Roles": ["Administrator", "User"]
+            },
+            {
+                "Value": "key-2",
+                "UserName": "UserName2",
+                "Roles": ["User"]
+            }
+        ]
+    },
+    "Basic": {
+        "Credentials": [
+            {
+                "UserName": "UserName1",
+                "Password": "Password1",
+                "Roles": ["Manager", "User"]
+            },
+            {
+                "UserName": "UserName2",
+                "Password": "Password2",
+                "Roles": ["User"]
+            }
+        ]
+    }
+}
+```
+
+The `Roles` parameter is optional. If omitted, no role claims will be added to the user's identity. You can then use the standard ASP.NET Core authorization features to check for roles:
+
+```csharp
+[Authorize(Roles = "Administrator")]
+public IActionResult AdminEndpoint()
+{
+    return Ok("Administrator access granted");
+}
+
+// Or with minimal APIs
+app.MapGet("/admin", () => "Administrator access granted")
+   .RequireAuthorization(policy => policy.RequireRole("Administrator"));
+```
+
 **Custom Authentication logic for API Keys and Basic Authentication**
 
 If you need to implement custom authentication logic, for example validating credentials with dynamic values and adding claims to identity, you can omit all the credentials in the _appsettings.json_ file and then provide an implementation of [IApiKeyValidator.cs](https://github.com/marcominerva/SimpleAuthentication/blob/master/src/SimpleAuthentication.Abstractions/ApiKey/IApiKeyValidator.cs) or [IBasicAuthenticationValidator.cs](https://github.com/marcominerva/SimpleAuthentication/blob/master/src/SimpleAuthentication.Abstractions/BasicAuthentication/IBasicAuthenticationValidator.cs):

samples/MinimalApis/ApiKeySample/Program.cs

@@ -1,6 +1,7 @@
 using System.Security.Claims;
 using ApiKeySample.Authentication;
 using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Options;
 using SimpleAuthentication;
 using SimpleAuthentication.ApiKey;
 
@@ -55,16 +56,22 @@
 app.UseAuthentication();
 app.UseAuthorization();
 
-app.MapGet("api/me", (ClaimsPrincipal user) =>
+app.MapGet("api/me", (ClaimsPrincipal user, IOptions<ApiKeySettings> options) =>
 {
-    return TypedResults.Ok(new User(user.Identity!.Name));
+    var roles = user.FindAll(options.Value.RoleClaimType).Select(c => c.Value);
+    return TypedResults.Ok(new User(user.Identity!.Name, roles));
 })
-.RequireAuthorization()
-.WithOpenApi();
+.RequireAuthorization();
+
+app.MapGet("api/admin", () => "Administrator access granted")
+.RequireAuthorization(policy => policy.RequireRole("Administrator"));
+
+app.MapGet("api/user", () => "User access granted")
+.RequireAuthorization(policy => policy.RequireRole("User"));
 
 app.Run();
 
-public record class User(string? UserName);
+public record class User(string? UserName, IEnumerable<string> Roles);
 
 public class CustomApiKeyValidator : IApiKeyValidator
 {

samples/MinimalApis/ApiKeySample/appsettings.json

@@ -11,15 +11,18 @@
             // You can set a fixed API Key for authentication. If you have a single value, you can just use the plain property:
             "ApiKeyValue": "f1I7S5GXa4wQDgLQWgz0",
             "UserName": "ApiUser", // Required if ApiKeyValue is used
+            "Roles": [ "Administrator" ],
             // Otherwise, you can create an array of ApiKeys:
             "ApiKeys": [
                 {
                     "Value": "ArAilHVOoL3upX78Cohq",
-                    "UserName": "alice"
+                    "UserName": "alice",
+                    "Roles": [ "Administrator", "User" ]
                 },
                 {
                     "Value": "DiUU5EqImTYkxPDAxBVS",
-                    "UserName": "bob"
+                    "UserName": "bob",
+                    "Roles": [ "User" ]
                 }
             ]
             // You can also combine both declarations.

samples/MinimalApis/BasicAuthenticationSample/Program.cs

@@ -1,6 +1,7 @@
 using System.Security.Claims;
 using BasicAuthenticationSample.Authentication;
 using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Options;
 using SimpleAuthentication;
 using SimpleAuthentication.BasicAuthentication;
 
@@ -55,16 +56,22 @@
 app.UseAuthentication();
 app.UseAuthorization();
 
-app.MapGet("api/me", (ClaimsPrincipal user) =>
+app.MapGet("api/me", (ClaimsPrincipal user, IOptions<BasicAuthenticationSettings> options) =>
 {
-    return TypedResults.Ok(new User(user.Identity!.Name));
+    var roles = user.FindAll(options.Value.RoleClaimType).Select(c => c.Value);
+    return TypedResults.Ok(new User(user.Identity!.Name, roles));
 })
-.RequireAuthorization()
-.WithOpenApi();
+.RequireAuthorization();
+
+app.MapGet("api/admin", () => "Administrator access granted")
+.RequireAuthorization(policy => policy.RequireRole("Administrator"));
+
+app.MapGet("api/user", () => "User access granted")
+.RequireAuthorization(policy => policy.RequireRole("User"));
 
 app.Run();
 
-public record class User(string? UserName);
+public record class User(string? UserName, IEnumerable<string> Roles);
 
 public class CustomBasicAuthenticationValidator : IBasicAuthenticationValidator
 {

samples/MinimalApis/BasicAuthenticationSample/appsettings.json

@@ -8,15 +8,18 @@
             //"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
             "UserName": "marco",
             "Password": "P@$$w0rd",
+            "Roles": [ "Administrator" ],
             // Otherwise, you can create an array of Credentials:
             "Credentials": [
                 {
                     "UserName": "alice",
-                    "Password": "Password1"
+                    "Password": "Password1",
+                    "Roles": [ "Administrator", "User" ]
                 },
                 {
                     "UserName": "bob",
-                    "Password": "Password2"
+                    "Password": "Password2",
+                    "Roles": [ "User" ]
                 }
             ]
             // You can also combine both declarations.

src/SimpleAuthentication.Abstractions/ApiKey/ApiKey.cs

@@ -1,8 +1,9 @@
-namespace SimpleAuthentication.ApiKey;
+namespace SimpleAuthentication.ApiKey;
 
 /// <summary>
 /// Store API Keys for API Key Authentication
 /// </summary>
 /// <param name="Value">The API key value</param>
 /// <param name="UserName">The user name associated with the current key</param>
-public record class ApiKey(string Value, string UserName);
+/// <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);

src/SimpleAuthentication.Abstractions/ApiKey/ApiKeySettings.cs

@@ -41,6 +41,13 @@ public class ApiKeySettings : AuthenticationSchemeOptions
     /// <seealso cref="ApiKeyValue"/>
     public string? UserName { get; set; }
 
+    /// <summary>
+    /// Gets or sets the optional list of roles to assign to the user when using <see cref="ApiKeyValue"/> and <see cref="UserName"/>.
+    /// </summary>
+    /// <seealso cref="ApiKeyValue"/>
+    /// <seealso cref="UserName"/>
+    public IEnumerable<string>? Roles { get; set; }
+
     /// <summary>
     /// The collection of valid API keys.
     /// </summary>
@@ -72,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));
+            apiKeys.Add(new(ApiKeyValue, UserName, Roles));
         }
 
         return apiKeys;

src/SimpleAuthentication.Abstractions/BasicAuthentication/BasicAuthenticationSettings.cs

@@ -30,6 +30,13 @@ public class BasicAuthenticationSettings : AuthenticationSchemeOptions
     /// <seealso cref="IBasicAuthenticationValidator"/>
     public string? Password { get; set; }
 
+    /// <summary>
+    /// Gets or sets the optional list of roles to assign to the user when using <see cref="UserName"/> and <see cref="Password"/>.
+    /// </summary>
+    /// <seealso cref="UserName"/>
+    /// <seealso cref="Password"/>
+    public IEnumerable<string>? Roles { get; set; }
+
     /// <summary>
     /// The collection of authorization credentials.
     /// </summary>
@@ -61,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));
+            credentials.Add(new(UserName, Password, Roles));
         }
 
         return credentials;

src/SimpleAuthentication.Abstractions/BasicAuthentication/Credential.cs

@@ -1,8 +1,9 @@
-namespace SimpleAuthentication.BasicAuthentication;
+namespace SimpleAuthentication.BasicAuthentication;
 
 /// <summary>
 /// Store credentials used for Basic Authentication.
 /// </summary>
 /// <param name="UserName">The user name</param>
 /// <param name="Password">The password</param>
-public record class Credential(string UserName, string Password);
+/// <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);

src/SimpleAuthentication.Swashbuckle/SimpleAuthentication.Swashbuckle.csproj

@@ -32,7 +32,7 @@
     </ItemGroup>
 
     <ItemGroup>
-        <PackageReference Include="SimpleAuthenticationTools.Abstractions" Version="3.0.13" />
+        <ProjectReference Include="..\SimpleAuthentication.Abstractions\SimpleAuthentication.Abstractions.csproj" />
         <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="9.0.6" />
     </ItemGroup>