authority

README

Authority

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

Features

• Create Roles
• Create Permissions
• Assign Permissions to Roles
• Assign Multiple Roles to Users
• Check User's Roles
• Check User's Permissions
• Check Role's Permissions
• Revoke User's Roles
• Revoke User's Permissions
• Revoke Role's permissions
• List User's Roles
• List All Roles
• List All Permissions
• Delete Roles
• Delete Permissions

Install

First get authority

go get github.com/parsidev/authority

Usage

To initiate authority you need to pass two variables the first one is the the database table names prefix

// initiate the database
db, err := mongo.Connect(context.Background(), options.Client().ApplyURI("mongodb://localhost:27017"))

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

// create role
err := auth.CreateRole("role-1")

// create permissions
err := auth.CreatePermission("permission-1")
err = auth.CreatePermission("permission-2")
err = auth.CreatePermission("permission-3")

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

// assign a role to user (user id = 1) 
err = auth.AssignRole(ObjectID("60ddddc63fb2aa8c3df9cf36"), "role-a")

// check if the user have a given role
ok, err := auth.CheckRole(ObjectID("60ddddc63fb2aa8c3df9cf36"), "role-a")

// check if a user have a given permission 
ok, err := auth.CheckPermission(ObjectID("60ddddc63fb2aa8c3df9cf36"), "permission-d")

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

Docs

func New(opts Options) *Authority

New initiates authority

db, err := mongo.Connect(context.Background(), options.Client().ApplyURI("mongodb://localhost:27017"))

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

func Resolve() *Authority

Resolve returns the initiated instance

auth := authority.Resolve()

func (a *Authority) CreateRole(roleName string) error

CreateRole stores a role in the database it accepts the role name. it returns an error incase of any

// create role
err := auth.CreateRole("role-1")

func (a *Authority) CreatePermission(permName string) error

CreatePermission stores a permission in the database it accepts the permission name. it returns an error in case of any

// create permissions
err := auth.CreatePermission("permission-1")
err = auth.CreatePermission("permission-2")
err = auth.CreatePermission("permission-3")

func (a *Authority) AssignPermissions(roleName string, permNames []string) error

AssignPermissions assigns a group of permissions to a given role it accepts in the first parameter the role name, it returns an error if there is not matching record of the role name in the database. the second parameter is a slice of strings which represents a group of permissions to be assigned to the role. if any of these permissions doesn't have a matching record in the database, the operations stops, changes reverted and an error is returned. in case of success nothing is returned

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

func (a *Authority) AssignRole(userID uint, roleName string) error

AssignRole assigns a given role to a user, you can assign multiple roles to a user, the first parameter is the user id, the second parameter is the role name. if the role name doesn't have a matching record in the database an error is returned.

// assign a role to user (user id) 
err = auth.AssignRole(ObjectID("60ddddc63fb2aa8c3df9cf36"), "role-a")

func (a *Authority) CheckRole(userID uint, roleName string) (bool, error)

CheckRole checks if a role is assigned to a user. it accepts the user id as the first parameter. the role as the second parameter. it returns an error if the role is not present in database

// check if the user have a given role
ok, err := auth.CheckRole(ObjectID("60ddddc63fb2aa8c3df9cf36"), "role-a")

func (a *Authority) CheckPermission(userID uint, permName string) (bool, error)

CheckPermission checks if a permission is assigned to the role that's assigned to the user. it accepts the user id as the first parameter. the permission as the second parameter. it returns an error if the permission is not present in the database

// check if a user have a given permission 
ok, err := auth.CheckPermission(ObjectID("60ddddc63fb2aa8c3df9cf36"), "permission-d")

func (a *Authority) CheckRolePermission(roleName string, permName string) (bool, error)

CheckRolePermission checks if a role has the permission assigned. it accepts the role as the first parameter. it accepts the permission as the second parameter. it returns an error if the role is not present in database. it returns an error if the permission is not present in database

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

func (a *Authority) RevokeRole(userID uint, roleName string) error

RevokeRole revokes a user's role. it returns a error in case of any

err = auth.RevokeRole(ObjectID("60ddddc63fb2aa8c3df9cf36"), "role-a")

func (a *Authority) RevokePermission(userID uint, permName string) error

RevokePermission revokes a permission from the user's assigned role. it returns an error in case of any

err = auth.RevokePermission(ObjectID("60ddddc63fb2aa8c3df9cf36"), "permission-a")

func (a *Authority) RevokeRolePermission(roleName string, permName string) error

RevokeRolePermission revokes a permission from a given role it returns an error in case of any

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

func (a *Authority) GetRoles() ([]string, error)

GetRoles returns all stored roles

roles, err := auth.GetRoles()

(a *Authority) GetUserRoles(userID uint) ([]string, error)

GetUserRoles returns user assigned roles

roles, err := auth.GetUserRoles(ObjectID("60ddddc63fb2aa8c3df9cf36"))

func (a *Authority) GetPermissions() ([]string, error)

GetPermissions retuns all stored permissions

permissions, err := auth.GetPermissions()

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

DeleteRole deletes a given role. if the role is assigned to a user it returns an error

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

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

DeletePermission deletes a given permission. if the permission is assigned to a role it returns an error

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

Documentation

Index

• type Authority
  • func New(opts Options) *Authority
  • func Resolve() *Authority
  • func (a *Authority) AssignPermissions(roleName string, permNames []string) error
  • func (a *Authority) AssignRole(userID primitive.ObjectID, roleName string) error
  • func (a *Authority) CheckPermission(userID primitive.ObjectID, permName string) bool
  • func (a *Authority) CheckRole(userID primitive.ObjectID, roleName string) bool
  • func (a *Authority) CheckRolePermission(roleName string, permName string) bool
  • func (a *Authority) CreatePermission(permName string) error
  • func (a *Authority) CreateRole(roleName string) error
  • func (a *Authority) DeletePermission(permName string) error
  • func (a *Authority) DeleteRole(roleName string) error
  • func (a *Authority) GetPermissionTableName() string
  • func (a *Authority) GetPermissions() []string
  • func (a *Authority) GetRolePermissionTableName() string
  • func (a *Authority) GetRoleTableName() string
  • func (a *Authority) GetRoles() ([]string, error)
  • func (a *Authority) GetUserRoleTableName() string
  • func (a *Authority) GetUserRoles(userID primitive.ObjectID) []string
  • func (a *Authority) RevokePermission(userID primitive.ObjectID, permName string) error
  • func (a *Authority) RevokeRole(userID primitive.ObjectID, roleName string) error
  • func (a *Authority) RevokeRolePermission(roleName string, permName string) error
• type Options
• type Permission
  • func (p Permission) TableName() string
• type Role
  • func (r Role) TableName() string
• type RolePermission
  • func (r RolePermission) TableName() string
• type UserRole
  • func (u UserRole) TableName() string

Types

type Authority

type Authority struct {
	DB *mongo.Database
}

Authority helps deal with permissions

func New

func New(opts Options) *Authority

New initiates authority

func Resolve

func Resolve() *Authority

Resolve returns the initiated instance

func (*Authority) AssignPermissions

func (a *Authority) AssignPermissions(roleName string, permNames []string) error

AssignPermissions assigns a group of permissions to a given role it accepts in the first parameter the role name, it returns an error if there is not matching record of the role name in the database. the second parameter is a slice of strings which represents a group of permissions to be assigned to the role if any of these permissions doesn't have a matching record in the database the operations stops, changes reverted and error is returned in case of success nothing is returned

func (*Authority) AssignRole

func (a *Authority) AssignRole(userID primitive.ObjectID, roleName string) error

AssignRole assigns a given role to a user the first parameter is the user id, the second parameter is the role name if the role name doesn't have a matching record in the data base an error is returned if the user have already a role assigned to him an error is returned

func (*Authority) CheckPermission

func (a *Authority) CheckPermission(userID primitive.ObjectID, permName string) bool

CheckPermission checks if a permission is assigned to the role that's assigned to the user. it accepts the user id as the first parameter the permission as the second parameter it returns an error if the permission is not present in the database

func (*Authority) CheckRole

func (a *Authority) CheckRole(userID primitive.ObjectID, roleName string) bool

CheckRole checks if a role is assigned to a user it accepts the user id as the first parameter the role as the second parameter it returns an error if the role is not present in database

func (*Authority) CheckRolePermission

func (a *Authority) CheckRolePermission(roleName string, permName string) bool

CheckRolePermission checks if a role has the permission assigned it accepts the role as the first parameter it accepts the permission as the second parameter it returns an error if the role is not present in database it returns an error if the permission is not present in database

func (*Authority) CreatePermission

func (a *Authority) CreatePermission(permName string) error

CreatePermission stores a permission in the database it accepts the permission name. it returns an error in case of any

func (*Authority) CreateRole

func (a *Authority) CreateRole(roleName string) error

CreateRole stores a role in the database it accepts the role name. it returns an error inCase of any

func (*Authority) DeletePermission

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

DeletePermission deletes a given permission if the permission is assigned to a role it returns an error

func (*Authority) DeleteRole

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

DeleteRole deletes a given role if the role is assigned to a user it returns an error

func (*Authority) GetPermissionTableName

func (a *Authority) GetPermissionTableName() string

func (*Authority) GetPermissions

func (a *Authority) GetPermissions() []string

GetPermissions returns all stored permissions

func (*Authority) GetRolePermissionTableName

func (a *Authority) GetRolePermissionTableName() string

func (*Authority) GetRoleTableName

func (a *Authority) GetRoleTableName() string

func (*Authority) GetRoles

func (a *Authority) GetRoles() ([]string, error)

GetRoles returns all stored roles

func (*Authority) GetUserRoleTableName

func (a *Authority) GetUserRoleTableName() string

func (*Authority) GetUserRoles

func (a *Authority) GetUserRoles(userID primitive.ObjectID) []string

GetUserRoles returns all user assigned roles

func (*Authority) RevokePermission

func (a *Authority) RevokePermission(userID primitive.ObjectID, permName string) error

RevokePermission revokes a permission from the user's assigned role it returns an error in case of any

func (*Authority) RevokeRole

func (a *Authority) RevokeRole(userID primitive.ObjectID, roleName string) error

RevokeRole revokes a user's role it returns a error in case of any

func (*Authority) RevokeRolePermission

func (a *Authority) RevokeRolePermission(roleName string, permName string) error

RevokeRolePermission revokes a permission from a given role it returns an error in case of any

type Options

type Options struct {
	TablesPrefix string
	DatabaseName string
	DB           *mongo.Client
}

Options has the options for initiating the package

type Permission

type Permission struct {
	ID   primitive.ObjectID `bson:"_id"`
	Name string             `bson:"name"`
}

Permission represents the database model of permissions

func (Permission) TableName

func (p Permission) TableName() string

TableName sets the table name

type Role

type Role struct {
	ID   primitive.ObjectID `bson:"_id"`
	Name string             `bson:"name"`
}

Role represents the database model of roles

func (Role) TableName

func (r Role) TableName() string

TableName sets the table name

type RolePermission

type RolePermission struct {
	ID           primitive.ObjectID `bson:"_id"`
	RoleID       primitive.ObjectID `bson:"role_id"`
	PermissionID primitive.ObjectID `bson:"permission_id"`
}

RolePermission stores the relationship between roles and permissions

func (RolePermission) TableName

func (r RolePermission) TableName() string

TableName sets the table name

type UserRole

type UserRole struct {
	ID     primitive.ObjectID `bson:"_id"`
	UserID primitive.ObjectID `bson:"user_id"`
	RoleID primitive.ObjectID `bson:"role_id"`
}

UserRole represents the relationship between users and roles

func (UserRole) TableName

func (u UserRole) TableName() string

TableName sets the table name