controller-roles

Role-based access control with RoleHandler

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a robust framework for implementing Role-Based Access Control (RBAC) in Go applications using the RoleHandler utility. It simplifies API security by mapping user roles to specific handler functions, managing session contexts automatically, and providing a hierarchical fallback mechanism to ensure secure and flexible authorization logic.

Use Cases

  • Restricting sensitive administrative actions (Create, Update, Delete) to users with specific high-level privileges like ROLE_ADMIN.
  • Implementing read-only access for support or audit staff by utilizing the ROLE_READ_ADMIN hierarchy to allow viewing without modification rights.
  • Providing multi-level access on a single endpoint, where admins receive full data objects and regular users receive limited, public-facing versions of the same resource.
  • Automating session management and user identity extraction from request headers to streamline backend development and reduce boilerplate code.
  • Enforcing global security standards by ensuring unauthenticated requests are automatically rejected with 401 Unauthorized status across all protected routes.
namecontroller-roles
descriptionRole-based access control with RoleHandler

Role-Based Access Control

The helpers.RoleHandler function provides role-based access control by mapping roles to specific handler functions.

Basic Usage

helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_READ_ADMIN: helpers.StandardRequestWrapper(adminGet),
    constants.ROLE_ADMIN: helpers.StandardRequestWrapper(adminCreate),
})

Role Hierarchy

Roles are defined as integer constants in descending order of privilege:

Role Value Description
ROLE_ADMIN 100 Full system administrator access
ROLE_READ_ADMIN 90 Read-only administrator access
ROLE_ANY_AUTHORIZED 0 Any authenticated user
ROLE_UNAUTHORIZED -1 Unauthenticated requests

How RoleHandler Works

  1. Extracts session from request headers/cookies
  2. Looks up user's role from the database
  3. Finds highest-privilege handler the user can access
  4. Falls back to lower privilege handlers if exact role match isn't found
  5. Returns 401 Unauthorized if no suitable handler is found

Fallback Behavior

If a user's role doesn't exactly match a handler, the system checks lower-privilege handlers:

helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_READ_ADMIN: helpers.StandardRequestWrapper(adminGet),
    constants.ROLE_ANY_AUTHORIZED: helpers.StandardRequestWrapper(authGet),
})

Examples:

  • User with ROLE_ADMIN (100) → Uses ROLE_READ_ADMIN handler (fallback)
  • User with ROLE_READ_ADMIN (90) → Uses ROLE_READ_ADMIN handler (exact match)
  • User with ROLE_ANY_AUTHORIZED (0) → Uses ROLE_ANY_AUTHORIZED handler (exact match)
  • Unauthenticated user → Returns 401 Unauthorized

Session Context

The RoleHandler automatically injects the session into the request context, making it available via:

userSession := helpers.GetReqSession(req)

Session Fields:

type Session struct {
    User       coremodel.Model // thin wrapper over session data if you only need the users ID, i.e. sessionObj.User.ID(), or used to save data so we can track who saved it.
	LoadedUser any // fully loaded user from the database, dont access directly, use the helper.GetLoadedUser(req)
}

Common Role Patterns

Admin-Only Endpoints

Full admin access required:

r.Post("/", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ADMIN: helpers.StandardRequestWrapper(adminCreate),
}))

r.Put("/{id}", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ADMIN: helpers.StandardRequestWrapper(adminUpdate),
}))

r.Delete("/{id}", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ADMIN: helpers.StandardRequestWrapper(adminDelete),
}))

Read-Only Admin Access

Both full admins and read-only admins can access:

r.Get("/", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_READ_ADMIN: helpers.StandardRequestWrapper(adminIndex),
}))

r.Get("/{id}", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_READ_ADMIN: helpers.StandardRequestWrapper(adminGet),
}))

r.Get("/count", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_READ_ADMIN: helpers.StandardRequestWrapper(adminCount),
}))

Authenticated User Endpoints

Any authenticated user can access:

r.Get("/", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ANY_AUTHORIZED: helpers.StandardPublicRequestWrapper(authIndex),
}))

r.Get("/{id}", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ANY_AUTHORIZED: helpers.StandardPublicRequestWrapper(authGet),
}))

Mixed Role Handlers

Different handlers for different roles on the same route:

r.Get("/{id}", helpers.RoleHandler(helpers.RoleHandlerMap{
    constants.ROLE_ADMIN: helpers.StandardRequestWrapper(adminGetFull),
    constants.ROLE_ANY_AUTHORIZED: helpers.StandardPublicRequestWrapper(authGetLimited),
}))

Example:

  • Admin users → Get full details via adminGetFull
  • Regular users → Get limited details via authGetLimited