Authentication

• 1: Authenticating with Confluence
• 1.1: Interactive Confluence Authentication
• 1.2: Token-Based Confluence Authentication
• 2: Authenticating with SharePoint Online
• 2.1: Required permissions for SharePoint Online
• 3: Proxy Authentication

1 - Authenticating with Confluence

The following authentication methods are currently supported:

• Interactive authentication (note: this also covers anonymous access)
• Token-based authentication (Confluence 7.9 and later support the use of personal access tokens, and Confluence Cloud)

Interactive Authentication

With this authentication method WikiTraccs uses the context of a logged-in user account. It also covers anonymous access.

Read more: Interactive Authentication

Token-based Authentication

Note: this option is available as of WikiTraccs v1.13 and works with Confluence 7.9 and later, and Confluence Cloud.

Read more: Token-based Authentication

Required permissions in Confluence

The permissions of the Confluence account you log in with determine what can be migrated.

The easiest approach is to log in with a Confluence admin account that has access to all spaces that should be migrated. This allows for content and permission migration.

But maybe you don’t want to use a Confluence admin account. In this case you can also use an account that is space admin in all to-be-migrated spaces. This allows for content and permission migration of those spaces.

The least permissive approach is to use an account that is no admin whatsoever but has normal user permissions like view and edit. This allows for migration of content this account has access to, which might not be all pages. Permission migration is not possible with a non-admin user account.

Certain operations like retrieving user account information or group memberships might be prohibited for non-admin users which might hinder WikiTraccs. If you see such errors in the log try using an account that has more permissions.

1.1 - Interactive Confluence Authentication

With interactive authentication, WikiTraccs uses the context of a user account you log in with.

Interactive Authentication

To authenticate with Confluence, WikiTraccs will open a browser window.

In the browser, WikiTraccs opens Confluence and adds a panel as overlay to the Confluence page, telling you to log in:

Note: the design and text of the panel might change in future releases.

Now log in to Confluence like you normally would. If the panel that WikiTraccs added is in the way, use its buttons to move it out of the way or hide it.

As soon as WikiTraccs got what it needs, it will automatically close the browser. Wait for the browser to close.

WikiTraccs will use the cookies from the authenticted browser session to access Confluence.

The following diagram shows how WikiTraccs uses cookies to make authenticated calls to Confluence:

Experimental alternative to obtain cookies (compatible with Kerberos)

When WikiTraccs is unable to make authenticated calls to Confluence and all troubleshooting fails, you might try an experimental option introduced in release 1.10.16.

This changes the flow like this:

All requests to Confluence are routed through the browser, in the context of the authenticated user session.

This mode can be activated in WikiTraccs.GUI via Settings > Misc > Proxy Confluence API calls through browser.

Anonymous Access

If you choose Anonymous authentication mode, WikiTraccs will still open Confluence in the WikiTraccs-controlled browser. You don’t have to log in. The browser will close eventually and WikiTraccs continues, accessing Confluence using an anonymous user session.

1.2 - Token-Based Confluence Authentication

Note: token-based authentication is available as of WikiTraccs v1.13 and works with Confluence 7.9 and later, and Confluence Cloud.

Refer to Atlassian’s documentation on how to create a personal access token: Using Personal Access Tokens.

2 - Authenticating with SharePoint Online

The following authentication methods are currently supported by WikiTraccs:

• interactive authentication (supports MFA)
• device-code authentication (supports MFA)
• client credentials authentication (no MFA support)
• certificate authentication (app-only, no migration account required)

Each of those authentication methods requires an Entra ID application to exist in Entra ID. WikiTraccs has to know the ID (“client ID”) of this application.

Prerequisites

When “authenticating with SharePoint Online” you are in fact authenticating with an Entra ID application that must be configured to authorize the access to SharePoint Online. Such an Entra ID application has to either exist or you have to register a new one.

You might have to register a new Entra ID application for use with WikiTraccs. This can be done manually in the Azure Portal or via PnP PowerShell. A sample on how to do this via PnP PowerShell is shown here: Register your own Entra ID App.

For the specific permissions to configure on the Entra ID application and the permissions the SharePoint account needs on target sites, see: Required permissions for SharePoint Online.

Ultimately - regardless of the Entra ID application you choose to use - WikiTraccs needs to know the ID of this application, and the application (plus the SharePoint account, under interactive/delegated auth) has to permit a certain amount of access to the target sites where WikiTraccs will migrate Confluence content to.

Interactive authentication

Interactive authentication allows to sign-in with a user that will be used to access SharePoint Online. The user account needs appropriate permissions on the target SharePoint site - see Required permissions for SharePoint Online for the scenarios and the recommended minimum role.

With interactive authentication multi-factor authentication (MFA) is fully supported.

Choose Interactive as Target: Authentication type.

Enter the Entra ID application ID into the Azure AD Application Client ID input field. (Note: This ID looks like “31359c7f-bd7e-475c-86db-fdb8c937548e”.) The user must be granted access to the Entra ID application that is used to authenticate with.

Also fill the Target SharePoint Site Address and Target Tenant ID fields.

Select the Test SharePoint connection to test connecting. A dialog window will appear to display the result of this test.

Device code authentication

Available.

Client credentials authentication

Available, but often not feasible due to MFA or CA requirements.

Certificate authentication

Certificate authentication is an app-only authentication method: WikiTraccs authenticates as the Entra ID application itself, using a certificate as credential. There is no migration user account, no interactive sign-in, and no browser window.

This is the recommended option for unattended migrations and for environments where creating and maintaining a dedicated migration user account is impractical. It pairs naturally with the Sites.Selected application permission, where an admin grants the app access on each target site individually - but the option is not tied to Sites.Selected and works with broader application permissions as well.

Comparison to interactive authentication

With interactive authentication you sign in as a user, and WikiTraccs inherits the intersection of that user’s permissions and the delegated scopes configured on the Entra ID application. A migration user account is required, with appropriate site permissions (see Required permissions for SharePoint Online).

With certificate authentication there is no user. WikiTraccs authenticates as the app, and SharePoint evaluates the app’s own permissions. No migration account is needed - which is why this mode is the best fit for Sites.Selected.

Prerequisites

• An Entra ID application registered in the target tenant (same as for the other authentication methods - see Registering WikiTraccs as App in Entra ID).
• A certificate whose public key has been uploaded to the app registration (Certificates & secrets → Certificates → Upload certificate). The matching .pfx (private key) stays on the machine that runs WikiTraccs.
• Application permissions configured and admin-consented on the app registration, plus a per-target-site grant if Sites.Selected is used. See Required permissions for SharePoint Online for the full permission matrix, and Configuring Sites.Selected Authentication for WikiTraccs for the end-to-end walkthrough.

Configuration in WikiTraccs

Choose Cert as the SharePoint authentication type.

Fill the Tenant ID and Entra ID Application Client ID fields at the top of the screen the same way you would for the other auth modes.

In the Certificate field, enter either:

• the absolute or relative path to the .pfx file (the path is resolved against the working directory and normalized to absolute when saved), or
• the SHA-1 thumbprint of a certificate that has been imported into the Windows certificate store (CurrentUser\My or LocalMachine\My)

WikiTraccs auto-detects which form you entered: a 40-character hex string (optionally with spaces or colons) is treated as a thumbprint, anything else as a file path. The Verify button next to the input field checks the certificate on demand - it loads the cert the exact same way the migration will later, and prompts for a PFX password if the file is password-protected. A successful verify shows the certificate’s subject and expiration date.

If the certificate file is password-protected, WikiTraccs prompts for the password the first time it needs it (either via the Verify button or at migration start). The entered password is stored in the configuration file alongside the certificate path, consistent with how WikiTraccs stores other secrets. Subsequent runs reuse the stored password without prompting.

At migration start, WikiTraccs performs a hard certificate check before any network call: the certificate is loaded, the password is validated, and on failure the migration aborts cleanly with a clear error message. This avoids half-started migrations caused by a misconfigured or expired certificate.

See the dedicated blog post for an end-to-end walkthrough of the Sites.Selected configuration and how to run WikiTraccs under certificate authentication: Configuring Sites.Selected Authentication for WikiTraccs.

2.1 - Required permissions for SharePoint Online

WikiTraccs requires two distinct permission surfaces to be configured for a Confluence to SharePoint Online migration:

1. SharePoint account permissions - the role held by the migration user on each target site (applies to interactive, credentials, and device-login authentication), or the role held by the application on each target site (applies to app-only certificate authentication with Sites.Selected).
2. Entra ID application permissions - the scopes configured on the Entra ID app registration that WikiTraccs authenticates through.

This page documents the supported combinations of the two, their limitations, and the configurations that are insufficient.

SharePoint account permissions on target sites

The migration account is expected to hold site-scoped admin-level permissions on each site that participates in the migration. The SharePoint Administrator and Microsoft 365 Global Administrator directory roles are not required.

Role model

SharePoint Online distinguishes two roles with “Full Control”:

• Site Owner - holds Full Control on the site. Permits creating lists, libraries, content types, and pages; setting page metadata (Author, Editor, Created, Modified); and managing permissions. When permissions inheritance is broken on a specific item (for example, a page), a Site Owner account retains access to that item only if it is still present in that item’s access control list.
• Site Admin (formerly Site Collection Administrator) - holds all Site Owner capabilities and, in addition, retains access to every item in the site collection regardless of the item-level access control list. A Site Admin account is therefore not locked out of items where permissions inheritance has been broken, even when the account is not listed in the item’s permissions. Site Admin also permits managing search, the recycle bin, and site collection features. Reference: Admin center site permissions reference.

Recommended default: Site Owner

For migration runs performed by a single account, Site Owner on every target site (and on the WikiTraccs site) is sufficient. Full Control covers all operations WikiTraccs performs:

• creating lists, fields, content types, and modern SharePoint pages
• setting page metadata: Author, Editor, Created, Modified
• uploading attachments
• breaking inheritance on individual pages and applying page-level restrictions

The migration account is preserved in the page access control list during the break-inheritance step. The account therefore retains access to each page it migrates.

When Site Admin is required

Site Admin only becomes relevant when Confluence page restrictions are migrated to SharePoint. Without permission migration, WikiTraccs does not break inheritance on pages, and Site Owner is sufficient.

Migrating page restrictions is generally not recommended - the Confluence and SharePoint permission models differ in ways that often make direct migration impractical. See Mapping principals and migrating permissions for the full discussion.

If permission migration is enabled, Site Admin is recommended to circumvent access-related issue, for example when multiple migration accounts are involved, or permission-related issues need to be investigated.

Insufficient account permissions

• Contribute, Edit, or Read. Full Control is required to break inheritance, set system fields, and apply provisioning templates.
• SharePoint Administrator or Microsoft 365 Global Administrator alone. Tenant-level roles are not a reliable substitute for per-site access; some per-site operations still require the account to hold at least Read on the site. When in doubt, grant Site Owner or Site Admin explicitly.

Entra ID application permissions

Each authentication mode requires an Entra ID application that WikiTraccs authenticates through. The permissions configured on the application determine which API scopes WikiTraccs can request.

Recommended default for interactive, credentials, and device-login authentication: FullControl delegated

• Microsoft Graph > Sites.FullControl.All (delegated) - requires admin consent
• SharePoint > AllSites.FullControl (delegated) - requires admin consent

Under delegated authentication, WikiTraccs receives the intersection of the signed-in user’s permissions and these scopes. The user account must additionally hold Site Owner or Site Admin on the target sites (see SharePoint account permissions).

Intermediate configuration: Manage delegated

If an administrator is unable to consent FullControl scopes in the target tenant:

• Microsoft Graph > Sites.Manage.All (delegated) - no admin consent required
• SharePoint > AllSites.Manage (delegated) - no admin consent required

Migrations continue to succeed with this configuration, at the cost of reduced capability:

• Page permissions cannot be configured. WikiTraccs cannot break inheritance or apply page restrictions under Manage scopes.
• Author, Editor, Created, and Modified cannot be set. Setting these system fields falls under the same permission category as managing permissions.

This configuration is appropriate in tenants where admin consent for FullControl is not available.

Recommended default for certificate and app-only authentication: Sites.Selected application with per-site FullControl

• Microsoft Graph > Sites.Selected (application) - requires admin consent
• SharePoint > Sites.Selected (application) - requires admin consent

On the app registration’s API permissions page, both Sites.Selected entries (the Microsoft Graph one and the SharePoint one) must display the “Granted for [Tenant]” status with the green checkmark. Adding the permission rows alone is not sufficient; admin consent must be granted explicitly.

In addition, the application must be granted FullControl on every target site and on the WikiTraccs site via Microsoft Graph. The roles Read, Write, and Manage are also available, but WikiTraccs requires FullControl for the same reasons interactive authentication requires Site Owner.

For the end-to-end configuration procedure, see Configuring Sites.Selected Authentication for WikiTraccs.

Intermediate configuration for certificate authentication: broader FullControl application permissions

If per-site scoping is not a requirement in the target environment:

• Microsoft Graph > Sites.FullControl.All (application) - requires admin consent
• SharePoint > Sites.FullControl.All (application) - requires admin consent

The application receives tenant-wide Full Control. Configuration is simpler because no per-site grants are needed, at the cost of tenant-wide SharePoint access that defeats the point of choosing app-only authentication for isolation. This configuration is listed for completeness; Sites.Selected is the recommended default.

Quick reference

Related

• Authenticating with SharePoint Online - reference for the supported authentication modes (Interactive, Device Login, Credentials, Certificate)
• Registering WikiTraccs as App in Entra ID - step-by-step application registration procedure
• Configuring Sites.Selected Authentication for WikiTraccs - end-to-end Sites.Selected configuration, including Microsoft Graph Explorer
• Run an Automated Confluence to SharePoint Migration - unattended migration with certificate authentication
• WikiTraccs FAQ - access levels

3 - Proxy Authentication

Note: Proxy authentication is available as of WikiTraccs v1.31.10.

You’ll see that your proxy requires authentication when you see an error like this when running the Confluence connection check:

HTTP Status code 407 translates to Proxy Authentication Required

Configuring Proxy Authentication

WikiTraccs allows you to configure proxy authentication.

In the main menu of the blue WikiTraccs window, click Settings ⇒ Configure Transformation to open the Settings dialog.

In the Settings dialog, click the Proxy tab.

Choose the proxy authentication option that is right for your proxy:

• None: No authentication required
• Default credentials: Authenticates using your current Windows login
• Credentials: Set user name and password, as well as an optional domain
  • note: the password is stored in cleartext in the appsettings.json file

Restart WikiTraccs after changing those settings.