Granting Starmind read access to SharePoint Pages with your own Azure app (`Sites.Selected`)

ℹ️

This guide is only for customers who provide their own Azure AD application. If you instead use the Starmind-provided app, none of the steps below are required — your Starmind representative will tell you which model applies. Follow this guide only if you (the customer) own and manage the Azure app.

Starmind reads SharePoint Pages (SitePages) from sites you explicitly authorize, using Microsoft's Sites.Selected permission model. Starmind has no access to any site you don't authorize, and no tenant-wide read access (Sites.Read.All is never used). You stay in full control and can revoke access at any time.

In this model you create and own the Azure AD application in your tenant, and share a certificate's private key with Starmind so it can authenticate only as that app, only to the sites you grant.

⚠️

This setup is required to read SharePoint Pages under Sites.Selected. With the narrowly-scoped Sites.Selected permission model, SharePoint Pages content is only reachable through an app-only certificate authenticating as an app that has been granted per-site Read access (Steps 3 and 4). Without completing this setup — i.e. with Sites.Selected alone and no certificate-based app authentication — Starmind cannot read your SharePoint Pages. (The alternative, tenant-wide Sites.Read.All, is intentionally not used.)

There are five steps:

1. Create an app registration in your tenant.
2. Add the SharePoint Sites.Selected application permission and grant it.
3. Create a certificate, upload the public part to the app, and share the private key with Starmind.
4. Authorize each site Starmind should read (per-site, read-only).
5. Send Starmind the tenant ID, app ID, private key, and site URLs.

Before you start

Reference values used below:

Step 1 — Create an app registration

📌

Only create a new app if you don't already have one from a previous setup. If you registered a Starmind SharePoint app during an earlier onboarding (e.g. for another data source or a prior project), reuse that existing app — skip the registration below and just note its Application (client) ID and Directory (tenant) ID from its Overview, then continue at Step 2. Create a new registration only if no such app exists yet.

1. Entra admin center → Identity → Applications → App registrations → New registration.
2. Name it e.g. Starmind SharePoint Connector, leave defaults (single tenant is fine), and Register.
3. From the app's Overview, note the Application (client) ID and Directory (tenant) ID — you'll send these to Starmind.

Step 2 — Add and grant the SharePoint Sites.Selected permission

This declares that the app may access selected SharePoint sites. On its own it grants no access to any site (that happens in Step 4).

Add the permission (portal)

1. In your app → API permissions → Add a permission.
2. APIs my organization uses tab → search Office 365 SharePoint Online (confirm the resource id is 00000003-0000-0ff1-ce00-000000000000) → select it.
3. Application permissions → expand Sites → tick Sites.Selected → Add permissions.
4. Click Grant admin consent for <your tenant> and confirm. It should show Granted.

Or grant via Azure CLI (Option B — direct app-role assignment)

Use this if admin consent in the portal is restricted, or you prefer scripting. It assigns only the Sites.Selected role to your app's service principal:

APP_ID="<your-app-client-id>"
SPO_RESOURCE="00000003-0000-0ff1-ce00-000000000000"
SITES_SELECTED_ROLE="20d37865-089c-4dee-8c41-6967602d4ac8"

CLIENT_SP_ID=$(az ad sp show --id "$APP_ID" --query id -o tsv)        # your app's service principal object id
SPO_SP_ID=$(az ad sp show --id "$SPO_RESOURCE" --query id -o tsv)     # SharePoint Online service principal in your tenant

az rest --method POST \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$CLIENT_SP_ID/appRoleAssignments" \
  --headers "Content-Type=application/json" \
  --body "{\"principalId\":\"$CLIENT_SP_ID\",\"resourceId\":\"$SPO_SP_ID\",\"appRoleId\":\"$SITES_SELECTED_ROLE\"}"

If az ad sp show --id "$APP_ID" returns nothing, create the service principal first: az ad sp create --id "$APP_ID".

Step 3 — Create a certificate and share the private key with Starmind

SharePoint app-only access requires a certificate (client secrets are rejected). Create a certificate, upload its public part to the app, and send the private key to Starmind.

1. Generate the certificate (private key + public certificate):

   Bash

   openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
     -keyout starmind-sharepoint.key.pem \
     -out    starmind-sharepoint.cer.pem \
     -subj "/CN=Starmind SharePoint Connector"

   (Windows alternative: New-SelfSignedCertificate + export the .cer and a password-protected .pfx.)

2. Upload the PUBLIC certificate (starmind-sharepoint.cer.pem) to the app: in your app → Certificates & secrets → Certificates → Upload certificate. Or via CLI (keep any existing credentials with --append):

   Bash

   az ad app credential reset --id "<your-app-client-id>" \
     --cert @starmind-sharepoint.cer.pem --append

3. Share the PUBLIC certificate and PRIVATE key with Starmind.

🔒

The private key is a credential — transfer it securely.

Step 4 — Authorize specific sites (read-only)

Grant the app Read access to each site Starmind should index. Repeat per site. Choose one method.

Method A — PnP PowerShell (recommended)

Install-Module PnP.PowerShell -Scope CurrentUser   # once

Connect-PnPOnline -Url "https://<YOUR_TENANT>.sharepoint.com/sites/<SITE_NAME>" -Interactive
Grant-PnPEntraIDAppSitePermission `
  -AppId "<your-app-client-id>" `
  -DisplayName "Starmind SharePoint Connector" `
  -Permissions Read `
  -Site "https://<YOUR_TENANT>.sharepoint.com/sites/<SITE_NAME>"

Valid -Permissions values are Read, Write, Manage, FullControl. Read is sufficient — please don't grant more.

Method B — Microsoft Graph API

GET https://graph.microsoft.com/v1.0/sites/<YOUR_TENANT>.sharepoint.com:/sites/<SITE_NAME>

Copy the returned id, then:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [
    { "application": { "id": "<your-app-client-id>", "displayName": "Starmind SharePoint Connector" } }
  ]
}

A 201 Created confirms the grant. The caller needs Sites.FullControl.All (e.g. a SharePoint Administrator).

Step 5 — Send Starmind the connection details

Provide your Starmind representative with:

• Directory (tenant) ID
• Application (client) ID
• SharePoint URL (<YOUR_TENANT>.sharepoint.com)
• The public certificate and private key (via the secure channel from Step 3)
• The list of site URLs you authorized in Step 4

Verify access

Connect-PnPOnline -Url "https://<YOUR_TENANT>.sharepoint.com/sites/<SITE_NAME>" -Interactive
Get-PnPEntraIDAppSitePermission

You should see an entry for your app with the Read role.

Step 6 — Revoke access

You're in control at all times:

• Remove a single site: Revoke-PnPEntraIDAppSitePermission -PermissionId "<PERMISSION_ID>" (find the id with Get-PnPEntraIDAppSitePermission).
• Revoke the credential: delete the certificate under the app's Certificates & secrets.
• Remove everything: delete the app registration.

What this does and does not grant

• ✅ The ability to read SharePoint Pages (SitePages) on authorized sites — which under Sites.Selected is only possible with this certificate-based, per-site grant setup.
• ✅ Read-only access to only the sites you authorize in Step 4.
• ✅ Authentication via a certificate you issued, revocable at any time.
• ✅ Fully revocable, per site or entirely.
• ❌ No access to any site you haven't authorized.
• ❌ No tenant-wide read permission (no Sites.Read.All).

Troubleshooting

Need help? Contact your Starmind representative with the site URL(s) you'd like to authorize.