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 certain limits, more on that later). 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 Page Permission Snapshots (located in the WikiTraccs site) now contains permission snapshots for those pages, waiting to be applied by WikiTraccs:
Confluence Page Permission Snapshots
Those permission snapshots contain information about a page’s restrictions.
Then there’s a third list that WikiTraccs populates, the Confluence User and Group Mappings 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 Mappings table (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 migration account and got Full Control permissions (the migration account is always added)
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 list, that is 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
WikiTraccs currently has two types of limitations when it comes to permission migrations: not-implemented features and nearly-impossible-to-add features.
But first, here is what WikiTraccs will do:
- apply Confluence user and group page restrictions to SharePoint modern pages, when no hierarchy of page restrictions is involved
- apply hierarchical page restrictions from Confluence to SharePoint modern pages in certain narrow circumstances (e.g. only users are involved)
- provide a mapping opportunity for each Confluence principal to one or more Entra ID accounts and SharePoint groups
- map the Confluence view and edit restrictions to corresponding SharePoint permission levels via a hard-wired logic
Features that might be useful in the future, but are not currently implemented:
- using other group types than SharePoint groups as mapping target
- provide fallbacks for when a mapping is missing or empty
- configurable behavior for failed permission migrations (should the SharePoint page be restricted or not?)
- more control over the permission migration scope (single pages, spaces, …)
- migrating space and global permissions (those are currently not migrated and need to be set manually on the SharePoint site or sub site level)
- allowing to configure SharePoint permission levels to be used in the target page (currently the out-of-the-box permission levels are used)
- regularly updating SharePoint permission based on a configurable schedule
Features that will be hard or impossible to add:
- migrating arbitrary hierarchies of page restrictions
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 Mappings list
- in each migration target SharePoint site, delete entries from the Page Transactions 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 update the already migrated page restriction information from Confluence. To get updated page restriction information from Confluence, you have to restart with STEP 1 and remigrate page contents, which will carry over updated page restriction information from Confluence.Summary
With the next release WikiTraccs adds the ability to migrate page restrictions from Confluence to SharePoint.
You’ll be able to configure which Confluence users and groups correspond to which SharePoint users and groups. WikiTraccs uses this information when applying unique permissions to SharePoint pages.
This release marks a milestone from which further development will be driven by your feedback. WikiTraccs could support several additional scenarios and development effort will be directed to areas with the most demand.
Furthermore, user and group mappings will be the basis for the migration of page metadata like 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.