Managing Permissions (Internal)

The Jeak framework offers an API for managing and checking user and group permissions for plugins and the TS3 server. Both permission implementations slightly differ from each other, which is why this page will focus on the internal permission service for use with plugin permissions.

🚧

Insufficient UX for inexperienced users

While the API and permission implementation are feature complete, we are working on a better user experience. We are planning on adding more commands or even a graphical application for permission management. Stay tuned for updates on that.

Checking a permission

Users and groups implement the ISubject interface which allows plugins to call #getPermission(String permName) and #hasPermission(String permName) on them to check whether or not a user or group is allowed to perform an action.
Permissions are named completely freely by the plugin that checks for their existence. Names are in no way enforced, although we suggest a scheme to follow,

How are permissions evaluated?

By default, permission lookups are transitive which means a check on a client will also evaluate whether or not the user is member of a group that has the permission in question.
In addition, groups can be dynamically assigned to any user by being linked to a TS3 server group. Therefore, any member of the server group on the TS3 server will automatically also be a member of the linked groups in the framework.
Note: It is not possible to remove members from a linked group without removing them from the TS3 server group.

How to set permissions?

Permissions are stored in the config directory in the permissions folder. The folder contains a file for each subject available and an _index.json.
Permissions can be modified programmatically by calling the respective #setPermission(...) and #removePermission(...) methods on the respective subject.
(Keep in mind that removing permissions on a subject does not remove them if the permission is set transitively too.)

Administrators can use several commands to modify subjects and permissions:

• !perm-group-create <group-name>
• !perm-group-link <group-name> <ts3-servergroup-id>
• !perm-group-grant <group-name> <permission-name> [value]
  There is also the lookup command available to retrieve the subject UUIDs of users, groups and linked server groups:
• !permuuid-lookup [g:<group-name> | u:<user-name-part> | sg:<ts3-servergroup-id>]
  • No arguments: Returns your own subject UUID
  • g:<group-name>: Returns the UUID of the internal group with that name
  • u:<user-name-part>: Returns the UUIDs of all clients (online), matching the given name (this is compiled to regex)
  • sg:<ts3-servergroup-id>: Returns the UUIDs of all internal groups linked to the given server group

❗️

About permission file modification

While permissions can be modified by modification of the permission files, it is necessary for the framework to be stopped during file modification.
Otherwise, the changes may be overwritten by the automatic profile save worker.

Administrators (wildcards)

The framework supports users with wildcard permissions. These are specifically defined in the _index.json (the modification warning from above applies to this too).
The subject UUIDs of administrators can be stored inside the admins list, which will make them automatically inherit all internal permissions.

_index.json

{
  "groups": {
    "bdc0fa8e-beae-448f-8e2a-08349b907cd7": {
      "name":"test-group"
    }
  },
   "admins": [
     "187190e3-7efc-451e-a506-0695d7c0a12a"
   ]
}