Role Management

Moka.Auth implements a flexible role-based access control (RBAC) system that allows you to manage user permissions through roles.

Role Operations

Creating Roles

// Via dependency injection
public class YourService
{
    private readonly IRoleService _roleService;
    private readonly IUserService _userService;

    public YourService(IRoleService roleService, IUserService userService)
    {
        _roleService = roleService;
        _userService = userService;
    }

    public async Task CreateRoleAsync()
    {
        var role = new MokaRole
        {
            Name = "ContentEditor",
            Description = "Can edit and publish content"
        };

        var result = await _roleService.CreateAsync(role);

        if (result)
        {
            // Role created successfully
            await _roleService.AddPermissionAsync(role.Id, "content.edit");
            await _roleService.AddPermissionAsync(role.Id, "content.publish");
        }
    }
}

Retrieving Roles

// Get role by ID
var role = await _roleService.FindByIdAsync(roleId);

// Get role by name
var role = await _roleService.FindByNameAsync(roleName);

// Get all roles
var roles = await _roleService.GetAllRolesAsync();

Updating Roles

public async Task UpdateRoleAsync(int roleId, RoleUpdateModel model)
{
    var role = await _roleService.FindByIdAsync(roleId);
    if (role != null)
    {
        role.Name = model.Name;
        role.Description = model.Description;

        var result = await _roleService.UpdateAsync(role);
        if (result)
        {
            // Role updated successfully
        }
    }
}

Deleting Roles

public async Task DeleteRoleAsync(int roleId)
{
    var result = await _roleService.DeleteAsync(roleId);
    if (result)
    {
        // Role deleted successfully
    }
}

Permission Management

Managing Role Permissions

// Add permission to role
await _roleService.AddPermissionAsync(roleId, permissionId);

// Remove permission from role
await _roleService.RemovePermissionAsync(roleId, permissionId);

// Get role's permissions
var permissions = await _roleService.GetPermissionsAsync(roleId);

User Role Management

// Add user to role
await _userService.AddToRoleAsync(userId, roleName);

// Remove user from role
await _userService.RemoveFromRoleAsync(userId, roleName);

// Get user's roles
var roles = await _userService.GetRolesAsync(userId);

// Get user's effective permissions (including from roles)
var effectivePermissions = await _userService.GetEffectivePermissionsAsync(userId);

API Endpoints

Moka.Auth provides built-in REST API endpoints for role management:

• POST /api/roles - Create new role
• GET /api/roles - List all roles
• GET /api/roles/{id} - Get role by ID
• PUT /api/roles/{id} - Update role
• DELETE /api/roles/{id} - Delete role
• POST /api/roles/{id}/permissions - Add permission to role
• DELETE /api/roles/{id}/permissions/{permissionId} - Remove permission from role
• GET /api/roles/{id}/permissions - List role permissions

Default Roles

Configure default roles in your application startup:

public async Task ConfigureDefaultRolesAsync(IRoleService roleService)
{
    // Create default roles if they don't exist
    var defaultRoles = new[]
    {
        new MokaRole { Name = "Admin", Description = "Full system access" },
        new MokaRole { Name = "User", Description = "Standard user access" },
        new MokaRole { Name = "Guest", Description = "Limited read-only access" }
    };

    foreach (var role in defaultRoles)
    {
        var existingRole = await roleService.FindByNameAsync(role.Name);
        if (existingRole == null)
        {
            await roleService.CreateAsync(role);
        }
    }
}

Best Practices

1. Role Design:

   • Keep roles focused and specific
   • Use descriptive names and descriptions
   • Avoid creating too many roles
   • Consider using a hierarchical structure

2. Permission Assignment:

   • Follow the principle of least privilege
   • Regularly audit role permissions
   • Document role permissions
   • Consider using role templates for common scenarios

3. Security:

   • Validate role names and descriptions
   • Implement role-based authorization in controllers and services
   • Log role management operations
   • Regularly review role assignments

4. Performance:

   • Cache role permissions where appropriate
   • Use bulk operations for multiple permission assignments
   • Consider the impact of role hierarchy depth
   • Monitor database performance

Example: Complete Role Setup

Here’s a complete example of setting up roles with permissions:

public class RoleSetup
{
    private readonly IRoleService _roleService;
    private readonly IPermissionService _permissionService;

    public RoleSetup(IRoleService roleService, IPermissionService permissionService)
    {
        _roleService = roleService;
        _permissionService = permissionService;
    }

    public async Task SetupRolesAsync()
    {
        // Create permissions
        var createUserPerm = await _permissionService.CreateAsync(new MokaPermission
        {
            Name = "users.create",
            Description = "Can create users"
        });

        var manageUserPerm = await _permissionService.CreateAsync(new MokaPermission
        {
            Name = "users.manage",
            Description = "Can manage users"
        });

        // Create admin role
        var adminRole = new MokaRole
        {
            Name = "Admin",
            Description = "System administrator"
        };

        if (await _roleService.CreateAsync(adminRole))
        {
            // Add permissions to admin role
            await _roleService.AddPermissionAsync(adminRole.Id, createUserPerm.Id);
            await _roleService.AddPermissionAsync(adminRole.Id, manageUserPerm.Id);
        }

        // Create user role
        var userRole = new MokaRole
        {
            Name = "User",
            Description = "Standard user"
        };

        if (await _roleService.CreateAsync(userRole))
        {
            // Users can only create other users
            await _roleService.AddPermissionAsync(userRole.Id, createUserPerm.Id);
        }
    }
}