Registering WikiTraccs as app in Entra ID
I recently got the following inquiry about WikiTraccs:
Please explain again briefly what the Tenant ID and Azure Client IDs are and how to acquire them.
This request is not the first of its kind and totally understandable. It refers to the following configuration in WikiTraccs.GUI:
Unless you are a Microsoft 365 developer or admin you normally never have to care about those IDs.
Why do I have to enter Tenant ID and Client ID in WikiTraccs? Where do those come from?
When WikiTraccs creates your migrated pages in SharePoint it needs to access APIs provided by Microsoft. Those are the SharePoint API and the Microsoft Graph API.
Accessing SharePoint in any form requires authentication. Open <company>.sharepoint.com (replace ‘<company>’ with the actual value of your SharePoint) in a private browser tab and it will ask for your credentials like email address and password.
Authentication is also required when WikiTraccs starts the migration. It will open a browser window for you to sign in.
Migration Account
It’s recommended to create a dedicated migration account. This account will be granted permissions to migration target sites only for the duration of the migration.Besides users, applications like WikiTraccs have to authenticate as well to access SharePoint.
To allow an application to authenticate, it has to be registered in Entra ID (formerly known as Azure Active Directory, or Azure AD). This is a manual configuration that needs to be done once.
A registered application has an ID - the Client ID. And the Entra ID tenant it is created in also has an ID - the Tenant ID. Those are the IDs needed by WikiTraccs.GUI.
How to register WikiTraccs as Application in Entra ID?
In a browser, navigate to https://entra.microsoft.com.
Sign in with an account that has the Application Developer role in Entra ID.
The Microsoft Entra admin center (former Azure Active Directory portal) opens.
In the left menu, under Applications, select App registrations, then New registration:
The Register an application blade opens:
Configure the following:
- under Name enter WikiTraccs Migration Tool (note: or any other name of your choosing)
- under Supported account types select Accounts in this organizational directory only
- under Redirect URI (optional) choose Public client/native (mobile & desktop) and type http://localhost in the edit field
Select Register to confirm the app registration.
The application’s settings are now open:
In the left menu, under Manage, choose API permissions.
Choose Add a permission to add the following permissions:
- Microsoft Graph > Sites.FullControl.All (delegated)
- SharePoint > AllSites.FullControl (delegated)
Make sure to select the Delegated permissions (not application permissions). Here’s a sample screenshot:
The configured permissions need to be consented by the tenant admin.
As a tenant admin, choose Grant admin consent for… and confirm:
In the left menu choose Overview and make note of both the Tenant ID (aka Directory ID) and Client ID (aka Application ID):
Those IDs need to be entered in WikiTraccs.GUI as Tenant ID and Azure AD Application Client ID.
What did I just configure? Can WikiTraccs now access all content in SharePoint?
NO, WikiTraccs can NOT access all content in SharePoint.
Let me explain.
When starting a migration with WikiTraccs you have to log in with a Microsoft 365 account.
Now the permissions WikiTraccs gets are the intersection of two things:
- the delegated permissions you configured above (that is Sites.FullControl.All, AllSites.FullControl) AND
- the permissions of the account you logged in with
This is the magic behind delegated permissions. WikiTraccs can only access as much of SharePoint as the logged-in account.
If you log in with an account that is owner in all sites - sure, WikiTraccs could now access those sites.
But if you log in with a dedicated migration account that has only access to some sites - WikiTraccs can now only access those, nothing more.
Are there alternatives to those permissions?
I hear from customers who have trouble to get the tenant admin to consent permissions.
Use less permissions, get less things migrated
If you can’t get admin consent for FullControl permissions you can try using the following Manage permissions instead:
- Microsoft Graph > Sites.Manage.All (delegated)
- SharePoint > AllSites.Manage (delegated)
Those allow a content migration as well.
But the functionality of WikiTraccs will be limited somewhat:
- 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
Note that an admin can also grant admin consent to those permissions.
Use an existing application
If you have access to another Entra ID application that has the required permissions configured you can use the Client ID of this existing app.
That’s why there is the Use M365 PnP Client ID button in WikiTraccs.GUI. It enters the well-known ID of the application used by PnP.PowerShell. This only works, if you have access to and the needed permissions are configured for the application (this is not always the case!). Note: The multitenant PnP.PowerShell enterprise application has been retired by Microsoft.
Troubleshooting
Check the platform
There is one common oversight when configuring the Entra ID application: selecting the right platform.
You might see the following error when testing the connection to SharePoint or starting the migration if the platform is not correct:
“A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details. Original exception: AADSTS7000218: The request body must contain the following parameter: ‘client_assertion’ or ‘client_secret’.”
This error happens when the platform of the Entra ID application has been set to Web instead of Public client/native (mobile & desktop).
Change the platform to Public client/native (mobile & desktop), which then shows up as Mobile and desktop applications here:
The error should now be gone.
Check the redirect address after authenticating
After logging in to Microsoft 365 via the browser, a redirect to http://localhost happens in the browser address bar.
This has to look like this:
Normally WikiTraccs takes over from this point. Get in touch if there are issues.
Test connecting with PnP.PowerShell
You can use PnP.PowerShell to check if an authentication issue is related to your Entra ID application configuration, or related to WikiTraccs doing something wrong.
Start PowerShell 7 and install the PnP.PowerShell module.
Configure and run the following script:
# make sure to use PowerShell 7 and install the PnP.PowerShell module; use the following command for that
# Install-Module PnP.PowerShell -Scope CurrentUser
# enter your SharePoint site to connect to here (the same as in WikiTraccs, either WikiTraccs site or default target site):
$siteUrl = "https://contoso.sharepoint.com/sites/somesite"
# enter your Entra ID application client id (application id) here (the same as in WikiTraccs):
$clientId = "017d043a-df74-4ab0-a411-430104faeaa4"
# authenticate with app, as user, and open login dialog in new browser window
Connect-PnPOnline -Url $siteUrl -ClientId $clientId -Interactive -LaunchBrowser:$true
# this should print the title of the site we connected to, if the connection was successful
Get-PnPWeb
This PowerShell script should open the Microsoft 365 login experience in the browser, just like WikiTraccs does. After logging in, it should print the title of the site you connected to. Otherwise, there will be an error that might help diagnose the app configuration issue.
Check that the migration user has access to the target SharePoint sites
If the migration user has no access to the SharePoint site, the following error might be shown:
Error while testing connection to target site...
HttpResponseCode: 403
Code: System.UnauthorizedAccessException
Message: Attempted to perform an unauthorized operation
Make sure the migration user account is site collection administrator of all target sites and the WikiTraccs site.
Check that the migration user is site collection administrator of the target SharePoint sites
If the migration user has only limited access to the SharePoint site, the following error might be shown:
Successfully connected to target site '2024-11-05-permission-test-deleteme2' but permissions are missing - refer to the docs for details
(view list items: YES, view pages: YES, allowed to approve items: NO, manage lists: NO, add and customize pages: NO, manage the site: NO).
Please give permissions, site admin works well. See log for details. Cannot continue for now.
This happens if the migration user is only visitor, member, or contributor in the site. Those limited permission levels don’t allow WikiTraccs to properly migrate pages.
Make sure the migration user account is site collection administrator of all target sites and the WikiTraccs site.
Check the log files for details
Note: this log output is avilable as of WikiTraccs v1.20.40.
WikiTraccs logs information about both the Entra ID authentication result and the SharePoint site access to the common log files.
When authenticating with Entra ID, WikiTraccs receives an access token. The claims of those access token can be seen in the log files:
[ 15:59:14 INF] #1 === START Claims of Access Token === |
[ 15:59:14 INF] #1 aud=00000003-0000-0ff1-ce00-000000000000 |
[ 15:59:14 INF] #1 amr=pwd |
[ 15:59:14 INF] #1 amr=mfa |
[ 15:59:14 INF] #1 app_displayname=Confluence Migration |
[ 15:59:14 INF] #1 appid=abcae113-5a68-4df9-b0f9-70243943beef |
[ 15:59:14 INF] #1 family_name=Vance |
[ 15:59:14 INF] #1 given_name=Adele |
...
[ 15:59:14 INF] #1 scp=AllSites.FullControl Sites.FullControl.All |
[ 15:59:14 INF] #1 tid=1acdc182-0353-4ee1-b9fa-225ce104406b |
[ 15:59:14 INF] #1 === END Claims of Access Token === |
Above claims show that user Adele Vance authenticated with app Confluence Migration, using interactive login, being granted delegated permissions AllSites.FullControl and Sites.FullControl.All. You can use that to double-check your configuration.
Then, when accessing SharePoint, WikiTraccs logs information about the migration user’s access to the SharePoint site:
[ 15:59:14 INF] Logging SharePoint site 'Test Site' (/sites/test-site) permission details (for diagnosing access-related issues): |
[ 15:59:14 INF] PermissionKind."ViewListItems": true |
[ 15:59:14 INF] PermissionKind."AddListItems": false |
[ 15:59:14 INF] PermissionKind."EditListItems": false |
[ 15:59:14 INF] PermissionKind."ManageLists": false |
...
[ 15:59:14 INF] PermissionKind."ManageWeb": false |
[ 15:59:14 INF] PermissionKind."FullMask": false |
Here, the migration user appears to have read-only access because they are allowed to view list items, but are not allowed to add list items, or manage lists.
Make sure the migration user account is site collection administrator of all target sites and the WikiTraccs site.
Incremental consent missing for “Manage” scopes?
Incremental consent might be required, if, after successful authentication, WikiTraccs shows (and logs) messages that look like those:
No permission granted to SharePoint, whatsoever.
Some permission to SharePoint has been granted via other permission scopes, but not enough to even read content.
WikiTraccs asks for the special .default permission scope when the user authenticates with Entra ID. The resulting access token contains all permission scopes that have been consented to by an admin on behalf of the organization (note: this is required for all FullControl scopes), and scopes that have been already consented to by the migration account.
The latter will cause issues when working with Sites.Manage.All and AllSites.Manage scopes that don’t require admin consent. Those scopes might be missing from the access token. Refer to the log files to check the presence of those scopes.
Specifically, when Sites.Manage.All or AllSites.Manage are missing in WikiTraccs’ access token, you have to invoke the consent dialog for those scopes for the migration account with an individual consent URL that looks like this:
https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/authorize
?client_id=11111111-0000-0000-0000-000000000000
&response_type=code
&redirect_uri=http://localhost
&response_mode=query
&prompt=select_account
&scope=https://graph.microsoft.com/Sites.Manage.All+https://contoso.sharepoint.com/AllSites.Manage
Modify above URL template as follows:
- Instead of 00000000-0000-0000-0000-000000000000, enter your SharePoint Tenant ID (note: you can see the tenant ID in the blue WikiTraccs window)
- Instead of 11111111-0000-0000-0000-000000000000, enter the client ID of your Entra ID application
- In https://contoso.sharepoint.com/AllSites.Manage replace contoso.sharepoint.com with your SharePoint host
So, the URL might look like this:
Open a browser where the migration account is authenticated to SharePoint, copy the final URL to the browser address bar and press the Return key, to navigate to this address. Follow the login flow.
Eventually, a consent dialog like the following should open in the browser:
Click Accept to give consent. This unblocks the migration.
Repeat the connection test in WikiTraccs. The error message should change, telling you that you don’t have full control access, but that migration should still work. Also, when starting the migration, it should now create pages in SharePoint.
Wrap-up
WikiTraccs needs an Entra ID application registration to access SharePoint. This is true for all applications integrating with Microsoft 365 services.
A common challenge is getting the right people to consent the configuration. The purpose of the app needs to be communicated clearly.
Technically, registering the app registration is quickly done following the steps in this post.
And last but not least, the migration user needs proper access to all target SharePoint sites.
Try WikiTraccs!
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.