This is the multi-page printable view of this section. Click here to print.
1 - 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 Azure AD application to exist. WikiTraccs has to know the ID of this application.
NoteUnder the hood WikiTraccs uses the PnP Core library that is also used by PnP PowerShell. Thus concepts regarding authentication are similar. That’s why this documentation will link to PnP documentation at certain points.
TipUse interactive authentication for starters. It’s the easiest option that gives good interactive feedback if something goes wrong.
NoteThis section uses PnP PowerShell for Azure AD application management. Refer to Installing PnP PowerShell on how to install PnP PowerShell.
When “authenticating with SharePoint Online” you are in fact authenticating with an Azure AD application that must be configured to authorize the access to SharePoint Online. Such an Azure AD application has to either exist or you have to register a new one.
If you are lucky then there is already an Azure AD application registered that you can use. One example for an existing application is the Azure AD application that is registered when using PnP PowerShell. The registration of this application is documented here: Setting up access. The cmdlet to use is
TipYou can try using this PnP application with WikiTraccs.GUI. Select the Use M365 PnP Client ID button to fill in the ID of this application. Please also check the permissions of this application since they sometimes are incomplete or not admin-granted.
You can also register a new Azure AD 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 Azure AD App.
The following permissions must be configured for the Azure AD 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 Azure AD 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.
NoteThe following assumes you are using WikiTraccs.GUI.
NoteIn WikiTraccs.GUI there is a Test SharePoint connection button. You can select this button at any time to test if the configuration is right and the authentication succeeds. This also checks that the permission level is sufficient.
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 Azure AD 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 Azure AD 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.
AttentionThe sign-in experience will be opened in a regular browser window (that might already be open) and not in a new, dedicated window. This is due to cross-platform restrictions that need to be solved. This could cause problems when already being logged in with a user account that is different from the one to be used for WikiTraccs. In this case just copy the URL from the address bar to another browser window where you sign in with the right user.
Device code authentication
This authentication mode is currently not supported in WikiTraccs.GUI and only available in WikiTraccs.Console.
Documentation is tbd.
Client credentials authentication
Documentation is tbd.
2 - Authenticating with Confluence
The following authentication methods are currently supported:
- cookie-based authentication
With this authentication method WikiTraccs uses the context of a logged-in user account.
To authenticate with Confluence WikiTraccs will open a Chrome browser window.
NoteCurrently only the Chrome browser is supported.
Log in to Confluence like you normally would. WikiTraccs will use the cookies from the authenticted browser session to access Confluence.
NoteWikiTraccs opens and controls the browser window you use to log in. This is necessary so that WikiTraccs can access cookies. A note about this automation will be shown at the top of Chrome, which is expected.
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.