This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Authentication

This article is a resource where you can find authentication information for WikiTraccs.

1 - Authenticating with Confluence

This article is a resource where you learn about 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

This article is a resource where you learn about authenticating with Confluence.

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 Chrome 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 Chrome 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

This article is a resource where you learn about authenticating with Confluence.

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

This article is a resource where you learn about 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)

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.

The following permissions must be configured for the Entra ID application:

  • delegated permissions in Microsoft Graph: Sites.FullControl.All (note: requires admin consent)
  • delegated permissions in SharePoint: AllSites.FullControl (note: requires admin consent)

What if FullControl cannot be granted? There is a plan B but with less features.

The following permissions will allow migrations as well:

  • delegated permissions in Microsoft Graph: Sites.Manage.All (note: no admin consent required)
  • delegated permissions in SharePoint: AllSites.Manage (note: no admin consent required)

Without full control permissions WikiTraccs will be limited in what it can migrate:

  • page permissions cannot be configured, as WikiTraccs won’t be allowed to do so
  • out-of-the-box SharePoint page and file metadata Created By, Created (Date), Modified By, Modified (Date) cannot be set, as this requires the same permissions as configuring permissions

Ultimately - regardless of the Entra ID application you choose to use - WikiTraccs needs to know the ID of this application and the application 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. Use a user account that has Owner permissions on the target SharePoint site.

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.