Inspect permissions
Inspect permissions is an advanced permissions feature, and is only available in Confluence Data Center.
Confluence is open by default, but because of the layers of group, individual and anonymous permissions that can be applied, it can be challenging to find out exactly who can do what.
Inspect permissions helps you:
- troubleshoot permissions problems
- audit who can do what in your site
- apply the permissions granted to a user or group in one space to multiple spaces.
It reveals a person's effective permissions, combining everything we know about their permissions in a way that can be easily interpreted.
On this page:
Related pages:
Troubleshoot permissions problems
Often you will need to find out why someone can or can't do something in Confluence. By inspecting permissions you can drill right down to the root of the problem.
For example, someone reports to you that a teammate can see a space they shouldn't be able see. By inspecting permissions you can work out exactly what group memberships, for example, might be contributing.
Inspect permissions via space administration
You need space admin permissions for the space you want to troubleshoot.
To find out why someone can or can't view this space:
- Go to the space and choose Space tools > Permissions from the bottom of the sidebar
- Go to the Inspect permissions tab
- Enter the person's name or username.
- Leave the Page field blank (unless you need to investigate a specific page in this space).
- Choose Show.
A table showing the person's effective permissions in this space will appear. Click one of the icons to go to the detail view, and find out exactly why they do or don't have that permission.
If you choose to specify a particular page, the permissions explanations will also include information about any page restrictions. The icons will represent just that page, not the user's permissions for the entire space.
Screenshot: Inspect permissions tab in Space Tools showing permissions for two users.
Animation: Inspect permissions tab in Space tools showing permissions explanations for a user
Inspect permissions via the Global administration
You need Confluence Administrator or System Administrator global permission to do this. You don't need to have permission to view the space itself.
To find out why someone can or can't view this space:
- Go to Administration
> General Configuration > Inspect permissions. - Enter the person's name or username.
- Enter the spaces you want to view.
- Choose Show.
A table showing the users and spaces you searched for will appear. Click the link to see the detailed view, then click the icons to find out exactly why they do or don't have that permission.
Screenshot: Inspect permissions in Global administration showing permissions for two users and three spaces.
Animation: Inspect permissions in Global administration showing searching for all spaces containing the word "project" and then viewing permissions explanations for a user.
Inspect permissions for a group
You can also inspect permissions for a specific group. This can only be done via the global administration.
To inspect permissions for a group:
- Go to Administration > General Configuration > Inspect permissions.
- Choose the Groups tab
- Enter the group name.
- Enter the spaces you want to view.
- Choose Show.
A table showing the groups and spaces you searched for will appear. Click the link to see the detailed view.
When inspecting permissions for a group, be aware:
- We don't indicate when a group does not have the Can Use global permission, as we do for users.
- We don't show effective permissions for the group, as we do for users. We only show permissions directly granted to that group (not granted via membership of a parent group. This is only an issue if your external user directory has nested groups).
Using wildcards in your search
When searching for users, groups, or spaces, you can use * as a wildcard. For example if you wanted to search for all spaces that contain the word project in their title, type *project and select Search for *project from the suggestions dropdown.
Permissions explanations
The detail view shows the effective permissions for a single user or group in a space. Click each icon to see a detailed explanation, as shown here.
- Icons - icons indicate whether the user or group can or can't do this action.
- Explanation - explains why the user can or can't do this action.
- Good to know information - provides additional information that may become relevant, for example that space administrators can grant themselves permissions they don't currently have.
The purpose of these explanations is to provide a simple reason why someone can or can't do something in a space. The messages are designed to be short, and present the most relevant information first.
The table below contains a more detailed explanation of every message, including the conditions that trigger the message.
Audit permissions
If you need to regularly check who can do what in your site, for example for compliance or regulatory reasons, you can inspect permissions to conduct an audit.
To export permissions information for all users and all spaces in your site:
- Go to Administration > General Configuration > Inspect permissions.
- Choose your search criteria - you can search for particular users, groups, or spaces, include disabled accounts, or exclude users who have no permissions.
- Choose Show. This will give you an idea of how large your query is.
- Choose Export.
- Keep the default separator. Comma separated is great for opening in most spreadsheet applications.
- Choose how you want spaces to be listed. This depends on how much information you want to include. You can include just the space key, just the space name, or both.
- Choose Export.
The CSV file will be immediately downloaded in your browser. This can take a few minutes, depending on the size of your query.
This file can be extremely large in sites with many users and spaces. You could use the wildcard search feature to limit the number of users to be included in each export.
- Wildcard search - use a wildcard to narrow your search.
- Export - export the results to CSV for auditing or further analysis.
Bulk apply permissions
Bulk applying permissions is useful when:
- You create a new group, and want to give that group permissions to a number of existing spaces.
- You need to grant someone permissions as an individual for a number of existing spaces.
- You have just created several new spaces, and want to use permissions from an existing space as a template.
We recommend using groups as an efficient way to manage permissions in your site. When someone new starts on your team, we would recommend making them a member of appropriate groups, over using the bulk add permission options to grant them permissions to all their spaces as an individual.
Bulk apply permissions for a group
You need Confluence Administrator or System Administrator global permissions to do this.
To give a group the same permissions in multiple spaces:
- Go to Administration > General Configuration > Inspect permissions.
- Go to the Groups tab.
- Enter the name of the group.
- Enter the name of the space that you want to use as a starting point.
- Choose Show, then click to see the detailed view.
- Choose Edit.
- Make sure the correct permissions are selected. These are the permissions you'll be copying.
- Enter the names of the spaces you want to copy these same permissions to. You can add as many spaces as you like.
- Choose Apply.
- Check the confirmation dialog to make sure all spaces were successfully updated.
Screenshot: detail view of permissions for a group and space, with several spaces listed in the 'Apply to other spaces' field.
Bulk apply permissions for a user
Before you do this, we recommend you inspect permissions to find out what permissions the user already has for the spaces you plan to update, paying particular attention to how the permissions are granted (individually, or via a group). In many cases the best approach is to change the user's group membership, or the space permissions granted to a group, rather than bulk applying changes to the individual.
You need Confluence Administrator or System Administrator global permissions to do this.
To give a user permissions in multiple spaces:
- Go to Administration > General Configuration > Inspect permissions.
- Enter the name of the user.
- Enter the name of the space that you want to use as a starting point.
- Choose Show, then click to see the detailed view.
- The user's effective permissions are shown. These permissions are a combination of any individual and group permissions. Choose Edit.
- Make sure the correct permissions are selected. These are the permissions you'll be copying.
- Enter the names of the spaces you want to copy these same permissions to. You can add as many spaces as you like.
- Choose Apply.
- Check the confirmation dialog to make sure all spaces were successfully updated.
As a general rule, we recommend managing permissions using groups. If you do decide to bulk apply permissions for a user, there are some things to be aware of:
- Permissions can only be granted to the user as an individual using this method.
- Any permissions the user has as a member of a group will be unchanged. For example if they are a member of a group that has Export permission, and you bulk apply permissions that do not have Export permission, they will still have Export permission. Changing their individual permissions can't override their group permissions.
- The checkboxes, when you click Edit, reflect the user's current effective permissions - that is the combination of all the permissions they already have as an individual or member of a group. When you click Apply, you'll apply these exact permissions as an individual. You may actually be doubling up on permissions the user already has, as a member of a group.
Troubleshooting and known issues
General cache problems
Confluence caches permissions information, which helps to make sure results are returned quickly when you check who can view a page, or inspect permissions. We continually update the cache as people and permissions change. However, we know of two scenarios where the cache is not correctly updated - when you import a site, and when you add, disable, or change the order of your user directories.
If this happens, the best way to force Confluence to rebuild the cache is to disable the Inspect permissions - gatekeeper plugin, then re-enable it. Alternatively, you can restart Confluence, as the cache is built on startup.
Export options limited in Internet Explorer 11
There's a known issue with the export dialog in Internet Explorer 11. The dialog is known to intermittently freeze if you select either of the dropdown menus. As a workaround, use the default values for the Separator and List spaces by fields, or use another browser to complete the export.
Inspect permissions for a group only shows direct permissions
If your external directory has nested groups (a group is a member of another group), and you inspect permissions for a group, you'll only see permissions granted directly to that group (not effectively granted by being a member of a parent group). If you search for a user, we'll always show the effective permissions, including those granted by parent groups.
Excluding spaces with no permissions can take a long time in large sites
In the global Inspect Permissions screen, if you select "Don't show spaces that have no permissions for selected users" and don't specify any other filters (such as specifying users, groups, or spaces), the query can take several minutes to return any results. This is particularly true in sites with a very large number of users and spaces.