Sang.AspNetCore.RoleBasedAuthorization 1.1.7

Sang.AspNetCore.RoleBasedAuthorization

Role-Based Authorization for ASP.NET.

For the Chinese version, see README.zh-CN.md.

Instructions

Step 1

Add this package:

Install-Package Sang.AspNetCore.RoleBasedAuthorization

Step 2

Add RBAC services:

builder.Services.AddSangRoleBasedAuthorization();

You can also configure the administrator role name. The default is SangRBAC_Administrator:

builder.Services.AddSangRoleBasedAuthorization(options =>
{
    options.AdministratorRoleName = "Admin";
});

Step 3

Add the ResourceAttribute tag to the Controller or action that needs to be authorized:

[Resource("Resource")]
[Route("api/[controller]")]
[ApiController]
public class RolesController : ControllerBase
{
}

/// <summary>
/// Delete - Value
/// </summary>
/// <param name="id"></param>
[Resource("Delete", "Value")]
[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
    return Ok("Delete-Value");
}

Step 4

After completing the above operations, the authorization check will verify whether User.Claims contains the corresponding Permission. You need to add the corresponding Claims for the user, which can be included directly when generating the JWT token. You can also use middleware to read the corresponding role and add it before the authorization check. You can implement it yourself or use the provided functions described in the next section.

var claims = new List<Claim>
{
    new Claim(ClaimTypes.NameIdentifier, "uid"),
    new Claim(ClaimTypes.Name, "UserName"),
    new Claim(ClaimTypes.Email, "test@exp.com"),
    new Claim(ClaimTypes.Role, "user"),
    new Claim(ResourceClaimTypes.Permission, "Query"),
};
var token = new JwtSecurityToken(
        "Issuer",
        "Audience",
        claims,
        expires: DateTime.UtcNow.AddSeconds(3600),
        signingCredentials: credentials
    );

Note: If the role is named SangRBAC_Administrator, no authorization check will be done. This role name can be customized via SangRoleBasedAuthorizationOptions.AdministratorRoleName.

Optional Features

Use the provided role-permission middleware. You can also use this component alone.

Step 1

Implement IRolePermission to get the permission list by role name:

public class MyRolePermission : IRolePermission
{
    public Task<List<Claim>> GetRolePermissionClaimsByName(string roleName)
    {
        List<Claim> list = new();
        // your code
        return Task.FromResult(list);
    }
}

Then add the service:

builder.Services.AddRolePermission<MyRolePermission>();

Step 2

Enable this middleware before app.UseAuthorization(); and after app.UseAuthentication();:

app.UseAuthentication();
app.UseRolePermission();
app.UseAuthorization();

Options

UseRolePermission accepts the following options:

1. option.Always

Whether to always check and execute the addition. By default, the middleware only adds permissions when the current request has a ResourceAttribute to be verified.

Wildcard Permission Matching

The authorization handler supports the following permission claim formats:

• "Resource" — grants all actions under the resource.
• "Resource-Action" — grants a specific action.
• "Resource-*" — grants all actions under the resource (explicit wildcard).
• "*" — grants all resources and actions (global super-administrator permission).

Demo

• Simple Demo: https://github.com/sangyuxiaowu/Sang.AspNetCore.RoleBasedAuthorization/tree/main/TestDemo
• Used in Identity: https://github.com/sangyuxiaowu/IdentityRBAC