Configuring Sites.Selected Authentication for WikiTraccs

Most WikiTraccs migrations sign in with a user account. For hands-on work that is the easiest path.

Some environments rule that out: automation is required, or the security team does not allow a tenant-wide app permission. The combination of Sites.Selected and certificate authentication fits both cases. Access is granted per target site, and WikiTraccs signs in as the application itself.

Why Sites.Selected, and why a certificate?

There are two common drivers:

• Automation. A scheduled or scripted Confluence to SharePoint migration run cannot wait for a browser sign-in. Certificate authentication removes the migration user from the picture.
• Security posture. An app with Sites.FullControl.All at the tenant scope can reach every site. Sites.Selected starts with the app having no access at all; an admin adds it to each target site explicitly. Configuration stays auditable and easy to revoke.

Either motivation leads to the same setup: an Entra ID app with Sites.Selected application permission, a certificate credential, and a FullControl grant on every site WikiTraccs will touch.

How to grant per-site FullControl

Here are three options to grant an app permissions on specific sites:

1. PnP PowerShell - Grant-PnPAzureADAppSitePermission. One cmdlet per site. Requires PnP PowerShell and the PnP Management Shell app admin-consented in the tenant.
2. Microsoft Graph Explorer - a browser tool at developer.microsoft.com/graph/graph-explorer. REST calls pasted into the URL bar.
3. Scripting Microsoft Graph directly - curl, Invoke-RestMethod, or any HTTP client. Same calls as Graph Explorer.

All three call the same endpoint: POST /sites/{site-id}/permissions.

In this post we use the Microsoft Graph Explorer because it needs no installation.

Prerequisites

Accounts and roles

You need an account that:

• holds the SharePoint Administrator directory role (or higher), and
• can consent to Sites.FullControl.All for Graph Explorer. A Global Administrator must grant that consent once - either tenant-wide, or individually for themselves.

Running the entire configuration as a Global Administrator is the simplest option. Global Admin covers the role requirement of POST /sites/{id}/permissions and can self-consent to Sites.FullControl.All without making the scope available tenant-wide.

Entra ID application

You need an app registration with a certificate. See Registering WikiTraccs as App in Entra ID for the basic registration flow.

For Sites.Selected, three details differ from the interactive-auth flow:

1. Permission type: Under API permissions, pick Application permissions (not Delegated permissions).
2. Permissions: Add Sites.Selected on both Microsoft Graph and SharePoint. WikiTraccs talks to SharePoint through both APIs; each needs its own grant.
3. Credential: Under Certificates & secrets, Certificates tab, upload the public key of your certificate (.cer or .pem). The .pfx with the private key stays on the migration machine. Do not upload the .pfx.

After adding both Sites.Selected rows, click Grant admin consent for [Tenant]. Both rows must show the green “Granted for [Tenant]” checkmark.

Target SharePoint sites

The following SharePoint sites matter:

• the WikiTraccs site, where WikiTraccs stores its lists (space inventory, user/group mapping, page transactions, content snapshots)
• the target sites, where Confluence content lands

Grant FullControl to the app on each. For multiple target sites, grant each one. Refer to the next section on how to do that via Microsoft Graph Explorer.

Configuring with Microsoft Graph Explorer

Open developer.microsoft.com/graph/graph-explorer and sign in with your Global Administrator account.

Consent to the required scope

Open the Modify Permissions tab (next to Request Body, Request Headers, Access token). Find Sites.FullControl.All (Delegated) and click Consent.

When the sign-in dialog appears, leave the “Consent on behalf of your organization” checkbox unchecked. As a Global Administrator you can self-consent without granting the scope to every user in the tenant. Click Accept.

To verify that the scope landed on the token, open the Access token tab, copy the JWT, paste it into jwt.ms, and check that the scp claim contains Sites.FullControl.All. If consent was done mid-session and the token predates it, sign out and back in.

Resolve each site’s ID

Microsoft Graph identifies SharePoint sites by a composite ID of the form <hostname>,<site-collection-guid>,<web-guid>. Given a URL path, Graph Explorer returns that composite ID.

Set the verb dropdown to GET and paste this URL into the URL bar:

https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<SITENAME>

For a tenant called contoso and a site named Marketing, the URL looks like this:

https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/Marketing

Click Run query.

Copy the id field from the response. For the example above, the response contains something like:

{
  "id": "contoso.sharepoint.com,e3a1c643-6d61-4847-b4f2-b1449917e667,59c6df0e-f8b9-4069-a681-304929c3e132",
  "webUrl": "https://contoso.sharepoint.com/sites/Marketing"
}

Repeat for every site. Keep the commas intact when pasting the ID later; do not URL-encode them.

Grant FullControl to the app

Switch the verb dropdown to POST and paste this URL into the URL bar:

https://graph.microsoft.com/v1.0/sites/<site-id>/permissions

For the site ID resolved in the previous step, the URL looks like this:

https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,e3a1c643-6d61-4847-b4f2-b1449917e667,59c6df0e-f8b9-4069-a681-304929c3e132/permissions

In the Request Body tab, paste the JSON below:

{
  "roles": ["fullcontrol"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "<your-client-id>",
        "displayName": "WikiTraccs Migration Tool"
      }
    }
  ]
}

Replace <your-client-id> with your Entra ID app’s client ID. The displayName is echoed back by Microsoft but not validated; any human-readable string works. A filled-in body looks like this:

{
  "roles": ["fullcontrol"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "823f5a22-be23-457a-beda-6adafc50d758",
        "displayName": "WikiTraccs Migration Tool"
      }
    }
  ]
}

Click Run query. 201 Created means success. Repeat for every site.

Valid roles: read, write, manage, fullcontrol. WikiTraccs requires fullcontrol.

Verify the grants

Switch the verb dropdown back to GET, paste this URL into the URL bar, and click Run query:

https://graph.microsoft.com/v1.0/sites/<site-id>/permissions

For the site ID from the earlier example, the URL looks like this:

https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,e3a1c643-6d61-4847-b4f2-b1449917e667,59c6df0e-f8b9-4069-a681-304929c3e132/permissions

Each site should show at least one entry with roles: ["fullcontrol"] and the application’s id set to your app’s client ID. The response looks like this:

{
  "value": [
    {
      "id": "aTowaS50fG1zLnNwLmV4dHw4MjNmNWEyMi1iZTIzLTQ1N2EtYmVkYS02YWRhZmM1MGQ3NThAOWY0ZGMxODItMDM1My00ZWUxLWI5ZmEtMjI1Y2UxMDQ0MDZi",
      "roles": ["fullcontrol"],
      "grantedToIdentitiesV2": [
        {
          "application": {
            "id": "823f5a22-be23-457a-beda-6adafc50d758",
            "displayName": "WikiTraccs Migration Tool"
          }
        }
      ],
      "grantedToIdentities": [
        {
          "application": {
            "id": "823f5a22-be23-457a-beda-6adafc50d758",
            "displayName": "WikiTraccs Migration Tool"
          }
        }
      ]
    }
  ]
}

Common pitfalls

• 403 Forbidden on the POST. Check in this order:
  1. On the app registration’s API permissions page, both Sites.Selected rows show the green “Granted for [Tenant]” checkmark. Missing admin consent here is the most common cause.
  2. The signed-in user has at least Read on the target site. This matters when the site was created by a different user - add the user to the site’s Visitors group and retry.
  3. Per Microsoft’s documentation, the signed-in user should also hold a SharePoint Administrator directory role or higher for this endpoint. Running the configuration as a Global Administrator satisfies this.
• 400 invalidRequest with “application not found”. Client ID typo, or the app is in a different tenant than the signed-in account.

Using the certificate in WikiTraccs

Once the app has Sites.Selected consent and holds FullControl on every target site, WikiTraccs needs the tenant ID, the app’s client ID, and the certificate reference.

Via WikiTraccs.GUI (the blue window)

In WikiTraccs.GUI:

1. Under SharePoint authentication type, select Cert.

2. Fill Tenant ID and Entra ID Application Client ID in the corresponding fields shown above.

3. In the Certificate field, enter either:

   • the path to the .pfx file (absolute or relative; relative paths resolve against the working directory), or
   • the SHA-1 thumbprint of a certificate in the Windows certificate store (CurrentUser\My or LocalMachine\My).

   A 40-character hex string is treated as a thumbprint, anything else as a file path.

4. Click Verify. WikiTraccs loads the certificate and shows the subject and expiration date on success.

   • For a PFX file path, WikiTraccs prompts for the password if the file is password-protected. The entered password is stored in plain-text in the configuration file, so subsequent runs do not prompt.
   • For a thumbprint, no password prompt appears. The private key is already accessible through the Windows certificate store under the Windows user account that runs WikiTraccs.

At migration start, WikiTraccs loads the certificate again to verify that everything is still in place. If the cert cannot be loaded, the migration aborts with a clear error.

Reference: Certificate authentication.

Via WikiTraccs.Console (unattended)

For scheduled or automated runs, configure WikiTraccs via appsettings.json instead of the GUI. Set AuthenticationType to apponlywithcertificate and fill the AuthenticationParameterSetAppOnlyAadCertificate block with either a path + password or a thumbprint.

See Run an Automated Confluence to SharePoint Migration for the full sample configuration.

Known limitation: link fixer and SharePoint Search

WikiTraccs’ link fixer uses SharePoint Search as one of its fallbacks, and SharePoint Search is not available under Sites.Selected with app-only authentication. This is a limitation set by Microsoft.

The impact in WikiTraccs: migrations complete without errors. Link fixing itself continues to work - the ContentSnapshots list resolves most links, including cross-site ones. What becomes unavailable is the Search-based fallback used when the snapshot lookup misses. A small number of links may therefore stay unresolved.

Two workarounds exist: use delegated authentication, or swap Sites.Selected for Sites.FullControl.All (application). The second option defeats the point of this setup - it grants tenant-wide SharePoint access - and is mentioned only for completeness.

Wrap-up

Sites.Selected with certificate authentication is one of the most locked-down WikiTraccs setups, on par with delegated authentication where the migration user only has access to the target sites. Once configured, operation is clean: there is no migration user to maintain, and no tenant-wide app access to defend in security reviews. Each target-site grant is explicit and auditable.

Setup is one-time: register the app, upload the certificate public key, admin-consent the Sites.Selected rows, and run one POST /sites/{id}/permissions per site. Those steps can be automated, for example via PnP PowerShell.

For full migration automation, see Run an Automated Confluence to SharePoint Migration. That said, Interactive authentication remains the easiest option and can be just as secure when configured properly.

Try WikiTraccs!

Give WikiTraccs a try and check out its transformation capabilities!

Quick start guide >>

Start today with WikiTraccs’ free Trial Version:

Download FREE WikiTraccs now

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.

• ←Previous
Next→