Permissions FAQ

For server owners (open) For server owners (close)

Does this mean I don't need plugins to set permissions now?
Bukkit just provides the concept of permissions, you'll still need to get a plugin to tell bukkit which players should get which permissions when. Don't worry, SpaceManiac made a simple plugin that I'm recommending to use! http://forums.bukkit.org/threads/ad...-0-official-default-groups-plugin-1000.26785/

If you're a small server or group of people, you don't technically need a plugin for permissions. As long as the plugins you're using had set defaults then simply giving someone op should give them the permissions they'll need for op-related tasks.

How easy will it be to convert from (some old permission plugin) to Bukkits?
It would depend on the old permission system, but I am quite sure that people will make tools to help convert you over. If the developers of that plugin wish, they could even make the old api compatible with the new one to make the transition seamless.

Why is there a permissions.yml? I thought bukkit didn't save permissions?
Server owners can create their own permissions here which we believe will help make your lives easier with other plugins. The possibilities of the usefulness of this is quite extensive, but the most popular case would be that you can create a permission that contains other permissions that you assign people often, and then you only need to assign people this new permission.

For plugin developers (open) For plugin developers (close)

What does the Bukkit permission API consist of?
The API we are providing is just an API and minimal implementation. There is no groups system or ways to store permissions for players. We provide the concept of permissions and plugins will be required to still tell bukkit which permissions to give to who, and when.

Do I have to register my permissions in plugin.yml?
No. It's entirely optional to register permissions at all. However, I recommend that you do so that you may provide a description of each permissions and set a default. Also, you can set "shortcut" permissions in plugin.yml to let people easily pick groups of similar permissions using a single node.

Can I register permissions outside of plugin.yml?
Certainly! It's a simple getPluginManager().addPermission(new Permission(.....)). Note that this will throw an exception if there's already a permission registered with the given name.

How do I test if someone has a permission?
Easy! player.hasPermission("my.plugins.permission"). If they don't have it, this'll default to whatever the default value of the permission was (if it isn't registered, it'll default to false).

What defaults can be set?
You have the following 4 options: true, false, op, not op. The "op" default will be true if the player is op, and the opposite for "not op".

Bukkit has no group system, but I need to know what group they're in!
In almost every case that plugins need to know the group of a player, they're actually trying to figure out if they have permission to do something. In this case, please just use a permission and see if they have that!

In the other cases, which I can only think of being for display purposes (like a chat prefix) you will have to reference a plugin directly as normal. But I would still advise another approach to this, such as using permissions as normal.

For example, if you're trying to figure out which group should have which chat prefix, have a config file listing permission nodes -> prefixes. The server owner sets which node you should set on, and if someone has this node give them that prefix.

For everyone (open) For everyone (close)

What are "child permissions" and "parent permissions"?
Permissions may contain other permissions; we call these "parent" and "children". If you give someone a parent, they automatically have the children set as per the parents requests.

What happens if I give someone a parent permission, and set it to false?
It will invert the children. If a child was normally set to true inside the parent, then it will now be set to false (and vice-versa).

Why aren't there * permissions in this system?
Because we solved the issue that * was trying to work around. Now you can set entire groups at a time with parent/child permissions, and also permissions can default to op/notop. We advise plugin developers to create a * permission as a parent to assist users.

 

Yay! This should be useful for us server admins.

 

So am I correct in presuming that the concept of groups *can* still be used to gather permissions together in whatever the actual permissions provider is? Eg: the default plugin that you're saying SpaceManiac is working on, it could provide groups and group inheritance as a way to organize permission granting, but that structure would simply not be accessible via the permissions API.

Secondly, would you consider a simple form of a "fixed" permission? Eg:

PermissionCheck check = new PermissionCheck("my.plugins.permission");

for type-checking and storage, thus you could call check.allows(player), or would the Permission object itself work in this manner? This seems like it might not be terribly different from just storing the raw string, but if you could save any part of the string unpacking and lookup work, it might be of value. Thus instead of doing string manipulation each time, you would have a reference to the node or whatever where the actual player set is contained, and you could simply check for membership there.

 

Because permissions don't have to be defined, we store the permissions as strings for "who has what" lookups. So changing it to an object will make zero difference here, it's going to lookup a string regardless.

And you are correct, you can use whatever system you like to define who gets what (such as groups), it's just not something we will be providing. We decided to do this so that plugins can use any arbitrary system to define attachments; based on what world someone is in, based on their shoesize, or for 5 minutes after winning a lottery from some plugin.

 

I really quickly read over it. Please give examples on how a plugin developer is supposed to (if they choose to do so) write down the permissions in their plugin.yml file.

 

Code:

permissions:
    doorman.*:
        description: Gives access to all doorman commands
        children:
            doorman.kick: true
            doorman.ban: true
            doorman.knock: true
            doorman.denied: false
    doorman.kick:
        description: Allows you to kick a user
        default: op
    doorman.ban:
        description: Allows you to ban a user
        default: op
    doorman.knock:
        description: Knocks on the door!
        default: true
    doorman.denied:
        description: Prevents this user from entering the door

 

Great, thanks!

 

How will a permission specified in permissions.yml interact with a child permission that's generated at runtime?

A non-contrived example, is the warp system I use. Warps are named, and generate their own permission check. Is it acceptable to have in permissions.yml the following:

Code:

permissions:
    preoccupied.warp.*:
        description: Permission to use all warps

And may I then insert a "preoccupied.warp.nexus-skylands" permission as they are loaded from persistence in onLoad? Will preoccupied.warp.* still grant preoccupied.warp.nexus-skylands ?

 

You can't alter a permission after it's created, whether at runtime or bukkit.yml. For your case, I'd suggest the new perms default to true as normal, and just have an "override" permission which you check for before looking at those.

 

So you're suggesting that I would instead be effectively looking for preoccupied.warp.deny.[warpname]

And basically, the dotted notation isn't actually meaningful, right? You're not turning them into individual nodes to check for the * privilege, they're all just strings. So I could make up a permission named "foo_bar/BAZ.comma hello mom? * * I like Pie" and it wouldn't matter?

 

You could do that, but I'll go medieval on your ass and never recommend your plugin Please keep them in the notion of: pluginname.category.category.permission

 

Okay. That's why the "*" one doesn't automatically grant access to what would casually appear to be child nodes by name. "*" is just human notion in your system, where in previous systems (the Permissions plugin) it's a special node name. You could just as well have used "doorman.everything" in your example. That definitely would have tripped me up, thanks for clarifying.

Since that is so different from existing systems, it might be something you want to add to the FAQ.

 

Wait, you mean that if you fetch the permission, get its children, and add to that map, it won't be updated? That's a bit annoying... :/

 

That's a good point actually. Why are permissions immutable? What does that gain?

 

We would have to find every Permissible that contains the permission and recalculate their permissions, which would be a rather heavy task.

 

Grrr, why can't you use a Map that doesn't have the put method then... stupid badly-designed Java collections library...

 

wait, what? You just said it was a string lookup. What exactly is a permissible storing then?

 

https://github.com/Bukkit/Bukkit/bl...a/org/bukkit/permissions/PermissibleBase.java

 

A Permissible is a Player, not a Command, correct? Typically one checks whether an action is permissible, but it appears that the Permissible is where you put PermissionAttachments, which are how you grant a permission to something.

So a permission with children is really just a macro, not actually a hierarchy. Such that adding that permission not only adds itself, but it adds the "children" permissions. So the attachPermission of doorman.* in your example will in stick the "doorman.*" permission into the map with whatever value, and then will go through all of its "children" during the recalculate and grant all of them as well.

Thus, you need a back-reference of what PermissibleAttachments reference what permissions, in order to update just the correct permissions when children are added or removed. I think it's worth it, honestly, and not "heavy", especially considering the likely frequency of such modifications.

 

Yeah it's named badly but... Better suggestions? ;D

 

None come to mind immediately, I can definitely see why you wound up using that one, but it's still an unfortunately ambiguous term. Worth thinking about

Is the rest about correct in how the inner mechanisms work? Would it be worthwhile to maintain the backreference for updating macro'd attachements?

Also, is the event system going to wind up hooked into this? You've got executors for grant/revoke I see, which hints at that possibility.

 

Haven't checked it in depth, so if I'm wrong, please ignore, but why isn't there a default implementation for permission cluster templates aka groups?
Without this, I need to assign my 20 - 30 default permissions every user gets to every new user? Besides that this makes it hard to find the users that additionaly have single special permissions and the problem that you need to keep track with an additional solution of which permissions you need to assign and the problem that you might forget to assign them or make errors, this is also very wasteful with memory and possibly cpu cycles.
And even if you argue that Permissible may be additionally implemented by a group - failing to provide an implementation for this will just move the problem of x different permission systems to then x different group systems.

If I did overlook something obvious, please gently push me in the right direction

 

I think the idea is that the default plugin could support groups, but as it's not currently written, it doesn't support anything.

 

It's in the process of being written: https://github.com/SpaceManiac/PermissionsBukkit
And yes, it supports groups.

 

whoa <3

 

It seems a bit confusing. Being a simplified permissions system with no groups, does this mean some people will remain using Permissions plugin and the developement for that will continue? At least people are used to that.

Still, good work! Any ETA on implementing this?

 

Is there a way to get all the players in a certain group?
For example .getGroup("admins").getPlayers(); ??

 

I see it being entirely likely that Permissions will not be made obsolete, but plugin developers won't need to explicitly support it anymore as long as they write it to utilize the Bukkit permissions system for assigning permissions. I'm not sure what they would do about wildcards though; it might be difficult or even impossible to effectively implement them in terms of Bukkit permissions.

Not using permissions alone. A groups plugin may or may not provide that.

EDIT by Moderator: merged posts, please use the edit button instead of double posting.

 

Principal. That's what it is, a Security Principal.

I've been working on a "permissions" plugin for a bit now. I got stuck on domains/worlds and the related inheritance between groups and players within the domain context.

I'm trying to create a simplified interface for developers to gain standardized access control functionality. Access control lists to relate groups and players through discretionary (users/admins can alter easily) permissions on a specific object (think things like regions or wolves or...?) And domain/world wide privileges (how current "permissions" work) that control rights to perform certain commands/overall actions (things like kicking a player or disabling/enabling plugins, etc).

One of the main features I am trying to add was an abstract class for the "repository" which would control translating between different security systems (Permissions, GroupManager, native Bukkit, etc) and my plugin's wrapping classes. This would make it very dynamic/flexible to allow easy migration from other systems.

I'd love feedback from anyone interested in such functionality and I'm hoping this thread is the right place to bring this up and attract interested people. I'm a VERY new Java developer and have a lot of bad practices simply due to a lack of knowledge. I need to spend some time to look over the permission interface Dinnerbone just put out, but I'd clearly be working to integrate any inherent functionality Bukkit can supply.

https://github.com/EdGruberman/AccessControl

 

Not directly; again, don't think about this system the way we currently think about Permissions.

You can approach this in one of two ways:
1. Your plugin defines a permission node for an action, a command, a message, etc. Let's say it's myplugin.admin.messages.dingo which notifies admins that a dingo has eaten someone's babies. You'd just use your permissions-managing plugin to give this node to the user (or group, if your permissions-managing plugin supports groups) you want to see the message. This is more flexible, not all users who see this message need to be in the "admin" group, your admin group doesn't need to be called "admins" at all, and you don't even need to have a permissions manager that supports groups.

2. You'd create a permission in permissons.yml which flags the player as being in a certain group. Plugins are just going to have to be versatile enough to ask which node signifies someone who should be entitled.

In your plugins' config.yml, instead of asking "What group are your admins?" Stop assuming that everyone uses groups - servers of 5 people don't need groups and most likely won't use a plugin with group support. Instead, ask "what node do users have if they should be notified of <x> event?"

Here is some example YAML:

Code:

dingomeal:
   log: true
   ban: maybe
   notify:
      message: 'Dingos ate your babies!'
      permissions:
         - mycustomserverperm.mygroups.admins
         - mycustomserverperm.doesntmatter.what.you.call.it

In this example (remember, this is your plugin's config.yml, not a permissions.yml), when a "dingomeal" happens, I want my plugin to log (log: true), to ban the dingo who caused this event (ban: true), and send the message "Dingos ate your babies!" do anyone who has mycustomerserverperm.mygroups.admins and mycustomserverperm.doesntmatter.what.you.call.it permissions. Then, if my permissions-managing plugin uses groups, I just make sure one of those custom-defined server permission nodes is assigned to the admins group.

The first method is probably perferable; the second method is a bit backwards but it allows the server admins more control over naming the nodes. In either case, you've no need whatsoever to know what group a user is in; and if you really need to know, you should ask your user for the name of a custom server node that identifies users in that group.