Permission System Overview For MOD Authors
Description: A overview of permissions system that is geared towards MOD authors
In Categories: Modifications
- Link to this article: Select All
[url=https://www.phpbb.com/support/docs/en/3.0/kb/article/permission-system-overview-for-mod-authors/]Knowledge Base - Permission System Overview For MOD Authors[/url]
This guide is intended as a overview to the whole permissions system and where & what data gets stored and how its used. It is not meant to be a userguide to setting up permissions although it does cover it to some degree. I have tried to be 100% sure of all this information by checking everything I believed against the code ... but this is not an official document so there could be mistakes. If you spot any let me know. I wrote this because I think its a brilliant system and some people might like to know a little more without having to study the code themselves.
What is the permissions system?
It's the system that allows board administrator decide what users are allowed do on the board.
How does it work?
An administrator with the right permission (Yes ... A administrator needs the permission to set permissions
) has access to the administration control panel(ACP) which contains the administrative side of the permissions system. The administrator then setups the permissions to allow users have the rights to do certain thing tasks or see certain features. At the end of the day each permission is what is called a permission option and users obtain the rights to these options either directly or from a group or from a role that is assigned to them or a group they are in.
What are permission options?
These are the individual options that allow or deny you access to features. Examples are 'f_post', 'm_delete', 'a_ban' & 'u_sendpm'. What are those f_, m_, a_ & u_ bits in the options? These are what are called permission types.
What are permission types?
Permission types are groupings of permissions of the same type. f_ is the forum type. m_ is the moderator type. a_ is the administrator type & u_ is the user type.
Where are my own users permissions stored?
Your permissions are stored in the phpbb_users table
What fields are in the phpbb_users table that relate to permissions?
user_permissions - Holds the users permission. We will talk later how this gets filled and when it gets updated. user_perm_from - If you have the a_switchperm permission option then you can assume the permissions of another user. If you do that this field contains the user_id you have assumed the permissions of. Normally its 0
Where are permissions options stored?
They are stored in the table phpbb_acl_options.
What fields are there and what do they mean?
auth_option_id - Unique ID of option auth_option - permission option name is_global - Set to 1 if a global option else set to 0 is_local - Set to 1 if a local option else set to 0 founder_only - Set to 1 if a found only option else set to 0
What is a local permission option?
A local permission option is a option that can be granted to a user on a forum by forum basis. This allows you grant users options to perform a task in one forum but not another. They are also called forum based permissions.
What is a global permission option?
A global permission option is a option that is valid board wide.
Can a permission option be both global & local?
Yes. A option can be both. An example is 'm_edit' this is the moderator permission to edit a topic. You might grant it for a user to one forum. Another user might be given it board wide. To allow this the option is set to both local & global.
What is a founder only option?
A permission that only a founder can have.
Are any default phpBB permissions founder only?
No.
What is a founder?
A founder is a special type of user. It should only be granted to the most trusted of administrators. A founder can access the permission system to correct his permissions even if another administrator has removed his permissions. Only a founder can remove the founder status of another founder.
What are roles?
Roles are a predefined setup of permission options that can be applied to users or groups. If you change a roles permission options the users or groups assigned the role get updated automatically.
Where are roles stored?
They are stored in the table phpbb_acl_roles.
What fields are there and what do they mean?
role_id - Unique ID of option role_name - role name normally as a lang key role_description - role description normally as a lang key role_type - a_, u_, m_ or f_ depending on what role is for role_order - number indicating display order in the ACP
Where are the permission options for a role stored?
They are stored in the table phpbb_acl_roles_data.
What fields are there and what do they mean?
role_id - role id from phpbb_acl_roles auth_option_id - option id from phpbb_acl_options auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
What are these ACL_YES, ACL_NO & ACL_NEVER?
Your effective permission for any option is built up from a combination of details such as which groups you are a member of, which role you have assigned and whether you have been assigned directly that permission. As such you might have opposing permissions. The YES, NO & NEVER system works to allow phpBB combine your this different answers for a option and give you the effective permission. If anywhere you get a NEVER that will be your permission for that option ... a YES can not override a NEVER. However a YES does override a NO.
What happens if I have a global option set to NO but also the same option is local and set to YES?
This depends partly on how the check is done. If acl_get is called without a forum id then only the global will be checked. If a forum id is specified then the local option will be combined with the global one. If the local one is YES then so will the global one & vice versa. One thing to note is that when checking if a user has a permission the answer is only every YES or NO. The YES|NO|NEVER system is only used to build the YES|NO final setting. The example above is a good reminder that local & global permissions are different. There is also a check called acl_getf_global this is effective the same as acl_get().
If I assigned a role to a user where is that stored?
That is stored in the table phpbb_acl_users.
What fields are there and what do they mean?
user_id - user id from phpbb_users forum_id - forum id from phpbb_forums if a local option else 0 auth_option_id - option id from phpbb_acl_options auth_role_id - role id from phpbb_acl_roles if obtained from a role else 0 auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
If I assigned a role to a group where is that stored?
That is stored in the table phpbb_acl_groups.
What fields are there and what do they mean?
group_id - group id from phpbb_groups forum_id - forum id from phpbb_forums if a local option else 0 auth_option_id - option id from phpbb_acl_options auth_role_id - role id from phpbb_acl_roles if obtained from a role else 0 auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
So how do I setup permissions now I know the different parts that are involved?
First you need to decide if you what you are trying to achieve. If you need to set one user to have maybe just one extra permission option then doing it to the user direction might be OK. Otherwise its best to set permission options on a group and place the user in the group. Or if its a lot of permission options you are setting up then a role might be best. You also need to understand if the options are global or local. Setting global permissions From the "PERMISSIONS" tab select from "Users' permissions", "Groups' permissions", "Administrators" or "Global moderators". If you select either of the last two you will first need to select the forum for which you are trying to set. Setting local (forum) permissions Setting forum based (local) permissions From the "PERMISSIONS" tab select from "Forum permissions", "Forum Moderators", "Users' forum permissions" or "Group' forum permissions". If you select either of the last two you will first need to select the user/group and then the forum for which you are trying to set. Setting role permissions From the "PERMISSIONS" tab select from "Admin roles", "User roles", "Moderator roles" or "Forum roles".
When setting advanced permissions or defining roles what are those tabs?
Each of the tabs represents a permission category. Categories are used to further group permission options together.
So where in the ACP can permissions be setup?
The ACP can be configured to place this modules in multiple places. So while some of the ways are listed above there are others and the administrators can move them.
OK. So I have setup the permissions I think. How can I view what permissions a user/group will get?
You view what permissions a user/group has by viewing its permission mask.
This permissions guide is in two parts due a limitation on article lengths in the Knowledge base. The second part of this guide can be found here
What is the permissions system?
It's the system that allows board administrator decide what users are allowed do on the board.
How does it work?
An administrator with the right permission (Yes ... A administrator needs the permission to set permissions
) has access to the administration control panel(ACP) which contains the administrative side of the permissions system. The administrator then setups the permissions to allow users have the rights to do certain thing tasks or see certain features. At the end of the day each permission is what is called a permission option and users obtain the rights to these options either directly or from a group or from a role that is assigned to them or a group they are in.What are permission options?
These are the individual options that allow or deny you access to features. Examples are 'f_post', 'm_delete', 'a_ban' & 'u_sendpm'. What are those f_, m_, a_ & u_ bits in the options? These are what are called permission types.
What are permission types?
Permission types are groupings of permissions of the same type. f_ is the forum type. m_ is the moderator type. a_ is the administrator type & u_ is the user type.
Where are my own users permissions stored?
Your permissions are stored in the phpbb_users table
What fields are in the phpbb_users table that relate to permissions?
user_permissions - Holds the users permission. We will talk later how this gets filled and when it gets updated. user_perm_from - If you have the a_switchperm permission option then you can assume the permissions of another user. If you do that this field contains the user_id you have assumed the permissions of. Normally its 0
Where are permissions options stored?
They are stored in the table phpbb_acl_options.
What fields are there and what do they mean?
auth_option_id - Unique ID of option auth_option - permission option name is_global - Set to 1 if a global option else set to 0 is_local - Set to 1 if a local option else set to 0 founder_only - Set to 1 if a found only option else set to 0
What is a local permission option?
A local permission option is a option that can be granted to a user on a forum by forum basis. This allows you grant users options to perform a task in one forum but not another. They are also called forum based permissions.
What is a global permission option?
A global permission option is a option that is valid board wide.
Can a permission option be both global & local?
Yes. A option can be both. An example is 'm_edit' this is the moderator permission to edit a topic. You might grant it for a user to one forum. Another user might be given it board wide. To allow this the option is set to both local & global.
What is a founder only option?
A permission that only a founder can have.
Are any default phpBB permissions founder only?
No.
What is a founder?
A founder is a special type of user. It should only be granted to the most trusted of administrators. A founder can access the permission system to correct his permissions even if another administrator has removed his permissions. Only a founder can remove the founder status of another founder.
What are roles?
Roles are a predefined setup of permission options that can be applied to users or groups. If you change a roles permission options the users or groups assigned the role get updated automatically.
Where are roles stored?
They are stored in the table phpbb_acl_roles.
What fields are there and what do they mean?
role_id - Unique ID of option role_name - role name normally as a lang key role_description - role description normally as a lang key role_type - a_, u_, m_ or f_ depending on what role is for role_order - number indicating display order in the ACP
Where are the permission options for a role stored?
They are stored in the table phpbb_acl_roles_data.
What fields are there and what do they mean?
role_id - role id from phpbb_acl_roles auth_option_id - option id from phpbb_acl_options auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
What are these ACL_YES, ACL_NO & ACL_NEVER?
Your effective permission for any option is built up from a combination of details such as which groups you are a member of, which role you have assigned and whether you have been assigned directly that permission. As such you might have opposing permissions. The YES, NO & NEVER system works to allow phpBB combine your this different answers for a option and give you the effective permission. If anywhere you get a NEVER that will be your permission for that option ... a YES can not override a NEVER. However a YES does override a NO.
What happens if I have a global option set to NO but also the same option is local and set to YES?
This depends partly on how the check is done. If acl_get is called without a forum id then only the global will be checked. If a forum id is specified then the local option will be combined with the global one. If the local one is YES then so will the global one & vice versa. One thing to note is that when checking if a user has a permission the answer is only every YES or NO. The YES|NO|NEVER system is only used to build the YES|NO final setting. The example above is a good reminder that local & global permissions are different. There is also a check called acl_getf_global this is effective the same as acl_get().
If I assigned a role to a user where is that stored?
That is stored in the table phpbb_acl_users.
What fields are there and what do they mean?
user_id - user id from phpbb_users forum_id - forum id from phpbb_forums if a local option else 0 auth_option_id - option id from phpbb_acl_options auth_role_id - role id from phpbb_acl_roles if obtained from a role else 0 auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
If I assigned a role to a group where is that stored?
That is stored in the table phpbb_acl_groups.
What fields are there and what do they mean?
group_id - group id from phpbb_groups forum_id - forum id from phpbb_forums if a local option else 0 auth_option_id - option id from phpbb_acl_options auth_role_id - role id from phpbb_acl_roles if obtained from a role else 0 auth_setting - Stores either ACL_YES (1), ACL_NO (-1) or ACL_NEVER (0)
So how do I setup permissions now I know the different parts that are involved?
First you need to decide if you what you are trying to achieve. If you need to set one user to have maybe just one extra permission option then doing it to the user direction might be OK. Otherwise its best to set permission options on a group and place the user in the group. Or if its a lot of permission options you are setting up then a role might be best. You also need to understand if the options are global or local. Setting global permissions From the "PERMISSIONS" tab select from "Users' permissions", "Groups' permissions", "Administrators" or "Global moderators". If you select either of the last two you will first need to select the forum for which you are trying to set. Setting local (forum) permissions Setting forum based (local) permissions From the "PERMISSIONS" tab select from "Forum permissions", "Forum Moderators", "Users' forum permissions" or "Group' forum permissions". If you select either of the last two you will first need to select the user/group and then the forum for which you are trying to set. Setting role permissions From the "PERMISSIONS" tab select from "Admin roles", "User roles", "Moderator roles" or "Forum roles".
When setting advanced permissions or defining roles what are those tabs?
Each of the tabs represents a permission category. Categories are used to further group permission options together.
So where in the ACP can permissions be setup?
The ACP can be configured to place this modules in multiple places. So while some of the ways are listed above there are others and the administrators can move them.
OK. So I have setup the permissions I think. How can I view what permissions a user/group will get?
You view what permissions a user/group has by viewing its permission mask.
This permissions guide is in two parts due a limitation on article lengths in the Knowledge base. The second part of this guide can be found here