Mapping principals and migrating permissions
Note
The features described in this blog post are currently only available in WikiTraccs.Console and not yet via the graphical user interface. The technical documentation is yet to be updated, as there might still be moving parts. Get in touch if you need info earlier.Latest release
Click here to get the latest release.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 or 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 migration
To illustrate the topic we’ll be going along with a sample 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 WikiTraccs does permission migrations
WikiTraccs can migrate page restrictions from Confluence to SharePoint (within certain limits, more on that later). Migrating page restrictions is done in two steps.
First migration step: WikiTraccs and you prepare everything needed to apply permissions to SharePoint
In a first step WikiTraccs stores Confluence page restriction and principal information in SharePoint lists. This is done while migrating page contents.
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, yet.
After successfully migrating the Confluence pages shown earlier (only content!) this is how the Pages Library should look:
Migrated Confluence Pages in SharePoint Pages Library
In addition, the document library Confluence Page Permission Snapshots 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 prepares, the Confluence User and Group Mappings list:
Confluence Users and Groups
You configure the user and group mapping in this list. WikiTraccs needs to know which Confluence principal maps to which SharePoint principal. More on that later.
After the mapping has been configured WikiTraccs can start with the next migration step.
Second migration step: WikiTraccs applies permissions to SharePoint pages
In a second 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. (More on how to do that in another blog post.)
Note
Separating the two steps - retrieving permissions information and applying those permissions to SharePoint - allows for a more flexible migration of content and permissions.Let’s assume WikiTraccs migrated the permissions.
We now have a look at one page permission migration result in depth.
Here’s the restrictions for page Page with view-only restriction for Wiki Reader in Confluence:
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)
In the next section we’ll look at how the mapping table has to look like to achieve this result.
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.
To achieve the result shown in the previous section the mapping table Confluence User and Group Mappings looks like this:
Mapping Confluence to SharePoint Principals
The highlighted column WT_Setting_MapForPermissions contains accounts from Azure AD and SharePoint groups.
The Admin Heinrich (admin) Confluence account is mapped to two target accounts Wiki SpaceAdmin and Heinrich Admin Ulbricht, and the Wiki Reader (wiki.reader) Confluence user is mapped to the Wiki Reader AD account.
When migrating restrictions for the page “Page with view-only restriction for Wiki Reader” WikiTraccs used those mappings to determine who should have access on the SharePoint page.
Tracking permission migration progress
WikiTraccs logs the result of each page permission migration in the Job Results list 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 Azure AD 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.
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.