SFS2X Docs / AdvancedTopics / privilege-manager
» User Privilege Manager
One common requirement in online applications is to provide a set of custom permissions for different types of users. Typically online games can handle guest users, registered users and maybe premium users. It is also quite common to have a profile for moderators and/or site administrators.
SmartFoxServer 2X provides a Privilege Manager within each Zone that can be customized to limit the interaction with the server. Each permission profile can set a list of denied API calls for each user from a specific category. For instance, we could prohibit the creation of Rooms and Room Variables for guest users and allow them only for registered users. Moderator and Administrator messages could be denied for everyone except those two privileged categories, etc.
Every profile in the Permission Manager is identified with a unique number. These IDs are freely assignable, however the first 4 are reserved and have a special meaning for the system:
- Id == 0: Guest user
- Id == 1: Registered user
- Id == 2: Moderator user
- Id == 3: Administrator user
There are no default settings provided for each of these profiles. The developer is free to customize these permissions to his likings. We should simply keep in mind that those four IDs are always recognized in the system as shown in the above list. For example if you are using this in your code:
User kermit = sfs.UserManager.GetUserByName("KermitTheFrog");
if (kermit.IsModerator())
{
// Allow some special action here...
}
var kermit = sfs.userManager.getUserByName("KermitTheFrog");
if (kermit.isModerator())
{
// Allow some special action here...
}
var kermit:User = sfs.userManager.getUserByName("KermitTheFrog");
if (kermit.isModerator())
{
// Allow some special action here...
}
Internally the API will actually check that profileId == 2.
You are also free to add any number of additional profiles and completely ignore the default ones that we have mentioned.
NOTE
The profile IDs are transmitted as a short integer (16 bit) so this means that there is a theoretical limit of 2^16 permission profiles, for each Zone.
» How to configure permission profiles
Configuring the permission profiles is a very simple operation. You just need to run the AdminTool, start the Zone Configurator module and choose the Zone where you want to edit the permissions. Under the Privilege Manager tab you will find the four standard profiles:
You will be able to edit any of these or add new ones:
The dual lists will enable you to add and remove any request from the denied list. In the lower part of the dialogue box you will be able to assign two other special flags:
- ExtensionCalls: activates the access to any Extension in the Zone; when turned off, users with the selected profile won't be able to use Extensions.
- SuperUser: when turned on it enables users with the selected profile to use Moderator/Administrator functions such as kicking, banning and sending mod/admin messages.
» How to use permission profiles
Assigning the proper Permission Profile to specific Users requires custom login logic. Usually the developer will manage the user data in a database or similar data source. At login time your Extension will be able to check the user credentials and finally set the proper Permission Id once the client is finally logged in the system.
The flow that we suggest is the following (for more informations check the Custom Login How To):
- In your init() extension method register for the USER_LOGIN server event.
- When USER_LOGIN is fired you can check the credentials against your data source and either allow or deny the access. If you allow the access you will also be able to store the permission profile in the Session properties. By convention there is a reserved property called $permission which is used to specify which permission ID the user will be assigned. For example:
session.setProperty("$permission", DefaultPermissionProfile.MODERATOR);
Now the User permissions are properly configured. Each time a request will be sent from the client side the Permission Manager will verify it against the user profile and determine if it can should be executed or rejected. In case the request is denied an error will be logged with the details.