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:

1. Go to the space and select Space tools > Permissions from the bottom of the sidebar.
2. Go to the Inspect permissions tab.
3. Enter the person's name or username.
4. Leave the Page field blank (unless you need to investigate a specific page in this space). 
5. Select 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:

1. Go to Administration  > General Configuration > Inspect permissions.
2. Enter the person's name or username.
3. Enter the spaces you want to view.
4. Select 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:

1. Go to Administration  > General Configuration > Inspect permissions.
2. Select the Groups tab.
3. Enter the group name.
4. Enter the spaces you want to view.
5. Select 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 an asterisk * as a wildcard. For example, if you want 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. 

1. Icons - icons indicate whether the user or group can or can't do this action. 
2. Explanation - explains why the user can or can't do this action.
3. 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. 

These explanations 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:

1. Go to Administration  > General Configuration > Inspect permissions.
2. Choose your search criteria — you can search for particular users, groups, or spaces, include disabled accounts, or exclude users who have no permissions.
3. Select Show. This will give you an idea of how large your query is. 
4. Select Export.
5. Keep the default separator. Comma separated is great for opening in most spreadsheet applications.
6. 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.
7. Select 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. 

1. Wildcard search — use a wildcard to narrow your search.
2. 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:

1. Go to Administration  > General Configuration > Inspect permissions.
2. Go to the Groups tab.
3. Enter the name of the group.
4. Enter the name of the space that you want to use as a starting point. 
5. Select Show, then click to see the detailed view. 
6. Select Edit.
7. Make sure the correct permissions are selected. These are the permissions you'll be copying.
8. Enter the names of the spaces you want to copy these same permissions to. You can add as many spaces as you like. 
9. Select Apply. 
10. 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:

1. Go to Administration  > General Configuration > Inspect permissions.
2. Enter the name of the user.
3. Enter the name of the space that you want to use as a starting point. 
4. Select Show, then click to see the detailed view. 
5. The user's effective permissions are shown. These permissions are a combination of any individual and group permissions. Select Edit.
6. Make sure the correct permissions are selected. These are the permissions you'll be copying.
7. Enter the names of the spaces you want to copy these same permissions to.  You can add as many spaces as you like. 
8. Select Apply. 
9. Check the confirmation dialog to make sure all spaces were successfully updated. 

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.