Admin
The Admin plugin provides a set of administrative functions for user management in your application. It allows administrators to perform various operations such as creating users, managing user roles, banning/unbanning users, impersonating users, and more.
Installation
Migrate the database
Run the migration or generate the schema to add the necessary fields and tables to the database.
See the Schema section to add the fields manually.
Add the client plugin
Next, include the admin client plugin in your authentication client instance.
Usage
Before performing any admin operations, the user must be authenticated with an admin account. An admin is any user assigned the admin
role or any user whose ID is included in the adminUserIds
option.
Create User
Allows an admin to create a new user.
List Users
Allows an admin to list all users in the database.
By default, 100 users are returned. You can adjust the limit and offset using the following query parameters:
search
: The search query to apply to the users. It can be an object with the following properties:field
: The field to search on, which can beemail
orname
.operator
: The operator to use for the search. It can becontains
,starts_with
, orends_with
.value
: The value to search for.
limit
: The number of users to return.offset
: The number of users to skip.sortBy
: The field to sort the users by.sortDirection
: The direction to sort the users by. Defaults toasc
.filter
: The filter to apply to the users. It can be an array of objects.
Pagination
The listUsers
function supports pagination by returning metadata alongside the user list. The response includes the following fields:
How to Implement Pagination
To paginate results, use the total
, limit
, and offset
values to calculate:
- Total pages:
Math.ceil(total / limit)
- Current page:
(offset / limit) + 1
- Next page offset:
Math.min(offset + limit, (total - 1))
– The value to use asoffset
for the next page, ensuring it does not exceed the total number of pages. - Previous page offset:
Math.max(0, offset - limit)
– The value to use asoffset
for the previous page (ensuring it doesn’t go below zero).
Example Usage
Fetching the second page with 10 users per page:
Set User Role
Changes the role of a user.
Ban User
Bans a user, preventing them from signing in and revokes all of their existing sessions.
Unban User
Removes the ban from a user, allowing them to sign in again.
List User Sessions
Lists all sessions for a user.
Revoke User Session
Revokes a specific session for a user.
Revoke All Sessions for a User
Revokes all sessions for a user.
Impersonate User
This feature allows an admin to create a session that mimics the specified user. The session will remain active until either the browser session ends or it reaches 1 hour. You can change this duration by setting the impersonationSessionDuration
option.
Stop Impersonating User
To stop impersonating a user and continue with the admin account, you can use stopImpersonating
Remove User
Hard deletes a user from the database.
Access Control
The admin plugin offers a highly flexible access control system, allowing you to manage user permissions based on their role. You can define custom permission sets to fit your needs.
Roles
By default, there are two roles:
admin
: Users with the admin role have full control over other users.
user
: Users with the user role have no control over other users.
A user can have multiple roles. Multiple roles are stored as string separated by comma (",").
Permissions
By default, there are two resources with up to six permissions.
user:
create
list
set-role
ban
impersonate
delete
set-password
session:
list
revoke
delete
The admin have full control over all the resources and actions. The user have no control over any of those actions.
Custom Permissions
the plugin providers easy way to define your own set of permission for each role.
Create Access Control
You first need to create access controller by calling createAccessControl
function and passing the statement object. The statement object should have the resource name as the key and the array of actions as the value.
Create Roles
Once you have created the access controller you can create roles with the permissions you have defined.
When you create custom roles for existing roles, the predefined permissions for those roles will be overridden. To add the existing permissions to the custom role, you need to import defaultStatements
and merge it with your new statement, plus merge the roles' permissions set with the default roles.
Pass Roles to the Plugin
Once you have created the roles you can pass them to the organization plugin both on the client and the server.
You also need to pass the access controller and the roles to the client plugin.
Access Control Usage
Has Permission:
To check the permission of the user, you can use the hasPermission
function provided by the client.
If you want to use the server instead to check if a user has a permission, you can use userHasPermission
action provided by the api
to check the permission of the user.
Check Role Permission:
Once you have defined the roles and permissions to avoid checking the permission from the server you can use the checkRolePermission
function provided by the client.
Schema
This plugin adds the following fields to the user
table:
Field Name | Type | Key | Description |
---|---|---|---|
role | string | The user's role. Defaults to `user`. Admins will have the `admin` role. | |
banned | boolean | Indicates whether the user is banned. | |
banReason | string | The reason for the user's ban. | |
banExpires | number | The Unix timestamp when the user's ban will expire. |
And adds one field in the session
table:
Field Name | Type | Key | Description |
---|---|---|---|
impersonatedBy | string | The ID of the admin that is impersonating this session. |
Options
Default Role
The default role for a user. Defaults to user
.
Admin Roles
The roles that are considered admin roles. Defaults to ["admin"]
.
Any role that isn't in the adminRoles
list, even if they have the permission,
will not be considered an admin.
Admin userIds
You can pass an array of userIds that should be considered as admin. Default to []
If a user is in the adminUserIds
list, they will be able to perform any admin operation.
impersonationSessionDuration
The duration of the impersonation session in seconds. Defaults to 1 hour.
Default Ban Reason
The default ban reason for a user created by the admin. Defaults to No reason
.
Default Ban Expires In
The default ban expires in for a user created by the admin in seconds. Defaults to undefined
(meaning the ban never expires).
bannedUserMessage
The message to show when a banned user tries to sign in. Defaults to "You have been banned from this application. Please contact support if you believe this is an error."