Confluence Page Restrictions vs. SharePoint Permission Inheritance

Confluence protects a subtree of pages, SharePoint protects a single item. What that means for migrating page restrictions, why groups along the page tree cannot be mapped, and what WikiTraccs does instead.

By Heinrich Ulbricht | Thursday, September 10, 2026

Migrating permissions from Confluence to SharePoint is often on the checklist I get when I demo WikiTraccs.

Confluence and SharePoint differ on a technical level, when looking at permissions. My recommendation is always the same: don’t migrate permissions from Confluence to SharePoint Online.

Confluence protects a subtree of pages, SharePoint protects a single item, and most of the difficulty in migrating page restrictions follows from that difference.

This post explains the gap and shows what WikiTraccs does to bridge it. It also covers the one case where a bridge would be hard to maintain: groups that change along the page tree.

Terminology

Confluence uses two words. Global and space level access is governed by permissions. Page level access is governed by restrictions. SharePoint calls all of it permissions, on every level. Users and groups together are principals. This post uses the Confluence terms for the source side and the SharePoint term for the target side.

The Basic Problem

In Confluence, pages form a tree, and a view restriction on a parent page hides every page below it. In SharePoint, pages are files in one flat library, the Site Pages library. A SharePoint page inherits its permissions from that library. There is no parent page it could inherit from.

CONFLUENCE                                   SHAREPOINT
Tree, visibility inherits downwards          Flat library "Site Pages"

Space "HR"                                   Site "HR"
│  Space permissions: HR team                │  Site permissions: HR team
│                                            │
└─ Salaries      VIEW: HR management         ├─ Salaries.aspx    inherits from the library
   ├─ 2025       (no rule of its own)        ├─ 2025.aspx        inherits from the library
   │  └─ Bonus   (no rule of its own)        ├─ Bonus.aspx       inherits from the library
   └─ Forecast   (no rule of its own)        └─ Forecast.aspx    inherits from the library

One rule protects four pages.                There is no parent page to inherit from.
The descendants inherit the restriction.     All pages sit next to each other in
                                             one library.

If a migration tool only copied the restriction to the one page that carries it, the three pages below it would be open to everyone who can access the site and its Site Pages library.

Why the Two Models Do Not Line Up

The two products also mean different things by “a permission on a page”.

Confluence has three layers, and each layer can only narrow what the layer above allows. A page restriction is a filter on the space audience. It can take people away, but it can never add someone who lacks the space view permission.

SharePoint has a chain of containers. Each link inherits from the one above, or it breaks inheritance and gets a unique set of permissions. That unique set is a complete replacement, and it can be narrower or wider than what the library grants.

CONFLUENCE                                     SHAREPOINT
three layers, each one can only NARROW         a chain, each link can REPLACE

  Global permissions                             Tenant
  who may use Confluence at all                    │
          │                                        ▼
          ▼                                      Site
  Space permissions                              Read, Contribute, Edit,
  view, add, delete, export,                     Full Control, ...
  restrict, admin, ...                             │
          │                                        ▼
          ▼                                      Library "Site Pages"
  Page restriction                               inherits from the site, or unique
  view or edit only                                │
  takes away, never adds                           ▼
                                                 Page (item)
                                                 inherits from the library, or unique
                                                 (a unique set may grant MORE than
                                                  the library does)

Three WikiTraccs rules follow from this difference:

WikiTraccs migrates page restrictions only. A page restriction in Confluence says who, out of the space audience, keeps access to the page. WikiTraccs does not migrate the space audience; you set up the site audience in SharePoint. WikiTraccs writes only the principals from the page restriction to the page.
The two mappings are fixed. A Confluence page restriction has two operations, view and edit. SharePoint has permission levels. WikiTraccs maps view to Read and edit to Contribute. There is nothing to configure.
Edit-only restrictions get a default read audience. In Confluence, a page with an edit restriction and no view restriction stays readable for the whole space audience. In SharePoint, a page with unique permissions has no link to the site audience. WikiTraccs gives Read to “Everyone except external users” on such a page.

WikiTraccs does not touch site permissions

WikiTraccs changes permissions on migrated pages only. It never changes the permissions of the target site or its libraries. This is by design. Target sites often exist before the migration starts, somebody has already set them up (a SharePoint admin, the site owner, or the team that will use the site), and access at the site level usually looks different from a Confluence space anyway. The site audience stays as you set it up. WikiTraccs adds page permissions inside that audience.

What WikiTraccs Does

WikiTraccs walks down the tree, calculates the effective restriction for each page, and applies it to each page separately:

  Salaries    VIEW: HR management  ─┐
  ├─ 2025     (inherits)            │  WikiTraccs resolves the inheritance
  │  └─ Bonus (inherits)            │
  └─ Forecast (inherits)           ─┘
                    │
                    ▼
  Site Pages
  ├─ Salaries.aspx   [x] inheritance broken  →  HR management: Read
  ├─ 2025.aspx       [x] inheritance broken  →  HR management: Read
  ├─ Bonus.aspx      [x] inheritance broken  →  HR management: Read
  └─ Forecast.aspx   [x] inheritance broken  →  HR management: Read
                      ▲
                      4 unique permission scopes instead of one rule

What breaking permission inheritance means

In SharePoint, a page starts with the permissions of its library (Site Pages). When you break inheritance on that page, SharePoint copies the current permission set to the page, and from then on the page has its own set. You can add and remove principals on that set. Later changes on the library do not reach the page anymore.

At first sight this looks like a Confluence page restriction: one page gets its own access rule. The SharePoint break stops the flow from the library to one page, and it flows nowhere else, because a page has no children in SharePoint. The Confluence restriction does the opposite. It keeps all rules from above in force, adds one more filter, and passes the result down to every descendant. So a broken inheritance in SharePoint is one isolated page, and a page restriction in Confluence is a rule for a whole subtree.

One Confluence rule becomes one unique permission scope per page in SharePoint. This is the only way to express the Confluence result on flat items. The consequences are listed further below.

The Limit: Groups Along the Tree

As long as the restrictions name individual users, WikiTraccs can resolve the inheritance, because at the end a user is either on the list or not. With groups, that calculation stops working.

Confluence works like a series of gates. Each page on the way down is a gate, and only the principals named at that gate get through:

Confluence: two gates in a row

  Project      VIEW: group "Engineering"   Gate 1: only Engineering gets through
  └─ Contract  VIEW: group "Purchasing"    Gate 2: only Purchasing gets through

Whoever sees the page "Contract" must pass both gates, so must be in BOTH groups:

      Group "Engineering"
     ┌──────────────────────────┐
     │                          │  Group "Purchasing"
     │              ┌───────────┼──────────────┐
     │              │▒▒▒▒▒▒▒▒▒▒▒│              │
     │              │▒▒▒▒▒▒▒▒▒▒▒│              │
     │              │▒▒▒▒▒▒▒▒▒▒▒│              │
     └──────────────┼───────────┘              │
                    │                          │
                    └──────────────────────────┘

     ▒ = members of both groups. Only these people may read "Contract".

SharePoint cannot express this, because SharePoint permissions are additive. There is no “and” between two groups:

SharePoint: two entries on the migrated page

  Confluence page             migrated SharePoint page
  "Contract"     ──────────►  "Contract.aspx"
                              ├─ Engineering: Read  ─┐
                              └─ Purchasing:  Read  ─┴─►  means "Engineering OR Purchasing"

      Group "Engineering"
     ┌──────────────────────────┐
     │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│  Group "Purchasing"
     │▒▒▒▒▒▒▒▒▒▒▒▒▒▒┌───────────┼──────────────┐
     │▒▒▒▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
     │▒▒▒▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
     │▒▒▒▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒│▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
     └──────────────┼───────────┘▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
                    │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
                    └──────────────────────────┘

     ▒ = members of either group. All of them may read "Contract.aspx".

  Result: far more people would have access than in Confluence.

There are two ways out, and WikiTraccs deliberately takes neither.

The first is to expand both groups to their members and write the overlap to the page as a list of individual users. That would be a snapshot that becomes wrong the moment someone joins or leaves one of the groups.

The second is to create a new group for the overlap and give that group access. This one stays correct over time, because a group can be maintained. But it needs a new group for each overlap that occurs in the page tree, and somebody must keep each of them up to date. A tree with many restricted branches produces many such groups, and the administration effort grows with them.

Instead, WikiTraccs reports such pages as a failed permission transaction with the reason “cannot merge hierarchical restrictions”. They show up in the Page Transactions (WikiTraccs) list, where you can work through them one by one. Rather than guess, WikiTraccs grants nothing for these pages.

Two more points about groups:

WikiTraccs does not create groups. A Confluence group is mapped to a SharePoint group that must already exist, both in the WikiTraccs site and in every target site.
Nested groups in Confluence have no direct counterpart in SharePoint.

Summary of the Rules

Number of permission scopes. Each restricted page gets one unique permission scope. Microsoft permits 50,000 unique scopes in one library and recommends less than 5,000. If you have many restricted pages, use more than one target site.
Groups along the tree. If the parent page and the child page name different groups, the result is an overlap of groups. SharePoint cannot show this overlap. WikiTraccs reports these pages as failed permission transactions. See the section above.
Page restrictions only. WikiTraccs does not migrate space permissions and global permissions. You set up access to the target site. WikiTraccs takes care of the pages.
Two permission levels only. WikiTraccs maps Confluence “view” to SharePoint Read and Confluence “edit” to SharePoint Contribute. You cannot change this mapping.
Unknown principals get no access. If WikiTraccs cannot map a user or a group to an Entra ID user or a SharePoint group, WikiTraccs breaks the inheritance and gives access only to the principals that it could map. This prevents access for the wrong people. It can also prevent access for the correct people.
Edit restriction without view restriction. If a page has an edit restriction and no view restriction, WikiTraccs gives Read to “Everyone except external users”.
Maximum of 200 entries. WikiTraccs reads a maximum of 200 entries from each restriction list in Confluence (view users, view groups, edit users, edit groups).
Attachments have the permissions of the page. WikiTraccs puts the attachments of a page in one folder in the Site Assets library. SharePoint also puts page attachments there. When the permissions of the page change, SharePoint applies the same change to the folder. This is a standard SharePoint function. See Page Attachments and External Images.

Wrap-Up

My observation. Most customers do not migrate page restrictions, and most of them are fine with that. The migration is the moment when they rebuild the permissions in SharePoint from the start and drop the exceptions that collected in Confluence over the years.

My recommendation. Do not migrate page restrictions if you can avoid it. Set up access at the site level and protect only the pages with sensitive content. Fewer unique permission scopes mean less administration, and they keep the permissions visible. A page with broken inheritance is easy to forget. Nobody sees it in the site settings, its permissions go stale, and each one must be maintained by hand.

If you do migrate page restrictions, remember that the result is not a 1:1 copy. Examine it before you give your users access to the content.

←Previous