gcasbin

README

Overview

This is a super simple middleware integrating with Gin and Casbin to implement RBAC in Gin apps.

Installation

$ go get github.com/xskit/gin-casbin

Usage

See examples.

SubjectFn

You will have to provide a custom function to look up the current subject in runtime when you initialize this middleware.

// SubjectFn is used to look up current subject in runtime.
// If it can not find anything, just return an empty string.
type SubjectFn func(c *gin.Context) string

I am pretty sure there are many ways to do this. I provided two examples using JWT and session respectively.

RequiresPermissions

This is one of the two core functionalities. You can use it to filter requests if the subjects don't have the required permissions.

func (am *CasbinMiddleware) RequiresPermissions(permissions []string, opts ...Option) gin.HandlerFunc

The first parameter is a slice of formatted strings representing required permissions. For example, "book:read" stands for the permission to read a book. Note that if you pass in an illegal string such as "bookread" or ":", it will abort immediately and respond HTTP 500.

RequiresRoles

This is the other core functionality. It is a little simpler than RequiresPermissions since you just need to specify what roles you expect the subjects to have.

func (am *CasbinMiddleware) RequiresRoles(requiredRoles []string, opts ...Option) gin.HandlerFunc

Documentation

Index

• Variables
• type CasbinMiddleware
  • func NewCasbinMiddleware(modelFile string, policyAdapter interface{}, subFn SubjectFn) (*CasbinMiddleware, error)
  • func NewCasbinMiddlewareFromEnforcer(e *casbin.Enforcer, subFn SubjectFn) (*CasbinMiddleware, error)
  • func (am *CasbinMiddleware) RequiresPermissions(permissions []string, opts ...Option) gin.HandlerFunc
  • func (am *CasbinMiddleware) RequiresRoles(requiredRoles []string, opts ...Option) gin.HandlerFunc
• type Logic
• type Option
  • func WithLogic(logic Logic) Option
• type SubjectFn

Variables

var (
	ErrSubFnNil = errors.New("subFn is nil")
)

Types

type CasbinMiddleware

type CasbinMiddleware struct {
	// contains filtered or unexported fields
}

func NewCasbinMiddleware

func NewCasbinMiddleware(modelFile string, policyAdapter interface{}, subFn SubjectFn) (*CasbinMiddleware, error)

NewCasbinMiddleware returns a new CasbinMiddleware using Casbin's Enforcer internally. modelFile is the file path to Casbin model file e.g. path/to/rbac_model.conf. policyAdapter can be a file or a DB adapter. File: path/to/basic_policy.csv MySQL DB: mysqladapter.NewDBAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/") subFn is a function that looks up the current subject in runtime and returns an empty string if nothing found.

func NewCasbinMiddlewareFromEnforcer

func NewCasbinMiddlewareFromEnforcer(e *casbin.Enforcer, subFn SubjectFn) (*CasbinMiddleware, error)

Create from given Enforcer.

func (*CasbinMiddleware) RequiresPermissions

func (am *CasbinMiddleware) RequiresPermissions(permissions []string, opts ...Option) gin.HandlerFunc

RequiresPermissions tries to find the current subject by calling SubjectFn and determine if the subject has the required permissions according to predefined Casbin policies. permissions are formatted strings. For example, "file:read" represents the permission to read a file. opts is some optional configurations such as the logical operator (default is AND) in case multiple permissions are specified.

func (*CasbinMiddleware) RequiresRoles

func (am *CasbinMiddleware) RequiresRoles(requiredRoles []string, opts ...Option) gin.HandlerFunc

RequiresPermissions tries to find the current subject by calling SubjectFn and determine if the subject has the required roles according to predefined Casbin policies. opts is some optional configurations such as the logical operator (default is AND) in case multiple roles are specified.

type Logic

type Logic int

Logic is the logical operation (AND/OR) used in permission checks in case multiple permissions or roles are specified.

const (
	AND Logic = iota
	OR
)

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is used to change some default behaviors.

func WithLogic

func WithLogic(logic Logic) Option

WithLogic sets the logical operator used in permission or role checks.

type SubjectFn

type SubjectFn func(c *gin.Context) string

SubjectFn is used to look up current subject in runtime. If it can not find anything, just return an empty string.