Skip to content

User groups and permissions#

User groups are XenForo's primary method of assigning roles to the users of your forum. This allows you to assign permissions, titles and other customizations to users.

XenForo's group and permission system is very powerful. However, it may work differently than you're accustomed to with other software. You will find you get better results if you adapt your approaches to work with the concepts presented here.

User groups as roles#

XenForo comes with four default user groups that you cannot remove, though you can rename them:

  1. Unregistered / unconfirmed
  2. Registered
  3. Administrative
  4. Moderating

The first two are the most significant initially. Unregistered / unconfirmed represents all guests and any users who have an account that is not in a confirmed/valid state. Registered represents all registered users.

All users must belong to at least one user group but can be members of many. We recommend that all users have the registered group as their primary user group -- including your moderators and administrators! When a new user registers, they will always be put in the registered group automatically.

If you're coming from a different forum software, having your admins and moderators be members of the registered group may seem awkward. However, if you consider user groups to be "roles", the concepts will begin to make sense.

Any user account on your forum is, by definition, a registered member. A user who is a moderator should also be in the moderating role (group). Similarly, if a user is an admin and a moderator, they should be in the registered, administrative and moderating roles (groups).

Taking this approach allows you to:

  • Define a baseline set of permissions for the registered group. These are the permissions that all registered users will have.
  • For each additional role, you then only need to consider the additional permissions that they will receive. (All other permissions can be left at no/inherit. See below.)

If done correctly, you will not be duplicating permission configurations across groups. If you find that two groups require nearly identical permissions, consider either merging them or using an additional group to represent the share components.

How permissions are applied#

There are multiple permission sets that come together to define a user's final set of permissions. Under the Groups & permissions section, these include:

  • User group permissions: the permissions defined for each user group you have created
  • User permissions: an optional set of additional permissions to apply to specific users. This is used for things like moderator permissions. However, if you are ever going to apply the same permissions to multiple users, we recommend creating user groups.
  • Node permissions: these are override permissions for specific nodes. This will be discussed more in the next section.

Add-ons may define additional permission types. These will behave similarly to node permissions.

To determine the global permissions for a user, we collect the permissions from all the groups they're a member of and any custom user permissions. The final value for a permission is then determined by which value has the highest priority.

Permission value priority#

As a user may be in many groups and have their own custom permissions, determining the final permission value is done by determining which value has the highest priority. The priority is defined as: (highest priority first)

  1. Never: this is an overriding no and the permission is not granted. It always trumps other values and should only be used in specific scenarios.
  2. Yes: the permission is granted.
  3. No: the permission is not granted.

To make this clearer, here are some examples of what permission would "win" in various scenarios:

  • No + Yes = Yes
  • No + Never = Never
  • Yes + Never = Never

For numeric permissions, the highest value from all of the groups and user permissions is used.

Warning

"Never" is a powerful feature but it can cause problems if used inappropriately. It is designed for being applied to groups that are used for user discipline, such as by removing permissions to users that have a certain number of warning points. Do not use it for the default registered group!

Node permissions#

Node permissions allow you to define permissions that will only apply to a specific node. Like the global permissions, these can be applied to user groups and individual users.

Initially, these permissions are inherited from the global permission values. If you customize a permission for a particular node, that new value will now be inherited by any child nodes as well, unless they too customize the value.

Differences from global permissions#

Node permissions are very similar in concept and application to the global user group and user permissions and the examples given above.

However, instead of defaulting to No, node permissions default to Inherit. If any custom permission value is set, it will be used instead of the inherited version; essentially, Inherit is the lowest priority permission value.

Note

There is one exception to this rule. If the inherited value is Never, it cannot be overridden, even by child nodes.

Private nodes#

When setting the permissions for a node, you have the option to make the node private. Enabling this will prevent all access except where explicitly granted.

This is ideal for creating staff-only forums. To do this, you would make the forum private and then set View node to Yes for the administrative and moderating user groups.

Confirming permissions are correct#

To confirm that a user is receiving the permissions you expect, use the Groups & permissions > Analyze permissions system. This allows you to see the final yes/no value for each permission, along with all of the permissions that were considered leading up to that decision.

This analysis can be done for a user's global or node-specific permissions.

User group promotions#

User group promotions are a means of automatically adding members to user groups, to alter their user title, user name styling, or permissions.

Managing promotions#

  • Log in to the admin control panel.
  • Click on Groups & permissions from the navigation on the left hand side.
  • Click on User group promotions from the list that appears.

From here you can see a list of all promotions created. Clicking the title will allow you to view, edit, and delete them. Promotions can be disabled and re-enabled via the checkbox.

Creating a promotion#

To create a new user group promotion, click on the Add promotion button. After giving the promotion a title and selecting the user groups to add the promoted users to, various criteria can then be defined.

The criteria that can be used is discussed in the Criteria section. If no criteria is selected, the promotion will never be awarded automatically.

Note

Promotions are governed by a routine cron task which runs every hour.

Once the promotion has been saved, any members active recently, who match all of the criteria, will be promoted. If a member no longer qualifies for the promotion, due to their status or the promotion criteria changing, then they will be demoted and removed from the user groups(s).

An example promotion#

For the purposes of this example, all members will have their first five posts pre-moderated. After that they will be promoted into a new user group which will allow them to post freely. This is a typical use for user group promotions, to allow moderators to vet all initial posts by new members and catch any potential spammers.

The first step is to configure the Registered user group with the base permissions all members will have. As we want all members to be pre-moderated initially, then the permission Submit content without approval must be set to No.

The next step is to create a new user group, which we will call Verified Member, and in that group we set the Submit content without approval permission to Yes, while all other permissions stay at No.

Now create the promotion, giving it a title of Promoted Member and check the Verified Member user group. For the criteria, select User has posted at least X messages and enter a value of 5.

Once saved, the first 5 posts of all members will be pre-moderated. Once they have made 5 posts they will be automatically promoted and added to the Verified Member user group, allowing them to post normally. Note that their posts will only go through normally after the promotion has run. It is not instantaneous.

Managing promoted users#

Clicking the Manage promoted users button will allow you to view any previously promoted users and also manually apply or prohibit promotions to individual users.

Promotion history#

To view promotion history, enter a user name and/or select a promotion. If no user name is entered, a full list of all users affected by that particular promotion is returned.

Any users who have been automatically promoted will appear in the list with user name, date and promotion title; any who have been prevented from being promoted will have their entry appended with Promotion disabled, any who have been manually promoted will be appended with Manually applied.

Note

Any users manually demoted will no longer be eligible for that particular promotion, even if they meet the criteria.

Users can be demoted by clicking the delete icon. The entry in the list will then be appended with Promotion disabled.

Clicking the delete icon again will make the user eligible for that promotion once more and remove the user from the list, until the next time the cron task runs, assuming they still meet the criteria.

Manual promotion#

Users can be manually promoted or prevented from being promoted.

To manually promote a user, enter the user name and select the desired promotion. Manual promotions override the criteria and the promotion will remain in effect indefinitely, even if the user does not meet the criteria.

Similarly, users can be prevented from being promoted, which will also override the criteria.

Manual promotions can be removed in the same way as automatic promotions, via the promotion history page.

Other uses for groups#

Setting custom permissions is probably the most significant use for user groups, but they can also be used to customize how users may appear to others.

If a user is a member of a multiple groups, the configuration of the group with the highest Display styling priority value will be used in most of the features listed here.

  1. User title override: this controls whether a user's title comes from this group or the standard user title ladder. Note that a user-specific custom title will override both.
  2. User name CSS: this can be used to apply color or other flourishes to the name of users in this group. Note that the user name styling is not used in all scenarios.
  3. User banners: if specified, a banner will be displayed below the user's name on their posts. Further configuration for this can be found in Setup > Options > User options > User banners.

Staff#

In XenForo, there are two types of staff members, moderators and administrators. These are entirely distinct roles in terms of the permissions granted. Making a user an administrator does not make them a moderator; these roles need to be assigned separately.

Moderators#

Moderators are users that are given special privileges on your site, generally to help manage the content other users submit to the site. This includes things like deleting posts that violate rules, moving threads to more appropriate locations, and handing out warnings. The exact permissions that a moderator has can be set when the moderator is configured.

There are two types of moderators: super and forum-specific. Super moderators have permissions in all forums by default, while a forum moderator is only able to use those permissions in the specific forums they're assigned to.

In order to have access to all of the moderator tools and functionality, a user must explicitly be made a moderator. Adding a user to the Moderating user group does not make them a moderator. They must be added via Groups & permissions > Moderators.

The moderator bar will be displayed at the top of the page for all moderators. This allows them to access the approval queue and reported items.

Administrators#

Administrators are users that can access and perform actions within the administrator control panel. Making someone an administrator does not inherently give them additional access to the forum.

There are two types of administrators: super and regular. Super administrators always have access to all parts of the control panel and can add/remove other administrators. Regular administrators are controlled by the specific permissions applied to them. They are unable to add/remove administrators.

Staff security#

Administrators and moderators have enhanced access to your forum. If an attacker is able to gain access to one of these accounts, they may be able to delete/manipulate content or deface your site. Therefore, it is very important that you and your staff take precautions to ensure that your accounts cannot be accessed unexpectedly. Here are several tips to help avoid that:

  1. Use a unique password for your site. Most account takeovers are caused by password reuse. The best method to ensure that you don't reuse passwords is to use a password manager.
  2. Enable two-step verification. This ensures that even if an attacker gains access to your password, they will need a second authentication token to login. You can force your staff to enable two-step verification through permissions or by blocking access to the control panel until they enable it.