Groups & Permissions
In advanced applications, access control can be managed through permissions and groups.
A permission gives a user the right to perform a given action (such as accessing a route).
A group brings together a set of users (a user can belong to more than one group).
Permissions can be attached to a user or a group. Attaching a permission to a group is equivalent to attaching the permission to each of its users.
Examples of groups are the "Free", "Pro" and "Enterprise" plans of a SaaS application. Depending of the price paid by the customers, they have access to certain features whose access are managed by permissions.
#
PermissionsPermission
Entity#
The Property name | Type | Database Link |
---|---|---|
id | number | Primary auto generated key |
name | string | |
codeName | string | Unique, Length: 100 |
#
Creating Permissions Programmatically#
Creating Permissions with a Shell Script (CLI)Create a new script with this command:
Replace the content of the new created file src/scripts/create-perm.ts
with the following:
Then you can create a permission through the command line.
#
GroupsGroups are used to categorize users. A user can belong to several groups and a group can have several users.
A group can have permissions. They then apply to all its users.
#
The Group EntityProperty name | Type | Database Link |
---|---|---|
id | number | Primary auto generated key |
name | string | Length: 80 |
codeName | string | Unique, Length: 100 |
permissions | Permission[] | A many-to-many relation with the table permission |
#
Creating Groups Programmatically#
Creating Groups with a Shell Script (CLI)Create a new script with this command:
Replace the content of the new created file src/scripts/create-group.ts
with the following:
Then you can create a group through the command line.
#
UsersUserWithPermissions
Entity#
The UserWithPermissions
is an abstract class that has useful features to handle access control through permissions and groups. You must extend your User
entity from this class to use permissions and groups.
Property name | Type | Database Link |
---|---|---|
id | number | Primary auto generated key |
groups | Group[] | A many-to-many relation with the table group |
userPermissions | Permission[] | A many-to-many relation with the table permission |
hasPerm
Method#
The The hasPerm(permissionCodeName: string)
method of the UserWithPermissions
class returns true if one of these conditions is true:
- The user has the required permission.
- The user belongs to a group that has the required permission.
#
Creating Users with Groups and Permissions with a Shell Script (CLI)Uncomment the code in the file src/scripts/create-user.ts
.
Then you can create a user with their permissions and groups through the command line.
#
Fetching a User with their PermissionsIf you want the hasPerm
method to work on the context user
property, you must use the fetchUserWithPermissions
function in the authentication hook.
Example with JSON Web Tokens
Example with Sessions Tokens
#
The PermissionRequired HookThis requires the use of
fetchUserWithPermissions
.
Context | Response |
---|---|
ctx.user is undefined | 401 - UNAUTHORIZED |
ctx.user.hasPerm('perm') is false | 403 - FORBIDDEN |
Context | Response |
---|---|
ctx.user is undefined | Redirects to /login (302 - FOUND) |
ctx.user.hasPerm('perm') is false | 403 - FORBIDDEN |
Example
#
BaseEntity InheritanceAvailable in Foal v1.8.0 onwards.
The classes Permission
, Group
and UserWithPermissions
all extends the BaseEntity
class so you can access its static and instance methods.
Example
#
Get All Users with a Given PermissionAvailable in Foal v1.8.0 onwards.
The class UserWithPermissions
provides a static method withPerm
to get all users with a given permission. It returns all users that have this permission on their own or through the groups they belong to.