How to rename a group and preserve its permissions
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
An administrator may need to rename a Confluence group to reflect changes their organisation undergoes. This is currently not possible to do in Confluence, but a feature request is under consideration: CONFSERVER-9159 - Enable changing groupnames
A feature request to support group renaming natively in Confluence is tracked at https://jira.atlassian.com/browse/CONFSERVER-9159. Check the issue for the latest status. Until this is resolved, the manual database procedure above remains the only available workaround.
However, we can manually change a group name and all the permissions related to it through the database.
Bear in mind that such procedure is not part of Confluence's intended functionality. As such, this process is not covered under the Atlassian Support Offerings and the information given here is provided as-is. It should be thoroughly tested in a development or staging environment before implementing any changes in your production instance.
Confirm you have a database backup taken prior to running the UPDATE queries — if verification reveals missing permissions, a restore from backup is the only reliable rollback.
Solution
1. Identify the permissions granted to the target group
As noted in Confluence permissions architecture, Confluence recognizes permissions at site level and at space level, as well as page-level restrictions. Therefore, we must identify where our target group is being used before editing the group.
Run the following SQL queries against the Confluence database, replacing <group_name> with the group name, in lowercase:
GLOBAL permissions
--Postgres
SELECT permgroupname AS groupname,
permtype AS "permission_type (global)"
FROM spacepermissions
WHERE spaceid IS NULL
AND permgroupname in ('<group_name>')
ORDER BY permgroupname,
permtype;
--MSSQL
SELECT PERMGROUPNAME AS groupname,
PERMTYPE AS "permission_type (global)"
FROM SPACEPERMISSIONS
WHERE SPACEID IS NULL
AND PERMGROUPNAME in ('<group_name>')
ORDER BY PERMGROUPNAME,
PERMTYPE;SPACE permissions
--Postgres
SELECT permgroupname AS groupname,
s.spacename,
permtype AS "permission_type (space)"
FROM spacepermissions sp
JOIN spaces s ON sp.spaceid = s.spaceid
WHERE permgroupname in ('<group_name>')
ORDER BY permgroupname,
s.spacename,
permtype;
--MSSQL
SELECT PERMGROUPNAME AS groupname,
s.SPACENAME,
PERMTYPE AS "permission_type (space)"
FROM SPACEPERMISSIONS sp
JOIN SPACES s ON sp.SPACEID = s.SPACEID
WHERE PERMGROUPNAME in ('<group_name>')
ORDER BY PERMGROUPNAME,
s.SPACENAME,
PERMTYPE;PAGE restrictions
--Postgres
SELECT cp.groupname,
content.title AS content_title,
cp.cp_type AS "permission_type (page)"
FROM content_perm cp
JOIN content_perm_set cps ON cp.cps_id = cps.id
JOIN content ON content.contentid = cps.content_id
WHERE cp.groupname in ('<group_name>')
ORDER BY cp.groupname,
content.title,
cp.cp_type;
--MSSQL
SELECT cp.GROUPNAME,
CONTENT.TITLE AS content_title,
cp.CP_TYPE AS "permission_type (page)"
FROM CONTENT_PERM cp
JOIN CONTENT_PERM_SET cps ON cp.CPS_ID = cps.ID
JOIN CONTENT ON CONTENT.CONTENTID = cps.CONTENT_ID
WHERE cp.GROUPNAME in ('<group_name>')
ORDER BY cp.GROUPNAME,
CONTENT.TITLE,
cp.CP_TYPE;2. Edit the permissions, depending on the permission level
For example, we may want to preserve only page-level restrictions, or our target group only has Global permissions to be adjusted.
Run the following queries depending on the situation:
Update GLOBAL permissions
--Postgres
UPDATE spacepermissions
SET permgroupname = 'NEW_GROUP_NAME'
WHERE permgroupname IN ('OLD_GROUP_NAME')
AND spaceid IS NULL;
--MSSQL
UPDATE SPACEPERMISSIONS
SET PERMGROUPNAME = 'NEW_GROUP_NAME'
WHERE PERMGROUPNAME IN ('OLD_GROUP_NAME')
AND SPACEID IS NULL;Update SPACE permissions - all spaces
--Postgres
UPDATE spacepermissions
SET permgroupname = 'NEW_GROUP_NAME'
WHERE permgroupname IN ('OLD_GROUP_NAME')
AND spaceid IS NOT NULL;
--MSSQL
UPDATE SPACEPERMISSIONS
SET PERMGROUPNAME = 'NEW_GROUP_NAME'
WHERE PERMGROUPNAME IN ('OLD_GROUP_NAME')
AND SPACEID IS NOT NULL;Update SPACE permissions - specific spaces
--Postgres
UPDATE spacepermissions
SET permgroupname = 'NEW_GROUP_NAME'
WHERE permgroupname IN ('OLD_GROUP_NAME')
AND spaceid IN
(SELECT spaceid
FROM spaces
WHERE spacename IN ('<SPACE_NAME_1>',
'<SPACE_NAME_2>',
'<SPACE_NAME_n>'));
--MSSQL
UPDATE SPACEPERMISSIONS
SET PERMGROUPNAME = 'NEW_GROUP_NAME'
WHERE PERMGROUPNAME IN ('OLD_GROUP_NAME')
AND SPACEID IN
(SELECT SPACEID
FROM SPACES
WHERE SPACENAME IN ('<SPACE_NAME_1>',
'<SPACE_NAME_2>',
'<SPACE_NAME_n>'));Update PAGE permissions
--Postgres
UPDATE content_perm
SET groupname = 'NEW_GROUP_NAME'
WHERE groupname IN ('OLD_GROUP_NAME');
--MSSQL
UPDATE CONTENT_PERM
SET GROUPNAME = 'NEW_GROUP_NAME'
WHERE GROUPNAME IN ('OLD_GROUP_NAME');3. Rename the Group
If you are going to link Confluence to a different Directory and would like to transfer the permissions from group A (current) to group B (synced from the new directory), you can skip this step.
As noted in Step 3 above, if the group is hosted in an external directory, the rename must be performed there. Additionally, note that If this Confluence instance syncs groups from an external directory (LDAP, Azure AD, Crowd), renaming the group only in the Confluence database will cause the next directory sync to either recreate the old group name or fail to match the renamed group. Coordinate the rename with your directory sync configuration, or perform the rename in the external directory first if it is the source of truth.
If the group is located at Confluence Internal Directory
UPDATE cwd_group
SET group_name = 'NEW_GROUP_NAME',
lower_group_name = 'NEW_GROUP_NAME'
WHERE group_name = 'OLD_GROUP_NAME';Otherwise, update the group in the external directory that hosts the target group. e.g. JIRA or Active Directory.
4. Restart Confluence and flush caches
After adjusting the database, restart Confluence and clear Confluence's internal caches at General Configuration > Cache Management > Flush All (at the bottom).
5. Verification
After running the UPDATE queries and restarting Confluence, log in as a member of the renamed group and confirm access to the previously-identified global, space, and page-level permissions is intact. Also spot-check that the group no longer appears under its old name in Administration menu (⚙) > User Management > Groups.
Was this helpful?