Sites.Selected setup
The certificate authentication guide grants the app registration Sites.FullControl.All, which reaches every site in the tenant. This page sets up the same certificate sign-in with Sites.Selected instead, so bdoctor can only reach the one site you publish to. Every step uses the CLI for Microsoft 365 (m365) from PowerShell 7.
Sites.Selected grants nothing on its own. It lets an administrator grant the app a permission on individual sites, and the app can reach only those. The setup has five parts:
- Create a certificate.
- Create the app registration with the
Sites.Selectedapplication permission on Microsoft Graph and on SharePoint. - Create a site collection app catalog on the site.
- Grant the app
fullcontrolon the site. - Sign in as the app and check what it can reach.
Before you start
Section titled “Before you start”An administrator runs these steps once per site, signed in to m365 as themselves. Install the CLI and sign in:
npm install --global @pnp/cli-microsoft365m365 setup # first run only: registers the Entra app the CLI signs you in withm365 login| Step | Role needed |
|---|---|
| Create the app registration | Application Administrator or Cloud Application Administrator |
Grant admin consent to the Sites.Selected application permissions |
Privileged Role Administrator or Global Administrator |
| Create the site collection app catalog | SharePoint Administrator or Global Administrator |
| Grant the app permission on the site | SharePoint Administrator or Global Administrator |
The app m365 signs you in with needs the matching delegated permissions: Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All and Sites.FullControl.All on Microsoft Graph, and AllSites.FullControl on SharePoint. m365 setup offers to add them.
Set the values the steps share. The app name is yours to pick; naming it after the site keeps one registration per site easy to find.
$TenantId = '00000000-0000-0000-0000-000000000000'$SiteUrl = 'https://<tenant>.sharepoint.com/sites/<site>'$AppName = 'bdoctor-<site>'$CertPassword = Read-Host -Prompt 'Certificate password' -AsSecureStringCreate the certificate
Section titled “Create the certificate”You need the certificate twice: its public key (a .cer file) goes on the app registration, and the private key (a password-protected .pfx file) is what bdoctor signs in with. Create it with either option below.
With PowerShell on Windows
Section titled “With PowerShell on Windows”$CertParams = @{ Subject = 'CN={0}' -f $AppName CertStoreLocation = 'Cert:\CurrentUser\My' KeyExportPolicy = 'Exportable' KeySpec = 'Signature' KeyAlgorithm = 'RSA' KeyLength = 2048 HashAlgorithm = 'SHA256' NotAfter = (Get-Date).AddYears(1)}$Cert = New-SelfSignedCertificate @CertParams
$null = Export-Certificate -Cert $Cert -FilePath .\bdoctor.cer$null = Export-PfxCertificate -Cert $Cert -FilePath .\bdoctor.pfx -Password $CertPassword
# The .pfx now holds the private key, so the copy in the certificate store can goRemove-Item -Path ('Cert:\CurrentUser\My\{0}' -f $Cert.Thumbprint)With OpenSSL on any platform
Section titled “With OpenSSL on any platform”openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes -keyout bdoctor.key -out bdoctor.pem -subj "/CN=bdoctor"openssl x509 -in bdoctor.pem -outform der -out bdoctor.ceropenssl pkcs12 -export -out bdoctor.pfx -inkey bdoctor.key -in bdoctor.pemopenssl pkcs12 asks for the password of the .pfx; use the one you entered for Read-Host above. Delete bdoctor.key once the .pfx exists, as it is the unprotected private key.
Keep bdoctor.pfx and its password out of source control. In a pipeline, store its base64 encoded contents as a secret:
[Convert]::ToBase64String([System.IO.File]::ReadAllBytes('.\bdoctor.pfx')) | Set-ClipboardCreate the app registration
Section titled “Create the app registration”Create the app registration with its certificate and both Sites.Selected application permissions, and grant admin consent in the same call:
$ApisApplication = @( 'https://graph.microsoft.com/Sites.Selected' 'https://microsoft.sharepoint-df.com/Sites.Selected') -join ','
$App = m365 entra app add --name $AppName --apisApplication $ApisApplication --certificateFile .\bdoctor.cer --certificateDisplayName $AppName --grantAdminConsent --output json | ConvertFrom-Json
$AppId = $App.appId$AppIdhttps://microsoft.sharepoint-df.com is the identifier the CLI for Microsoft 365 uses for the SharePoint resource (Office 365 SharePoint Online in the portal). The app needs Sites.Selected on both resources:
- SharePoint:
bdoctorsigns in with a SharePoint token, and nearly everything it does (pages, files, navigation, features, the app catalog) is a SharePoint REST call. - Microsoft Graph: some CLI for Microsoft 365 commands reach the site through Graph, and a site permission granted in the next steps only applies to Graph calls when the app holds Graph’s
Sites.Selectedtoo.
--grantAdminConsent also creates the enterprise application (service principal), which the site permission is granted to. Check the result:
m365 entra app permission list --appId $AppIdMoving an existing app registration to Sites.Selected
Section titled “Moving an existing app registration to Sites.Selected”An app set up with the certificate authentication guide can be moved over instead of replaced. Add the new permissions first, then remove the tenant-wide one:
$AppId = '00000000-0000-0000-0000-000000000000' # the existing app registration
m365 entra app permission add --appId $AppId --applicationPermissions 'https://graph.microsoft.com/Sites.Selected https://microsoft.sharepoint-df.com/Sites.Selected' --grantAdminConsentm365 entra app permission remove --appId $AppId --applicationPermissions 'https://microsoft.sharepoint-df.com/Sites.FullControl.All' --revokeAdminConsent --forceentra app permission add and remove take a space-separated list, where entra app add --apisApplication takes a comma-separated one. To add a new certificate to an existing app, use m365 entra app set --appId $AppId --certificateFile .\bdoctor.cer; it keeps the certificates already there, which is also how you rotate one before it expires.
Create the site collection app catalog
Section titled “Create the site collection app catalog”bdoctor publishes into the Better Doctor Markdown web part, which has to be deployed to the site first. With Sites.Selected the app cannot reach the tenant app catalog, so the site gets an app catalog of its own:
m365 spo site appcatalog add --siteUrl $SiteUrlThe command returns nothing on success. SharePoint can take a few minutes before the catalog accepts apps. Check that it is listed:
m365 spo site appcatalog list --output textGrant the app permission on the site
Section titled “Grant the app permission on the site”Grant the app fullcontrol on the site. This is the step that turns Sites.Selected into access, and it applies to both the SharePoint and the Graph permission:
$SitePermission = 'fullcontrol'
m365 spo site apppermission add --siteUrl $SiteUrl --appId $AppId --appDisplayName $AppName --permission $SitePermissionPassing both --appId and --appDisplayName saves the CLI a lookup. fullcontrol is needed rather than write: besides pages and files, bdoctor and the web part deployment add, deploy and install the solution in the site’s app catalog, turn on the multilingual site feature, and change the site navigation and chrome. write covers list items and files only.
Check the grant:
m365 spo site apppermission list --siteUrl $SiteUrlRepeat this step (and the app catalog) for every other site the same app publishes to.
Check the sign-in as the app
Section titled “Check the sign-in as the app”Sign out as the administrator and sign in as the app, the way bdoctor will:
m365 logoutm365 login --authType certificate --appId $AppId --tenant $TenantId --certificateFile .\bdoctor.pfx --password (ConvertFrom-SecureString -SecureString $CertPassword -AsPlainText)
# Store the root site URL, so the CLI does not look it up through Graph's root site, which Sites.Selected does not grantm365 spo set --url ([uri]$SiteUrl).GetLeftPart('Authority')
m365 spo web get --url $SiteUrl --output textspo web get returns the site. The same command against any other site, for example the root site, answers with an access denied error, which is what Sites.Selected is for.
Deploy the web part and publish
Section titled “Deploy the web part and publish”The app registration now has everything bdoctor needs on the site. Next:
-
Deploy the Better Doctor Markdown solution to the site collection app catalog, as described in web part deployment.
scripts/deploy-webpart.jsin the repository does it with this app registration: setSITE_URL,APP_ID,TENANT_ID,CERTIFICATE_PATH(orCERTIFICATE, the base64 contents) andCERT_PASSWORD. -
Publish with the same values:
Terminal window bdoctor publish --appId $AppId --tenant $TenantId --url $SiteUrl --certificate ./bdoctor.pfx --password '<certificate password>'
The appId, tenant and url values can live in bdoctor.json; the certificate and its password cannot.
What Sites.Selected does not cover
Section titled “What Sites.Selected does not cover”Nearly everything bdoctor does is on the site itself, including the siteDesign.logo and siteDesign.chrome settings. A few things are not:
- A custom tenant theme (
siteDesign.themewith--applyTheme): it is applied through the tenant admin site, which a site-level grant does not reach. A built-in SharePoint theme is applied on the site and works without it. - The tenant app catalog: deploying the web part tenant-wide needs an app with access to the tenant app catalog.
- Other sites: the app reaches only the sites it was granted. Publishing to another site needs its own grant and app catalog.
For the first two, set up a separate admin app registration with Sites.FullControl.All. The regular app keeps its site grant; bdoctor signs in as the admin app only for the calls that need it, and switches back straight after. Without one, bdoctor skips a custom theme it cannot apply and says so in a warning.
bdoctor also falls back to the admin app for the logo when the site refuses to set it with the regular app. That is not expected with a fullcontrol grant, but it keeps the logo from being skipped.
Create the admin app registration
Section titled “Create the admin app registration”Give the admin app a certificate of its own, created the same way as the first one with another name, so the full-control key can be kept apart from the one CI publishes with:
$AdminAppName = 'bdoctor-admin'
$AdminApp = m365 entra app add --name $AdminAppName --apisApplication 'https://microsoft.sharepoint-df.com/Sites.FullControl.All' --certificateFile .\bdoctor-admin.cer --certificateDisplayName $AdminAppName --grantAdminConsent --output json | ConvertFrom-Json
$AdminAppId = $AdminApp.appId$AdminAppIdIt needs no site permission and no app catalog of its own: Sites.FullControl.All already reaches the tenant admin site and the tenant app catalog.
Apply a custom theme with the admin app
Section titled “Apply a custom theme with the admin app”The admin app applies the theme, but does not create it: register it in the tenant first, and set its name in siteDesign.theme.
Pass the admin app next to the regular one. The admin options can be combined with a full publish, but a separate run keeps the full-control certificate out of the publishing pipeline altogether: run the one below by hand, or in a job of its own, whenever the theme changes.
bdoctor publish --skipPages --skipNavigation --applyTheme --appId $AppId --tenant $TenantId --url $SiteUrl --certificate ./bdoctor.pfx --password '<certificate password>' --adminAppId $AdminAppId --adminCertificate ./bdoctor-admin.pfx --adminPassword '<admin certificate password>'--skipPages and --skipNavigation leave the pages and the navigation alone, so the run only changes the look of the site. The CLI options page describes the admin options.
Deploy the web part tenant-wide
Section titled “Deploy the web part tenant-wide”scripts/deploy-webpart.js deploys to the tenant app catalog with APP_CATALOG_SCOPE=tenant, signed in as the admin app. Set ADMIN_APP_ID, ADMIN_CERTIFICATE_PATH (or ADMIN_CERTIFICATE), ADMIN_CERT_PASSWORD, TENANT_ID and SITE_URL. The solution is deployed to every site, so the site needs no app catalog of its own. See web part deployment.