Access Control Plugin

Overview

The Access Control plugin provides a comprehensive Role-Based Access Control (RBAC) system for managing authorization in your application. It enables you to define roles, assign permissions to those roles, and grant roles to users, creating a flexible and scalable authorization model.

What It Does

• Role Management — Create and manage roles. Supports system-managed roles that cannot be modified or deleted once created. Roles also support adding a weight to determine their hierarchy and precedence. This is reminicent of the concept of "role hierarchy" in traditional RBAC systems, but implemented with a flexible weight system that allows for more granular control.
• Permission Management — Define fine-grained permissions with unique keys
• Role-Permission Mapping — Associate permissions with roles and manage bulk updates
• User Authorization — Assign roles to users and query their effective permissions
• Audit Tracking — Track who granted permissions and assigned roles

The plugin uses a hierarchical model: Users → Roles → Permissions, allowing you to manage authorization at any level and simplifying policy changes across multiple users.

Configuration

Standalone Mode

[plugins.access_control]
enabled = true

Library Mode

accesscontrolplugin "github.com/Authula/authula/plugins/access-control"
accesscontrolplugintypes "github.com/Authula/authula/plugins/access-control/types"

accesscontrolplugin.New(accesscontrolplugintypes.AccessControlPluginConfig{
  Enabled: true,
})

API Reference

Each endpoint in this plugin requires the caller to have a specific hardcoded permission assigned to their role(s).

Roles Management

Permissions Management

Role-Permission Mapping

User Access & Permissions

Database Schema

This plugin creates the following database tables:

Table: access_control_roles

Table: access_control_permissions

Table: access_control_role_permissions

Table: access_control_user_roles

Migrations are automatically handled when the plugin is initialized.

Plugin Capabilities

Example Usage

Standalone mode:

[[route_mappings]]
path = "/some/path"
method = "GET"
# Make sure to include an auth capability plugin (e.g. session.auth) before the access control plugin
# to ensure the user is authenticated before enforcing permissions.
plugins = ["session.auth"]
permissions = ["domain:resource:action"] # Specify the required custom permission to access this route

Library mode:

import (
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
  sessionplugin "github.com/Authula/authula/plugins/session"
  accesscontrolplugin "github.com/Authula/authula/plugins/access-control"
)

config := authulaconfig.NewConfig(
  // Other config options...
  authulaconfig.WithRouteMappings([]authulamodels.RouteMapping{
    {
      Method: "GET",
      Path:   "/some/path",
      Plugins: []string{
        sessionplugin.HookIDSessionAuth.String(),
      },
      Permissions: []string{
        "domain:resource:action",
      },
    },
  }),
)

Notes

• System-managed roles and permissions are protected from modification or deletion to ensure critical access controls remain intact.
• Role weights allow you to establish a hierarchy, where higher-weighted roles take precedence over lower-weighted ones. This is very useful for scenarios where users may have multiple roles, and you want to determine which role is of higher priority. Also this is important to take into consideration as a user can only grant roles with equal or lower weight than their highest role, preventing privilege escalation.
  • An example of this is an Admin role with weight 100, Editor role with weight 50, and Viewer role with weight 25. An Admin can assign any of these roles, while an Editor can only assign the Viewer role.

Client Plugin

If you're using the Authula SDK, add the plugin to the SDK like so:

import { createClient } from "authula";
import { AccessControlPlugin } from "authula/plugins";

export const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [
    // other plugins...
    new AccessControlPlugin(),
  ],
});