authority

Authority

Role Based Access Control (RBAC) Go package with database persistence

Features

• Database Transactions
• Create Roles
• Create Permissions
• Assign Permissions to Roles
• Supports Assigning Multiple Roles to Users
• Check if a user have a given roles
• Check if a user have a given permission
• Check if a role have a given permission
• Revoke User's Roles
• Revoke Role's permissions
• List all roles assigned to a given user
• List all roles in the database
• List all permissions assigned to a given role
• List all Permissions in the database
• Delete a given role
• Delete a given permission

Install

1. Go get the package

go get github.com/harranali/authority

1. Authority uses the orm gorm to communicate with the database. gorm needs a database driver in order to work properly. you can install the database driver by runnig a command from the list below, for example if you are using mysql database, simply run go get gorm.io/driver/mysql and so.

# mysql 
go get gorm.io/driver/mysql 
# or postgres
go get gorm.io/driver/postgres
# or sqlite
go get gorm.io/driver/sqlite
# or sqlserver
go get gorm.io/driver/sqlserver
# or clickhouse
go get gorm.io/driver/clickhouse

Usage

To initiate authority you need to pass two variables the first one is the the database table names prefix, the second is an instance of gorm

// initiate the database (using mysql)
dsn := "dbuser:dbpassword@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{})

// initiate authority
auth := authority.New(authority.Options{
    TablesPrefix: "authority_",
    DB:           db,
})

// create role
err = auth.CreateRole(authority.Role{
	Name: "Role 1",
	Slug: "role-1",
})

// create permissions
err = auth.CreatePermission(authority.Permission{
	Name: "Permission 1",
	Slug: "permission-1",
})
err = auth.CreatePermission(authority.Permission{
	Name: "Permission 2",
	Slug: "permission-2",
})
err = auth.CreatePermission(authority.Permission{
	Name: "Permission 3",
	Slug: "permission-3",
})

// assign the permissions to the role
err = auth.AssignPermissionsToRole("role-1", []string{
	"permission-1",
	"permission-2",
	"permission-3",
})

// assign a role to user (user id = 1)
err = auth.AssignRoleToUser(1, "role-1")

// check if the user have a given role
ok, err := auth.CheckUserRole(1, "role-a")
if ok {
	fmt.Println("yes, user has the role assigned")
}

// check if a user have a given permission
ok, err = auth.CheckUserPermission(1, "permission-d")
if ok {
	fmt.Println("yes, user has the permission assigned")
}

// check if a role have a given permission
ok, err = auth.CheckRolePermission("role-a", "permission-a")
if ok {
	fmt.Println("yes, role has the permission assigned")
}

Docs

func New(opts Options) *Authority

New initiates authority

dsn := "dbuser:dbpassword@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{})

auth := authority.New(authority.Options{
    TablesPrefix: "authority_",
    DB:           db,
})

func Resolve() *Authority

Resolve returns the initiated instance

auth := authority.Resolve()

func (a *Authority) CreateRole(r authority.Role) error

Add a new role to the database it accepts the Role struct as a parameter it returns an error in case of any it returns an error if the role is already exists

// create role
err = auth.CreateRole(authority.Role{
	Name: "Role 1",
	Slug: "role-1",
})

func (a *Authority) CreatePermission(p authority.Permission) error

Add a new permission to the database it accepts the Permission struct as a parameter it returns an error in case of any it returns an error if the permission is already exists

// create a permission
err = auth.CreatePermission(authority.Permission{
	Name: "Permission 1",
	Slug: "permission-1",
})

func (a *Authority) AssignPermissionsToRole(roleSlug string, permSlugs []string) error

Assigns a group of permissions to a given role it accepts the the role slug as the first parameter the second parameter is a slice of permission slugs (strings) to be assigned to the role it returns an error in case of any it returns an error in case the role does not exists it returns an error in case any of the permissions does not exists it returns an error in case any of the permissions is already assigned

// assign the permissions to the role
err := auth.AssignPermissions("role-1", []string{
    "permission-1",
    "permission-2",
    "permission-3",
})

func (a *Authority) AssignRoleToUser(userID interface{}, roleSlug string) error

Assigns a role to a given user it accepts the user id as the first parameter the second parameter the role slug it returns an error in case of any it returns an error in case the role does not exists it returns an error in case the role is already assigned

// assign a role to user (user id) 
err = auth.AssignRoleToUser(1, "role-a")

func (a *Authority) CheckUserRole(userID interface{}, roleSlug string) (bool, error)

Checks if a role is assigned to a user it accepts the user id as the first parameter the second parameter the role slug it returns two parameters the first parameter of the return is a boolean represents whether the role is assigned or not the second is an error in case of any in case the role does not exists, an error is returned

// check if the user have a given role
ok, err := auth.CheckUserRole(1, "role-a")

func (a *Authority) CheckUserPermission(userID interface{}, permSlug string) (bool, error)

Checks if a permission is assigned to a user it accepts in the user id as the first parameter the second parameter the role slug it returns two parameters the first parameter of the return is a boolean represents whether the role is assigned or not the second is an error in case of any in case the role does not exists, an error is returned

// check if a user have a given permission 
ok, err := auth.CheckUserPermission(1, "permission-d")

func (a *Authority) CheckRolePermission(roleSlug string, permSlug string) (bool, error)

Checks if a permission is assigned to a role it accepts in the role slug as the first parameter the second parameter the permission slug it returns two parameters the first parameter of the return is a boolean represents whether the permission is assigned or not the second is an error in case of any in case the role does not exists, an error is returned in case the permission does not exists, an error is returned

// check if a role have a given permission
ok, err := auth.CheckRolePermission("role-a", "permission-a")

func (a *Authority) RevokeUserRole(userID interface{}, roleSlug string) error

Revokes a user's role it returns a error in case of any in case the role does not exists, an error is returned

err = auth.RevokeUserRole(1, "role-a")

func (a *Authority) RevokeRolePermission(roleSlug string, permSlug string) error

Revokes a roles's permission it returns a error in case of any in case the role does not exists, an error is returned in case the permission does not exists, an error is returned

err = auth.RevokeRolePermission("role-a", "permission-a")

func (a *Authority) GetAllRoles() ([]Role, error)

Returns all stored roles it returns an error in case of any

roles, err := auth.GetAllRoles()

func (a *Authority) GetUserRoles(userID interface{}) ([]Role, error)

Returns all user assigned roles it returns an error in case of any

roles, err := auth.GetUserRoles(1)

func (a *Authority) GetRolePermissions(roleSlug string) ([]Permission, error)

Returns all role assigned permissions it returns an error in case of any

permissions, err := auth.GetRolePermissions("role-a")

func (a *Authority) GetAllPermissions() ([]Permission, error)

Returns all stored permissions it returns an error in case of any

permissions, err := auth.GetAllPermissions()

func (a *Authority) DeleteRole(roleSlug string) error

Deletes a given role even if it's has assigned permissions it first deassign the permissions and then proceed with deleting the role it accepts the role slug as a parameter it returns an error in case of any if the role is assigned to a user it returns an error

err := auth.DeleteRole("role-b")

func (a *Authority) DeletePermission(permSlug string) error

Deletes a given permission it accepts the permission slug as a parameter it returns an error in case of any if the permission is assigned to a role it returns an error

err := auth.DeletePermission("permission-c")

Transactions

authority supports database transactions by implementing 3 methods BeginTX(), Rollback(), and Commit() here is an example of how to use transactions

// begin a transaction session
tx := auth.BeginTX()
// create role
err = tx.CreateRole(authority.Role{
	Name: "Role 1",
	Slug: "role-1",
})
if err != nil {
    tx.Rollback() // transaction rollback incase of error
    fmt.Println("error creating role", err)
}

// create permissions
err = tx.CreatePermission(authority.Permission{
	Name: "Permission 1",
	Slug: "permission-1",
})
if err != nil {
    tx.Rollback() // transaction rollback incase of error
    fmt.Println("error creating permission", err)
}

// assign the permissions to the role
err = tx.AssignPermissionsToRole("role-1", []string{
	"permission-1",
	"permission-2",
	"permission-3",
})

if err != nil {
    tx.Rollback() // transaction rollback incase of error
    fmt.Println("error assigning permission to role", err)
}
// assign a role to user (user id = 1)
err = tx.AssignRoleToUser(1, "role-1")
if err != nil {
    tx.Rollback() // transaction rollback incase of error
    fmt.Println("error assigning role to user", err)
}

// commit the operations to the database
tx.Commit()