Registering WikiTraccs as app in Azure AD
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 AccountIt’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 Azure Active Directory (Azure AD). This is a manual configuration that needs to be done once.
A registered application has an ID - the Client ID. And the Azure AD 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 Azure AD?
In a browser, navigate to https://entra.microsoft.com.
Sign in with an account that has the Application Developer role in Azure AD.
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 you can try using the following 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
Use an existing application
If you have access to another Azure AD 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!).
There is one common oversight when configuring the Azure AD 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 Azure AD 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.
WikiTraccs needs an Azure AD 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.
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.