Permissions

The permissions system in go-advanced-admin is a crucial component that controls access to various parts of the admin panel. It allows you to define who can view, create, update, or delete resources within your application.

Important: If you do not set up the permissions correctly, users may find the admin panel empty or lacking content. It's essential to implement the permission checker function to ensure that the appropriate content is displayed to the right users.

This guide covers:

Understanding the Permission Checker Function
Building a Custom Permission Checker
Permission Schemes
- Role-Based Permissions
- Attribute-Based Permissions
Integration with Authentication Systems
Common Pitfalls
Troubleshooting Empty Panels
Next Steps

Understanding the Permission Checker Function

At the core of the permissions system is the Permission Checker Function. This function determines whether a user has the necessary permissions to perform specific actions within the admin panel.

Function Signature

type PermissionFunc func(PermissionRequest, interface{}) (bool, error)

PermissionRequest: Contains details about the requested action.
interface{}: The context, typically representing the current request.
Returns: A boolean indicating whether the action is allowed, and an error if applicable.

PermissionRequest Structure

type PermissionRequest struct {
    AppName    *string
    ModelName  *string
    InstanceID interface{}
    Action     *Action
}

AppName: The name of the application.
ModelName: The name of the model.
InstanceID: The ID of the specific instance (if applicable).
Action: The action being requested (e.g., read, create, update, delete).

Actions

The actions are defined as constants:

const (
    ReadAction    Action = "read"
    CreateAction  Action = "create"
    UpdateAction  Action = "update"
    DeleteAction  Action = "delete"
    LogViewAction Action = "log_view"
)

Building a Custom Permission Checker

To effectively use the admin panel, you need to implement the PermissionFunc. Here's how to build a custom permission checker that aligns with your application's requirements.

Step-by-Step Guide

Define the Permission Checker Function
Create a function that matches the PermissionFunc signature.
func MyPermissionChecker( req admin.PermissionRequest, ctx interface{}, ) (bool, error) { // Your permission logic goes here }
Access User Information
Extract the current user or request context from the ctx parameter. This often involves type asserting ctx to your specific context type.
user, ok := ctx.(*User) if !ok { return false, errors.New("invalid context") }
Implement Permission Logic
Based on the PermissionRequest, determine if the user has the necessary permissions.
switch *req.Action { case admin.ReadAction: // Logic for read permissions case admin.CreateAction: // Logic for create permissions case admin.UpdateAction: // Logic for update permissions case admin.DeleteAction: // Logic for delete permissions default: return false, nil }
Return the Permission Decision
Return true if the action is allowed, false otherwise. Include an error if applicable.
if user.HasPermission(*req.Action, req.AppName, req.ModelName) { return true, nil } return false, nil
Handle Errors Appropriately
If an error occurs during permission checking, return false and the error.
if err != nil { return false, err }
Register the Permission Checker
When initializing the admin panel, provide your custom permission checker function.
panel, err := admin.NewPanel(ormIntegrator, webIntegrator, MyPermissionChecker, &admin.Config{ // Your configuration options }) if err != nil { log.Fatalf("Failed to create admin panel: %v", err) }

Note: Without a proper permission checker function, the admin panel will not display any content to users, as all actions will be denied by default.

Permission Schemes

Implementing an effective permission scheme is crucial for both security and usability. Here are two common approaches:

Role-Based Permissions

Role-based permissions assign access rights to users based on their roles (e.g., admin, editor, viewer).

Example:

func RoleBasedPermissionChecker(
    req admin.PermissionRequest, ctx interface{}, 
) (bool, error) {
    user, ok := ctx.(*User)
    if !ok {
        return false, errors.New("invalid context")
    }

    switch user.Role {
    case "admin":
        // Admins have all permissions
        return true, nil
    case "editor":
        // Editors can read and update
        if *req.Action == admin.ReadAction || *req.Action == admin.UpdateAction {
            return true, nil
        }
    case "viewer":
        // Viewers can only read
        if *req.Action == admin.ReadAction {
            return true, nil
        }
    }

    // Deny all other actions
    return false, nil
}

Attribute-Based Permissions

Attribute-based permissions consider specific attributes of the user or the resource to determine access rights.

Example:

func AttributeBasedPermissionChecker(
    req admin.PermissionRequest, ctx interface{}, 
) (bool, error) {
    user, ok := ctx.(*User)
    if !ok {
        return false, errors.New("invalid context")
    }

    // Allow users to read their own data
    if *req.Action == admin.ReadAction && req.InstanceID == user.ID {
        return true, nil
    }

    // Additional attribute-based logic
    // ...

    // Deny by default
    return false, nil
}

Integration with Authentication Systems

To make effective permission decisions, your permission checker needs to access user information from your authentication system.

Steps to Integrate

Pass User Information via Context
Ensure that the ctx parameter provided to the permission checker includes the authenticated user.
Modify Your Web Integrator
Adjust your web integrator to include user information in the context passed to the admin panel handlers.
Example with Gin:
func MyGinWebIntegrator() admin.WebIntegrator { return &GinWebIntegrator{ // Implementation details } } // Within your Gin handlers, set the user in the context func (gi *GinWebIntegrator) HandleRoute( method, path string, handler admin.HandlerFunc, ) { gi.router.Handle(method, path, func(c *gin.Context) { user, err := AuthenticateUser(c) if err != nil { c.AbortWithStatus(http.StatusUnauthorized) return } // Pass the user to the handler statusCode, body := handler(user) c.String(int(statusCode), body) }) }

Common Pitfalls

Empty Admin Panel

Symptom: When accessing the admin panel, all pages appear empty.
Cause: The permission checker function is denying all actions, or not properly implemented.
Solution: Ensure your permission checker returns true for the actions and resources the user should have access to.

Incorrect Context Type

Symptom: Errors indicating invalid context or type assertion failures.
Cause: The ctx parameter does not contain the expected user or request information.
Solution: Verify that you're correctly passing the context with the necessary user information to the permission checker.

Unhandled Actions

Symptom: Users cannot perform certain actions despite having the correct permissions.
Cause: The permission checker does not handle all possible actions.
Solution: Ensure your permission checker includes cases for all relevant actions (ReadAction, CreateAction, UpdateAction, DeleteAction, etc.).

Troubleshooting Empty Panels

If the admin panel appears empty or certain sections are not visible, follow these steps:

Review Your Permission Checker
Confirm that your permission checker function correctly grants permissions for the intended actions and resources.
Check User Roles and Permissions
Ensure that the user has the appropriate roles or attributes assigned.
Inspect Logs
Look for any error messages or warnings in your application's logs that might indicate permission issues.
Test with Different Users
Try accessing the admin panel with users of different roles to determine if the issue is user-specific.
Validate Context Passing
Make sure that the user information is correctly passed through the context to the permission checker.

Next Steps

Implement and Test Your Permission Checker
Ensure that your permission logic aligns with your application's security requirements.
Explore Advanced Permission Schemes
Consider combining role-based and attribute-based permissions for more granular control.
Proceed to Configuration
Continue to the Configuration guide to further customize your admin panel.

Feedback and Support

If you encounter any issues or have questions regarding permissions, please:

Open an Issue: GitHub Issues
Contribute: Refer to our Contribution Guide if you'd like to contribute improvements.

Note: Properly setting up the permissions system is essential for the functionality of the admin panel. Without it, users may not see any content when accessing the main page or specific apps and models.

Return to Core Features or explore other topics in the documentation.

Thank you for using go-advanced-admin!

Last modified: 07 October 2024