Mapping principals and migrating permissions
Terminology
We need to define some terms before starting into the topic.
The term permissions is used broadly to describe which audiences can access which content in Confluence or SharePoint, and to which extent. Those audiences can be users and groups. Users and groups are collectively referred to as principals.
When explicitly talking about permissions for Confluence pages the term page restrictions will be used as this is the correct Confluence terminology.
A sample permission migration
We’ll do a sample permission migration. Screenshots from this migration will be shown throughout the blog post.
For the sake of this sample migration, let’s assume we want to migrate the following Confluence pages:
Confluence Pages
Each of those pages has a different permission configuration. Some pages have view and edit restrictions set. Some for users, some for groups, and some for both. And some pages form a hierarchy to illustrate the challenges associated with that.
How to migrate permissions with WikiTraccs
Opinion from the author of WikiTraccs
If you can, don’t migrate permissions.
Spare yourself the hassle that is migrating permissions from Confluence to SharePoint. It rarely provides value compared to rethinking the information architecture in SharePoint, which will likely yield a different result than what has grown in Confluence. Besides, a 1:1 permission migration is nearly impossible as soon as you’ve got permission hierarchies in Confluence that involve groups.
If you want to migrate permissions, do a test migration first.
If there is a tight deadline and you did not test-migrate, don’t stumble into the production migration. Test-migrate first.
That being out of the way, the rest of this post shows how to migrate permissions.
WikiTraccs can migrate page restrictions from Confluence to SharePoint within the documented permission migration limits. Migrating page restrictions is done in three steps.
STEP 1: Migrate content and configure mappings for users and groups
First, you migrate page contents. WikiTraccs stores Confluence page restriction and principal information in SharePoint lists, along the way.
Choose content migration mode
In the main blue WikiTraccs.GUI window, from the main menu, choose Settings > Configure Transformation.
In the Transformation Settings dialog, in the Migrations tab, choose Migrate Content as migration mode.
Select Ok to close the dialog.
When a page is migrated, WikiTraccs also receives page restrictions for this page as well as information about users and groups involved in those restrictions.
No permission configuration is applied to SharePoint pages, yet.
After successfully migrating the Confluence pages shown earlier (only content!) this is how the Pages Library of the migration target site looks:
Migrated Confluence Pages in SharePoint Pages Library
In addition, the document library Confluence Permission Snapshots (WikiTraccs) (located in the WikiTraccs site) now contains permission snapshots for those pages, waiting to be applied by WikiTraccs:
Confluence Permission Snapshots (WikiTraccs)
Those permission snapshots contain information about a page’s restrictions.
Then there’s a third list that WikiTraccs populates, the Confluence User and Group Mapping (WikiTraccs) list (also located in the WikiTraccs site):
Confluence Users and Groups
You now configure the user and group mapping in this list. WikiTraccs needs to know which Confluence principal maps to which SharePoint principal.
STEP 2: Mapping Confluence users and groups to SharePoint
One factor for a successful permission migration is the mapping of Confluence users and groups to their counterparts in SharePoint. You configure this mapping manually.
Let’s configure the mapping like this, in the Confluence User and Group Mapping (WikiTraccs) list (located in the WikiTraccs site):
Mapping Confluence to SharePoint Principals
The highlighted column WT_Setting_MapForPermissions contains accounts from Entra ID and SharePoint groups.
Those two mappings shall be highlighted in particular, as we’ll revisit them in STEP 3:
- the Admin Heinrich (admin) Confluence account is mapped to two target accounts Wiki SpaceAdmin and Heinrich Admin Ulbricht
- the Wiki Reader (wiki.reader) Confluence user is mapped to the Wiki Reader AD account
When you are done with the mapping, proceed with the next step.
Mapping groups
Group mappings are based on SharePoint groups. Due to technical reasons, those SharePoint groups have to be created both in the WikiTraccs site and in the target SharePoint sites.
Group members only have to be configured in the target sites, though. The SharePoint group in the WikiTraccs site is merely a placeholder, so the group can be chosen as migration target in the people picker.
Automating the creation of those SharePoint groups is recommended, e.g. using PnP.PowerShell.
Note
You can change the mapping later and run the permission migration again, to update SharePoint page permissions.STEP 3: Apply permissions to SharePoint pages
In this last step WikiTraccs applies the stored permission information to the already migrated SharePoint pages. This step has to be started manually and separately from the first step.
Enable permission migration mode
In the main blue WikiTraccs.GUI window, from the main menu, choose Settings > Configure Transformation.
In the Transformation Settings dialog, in the Migrations tab, choose Migrate Permissions as migration mode.
Select Ok to close the dialog.
Note
Separating the two steps - retrieving permissions information and applying those permissions to SharePoint - allows for a more flexible migration of content and permissions.After choosing permission migration mode, start the migration as usual. WikiTraccs now applies the already migrated permission information to the already migrated pages in SharePoint.
We now have a look at a page permission migration result in depth.
In Confluence, the restrictions for page Page with view-only restriction for Wiki Reader look like this:
Restrictions of Page "Page with view-only restriction for Wiki Reader" in Confluence
Here’s the resulting permissions for the migrated SharePoint page:
Permissions of the Migrated SharePoint Page
Looking at the principals and permission levels this is what happened:
- Confluence account “wiki.reader” was mapped to the “Wiki Reader” AD account and got Read permissions which corresponds to the Confluence view restriction
- Confluence account “admin” was mapped to both the “Heinrich Admin Ulbricht” and the “Wiki SpaceAdmin” accounts and got Contribute permissions which corresponds to the Confluence edit permission
- “WikiTraccs Admin” is the identity running the migration and got Full Control permissions (the running identity is always retained)
The basis for this permission configuration had been layed in step 2 when you configured the principal mappings.
Tracking permission migration progress
WikiTraccs logs the result of each page permission migration in the Page Transactions (WikiTraccs) list, located in each migration target site in SharePoint.
For our sample migration this looks like this:
Permission Migration Results
There are several reasons why migrating Confluence page restrictions to SharePoint might fail.
The good thing is that a range of permission migration failures can be fixed easily. The permission migration can be run multiple times and will retry failed migrations. This can be repeated until all resolvable errors have been resolved.
Going back to our sample migration you might have noticed that (in the last screenshot) two permission migrations where not successful. For two pages the result is cannot merge hierarchical group restrictions when calculating merged page restrictions which means that for those pages restrictions could not be migrated.
The next section takes a deeper look at what WikiTraccs currently can and cannot do when it comes to migrating permissions.
Capabilities and limitations with regard to migrating permissions
At a high level, WikiTraccs can:
- apply direct user and group page restrictions to SharePoint modern pages
- apply hierarchical page restrictions in certain narrow cases, for example when only users are involved
- map each Confluence principal to one or more existing Entra ID users or SharePoint groups
- map Confluence view to SharePoint Read and Confluence edit to SharePoint Contribute
The main model limitations are:
- complex restriction hierarchies involving groups cannot always be represented on flat SharePoint pages
- only page restrictions are applied, not Confluence space or global permissions and not restrictions on generated calendar or database lists
- WikiTraccs does not create target accounts or groups, and the SharePoint permission levels chosen by WikiTraccs are not configurable
- each restricted page receives unique permissions and retains the identity running the migration (“migration account”) with Full Control
Missing principal mappings
A missing or empty principal mapping does not fall back to inherited site permissions. WikiTraccs breaks inheritance and restricts the page to the principals it could resolve, plus the identity running the migration. Review failed permission transactions before releasing the target site.See Known Issues and limitations for the complete list.
Nested pages and restrictions
Hierarchical page restrictions from Confluence are difficult to handle because nested pages don’t exist in SharePoint. For SharePoint, the restriction hierarchy of a page needs to be combined and applied to a single SharePoint page.
When only user restrictions are involved then merging a hierarchy of restrictions is relatively easy to do. But when it comes to groups which overlap in only some of their members it becomes nearly impossible to apply that to SharePoint.
Re-apply permissions after changing principal mappings
You can change the principal mapping that you configured in STEP 2, even during or after a permission migration.
To do so, proceed as follows:
- in the WikiTraccs SharePoint site, change principal mappings via the Confluence User and Group Mapping (WikiTraccs) list
- in each migration target SharePoint site, delete entries from the Page Transactions (WikiTraccs) table for pages that should have their permission configuration updated; otherwise WikiTraccs won’t update those pages
- in WikiTraccs, choose Permission Migration mode and start the migration
WikiTraccs will now apply page permissions again, using the already migrated information about Confluence page restrictions, and the updated principal mapping.
Note
This does not refresh the stored page restriction information from Confluence. To retrieve current restrictions, delete the page’s snapshot from Confluence Permission Snapshots (WikiTraccs) before running permission migration again. WikiTraccs will recreate the missing snapshot from Confluence. Remigrating the page content also refreshes its snapshot.Summary
WikiTraccs can migrate page restrictions from Confluence to SharePoint in a separate permission pass.
You configure which Confluence users and groups correspond to which SharePoint users and groups. WikiTraccs uses this information when applying unique permissions to SharePoint pages.
Because the Confluence and SharePoint permission models differ, test the result and review all failed transactions before making the target sites available. The current limitations are maintained on the Known Issues and limitations page.
The same user and group mappings are also used when updating page metadata such as author and editor.
Give it a try
Give WikiTraccs a try and check out its transformation capabilities!
Start today with WikiTraccs’ free Trial Version:
Or get in touch via email if you are interested in a demo. Give it 45 minutes and you’ll be up to speed on how WikiTraccs can help you.