Guida alla distribuzione

AccessPoint utilizza un modello di distribuzione suddiviso in più componenti: una web part SPFx leggera in SharePoint, un'app Teams che ospita la stessa web part come scheda personale e un backend Azure che esegue le API e archivia tutti i dati. Ogni componente viene installato nel tenant Microsoft 365 e nell'abbonamento Azure dell'organizzazione stessa — nulla è ospitato dal fornitore e nessun dato del cliente lascia l'ambiente dell'organizzazione.

Panoramica

Per i cloud sovrani/governativi, per il blocco delle versioni o per le distribuzioni tramite script, tutti gli artefatti sono pubblicati anche all'indirizzo https://get.realizer.io/public/accesspoint/latest/.

L'ordine di installazione è importante. Installare la soluzione SharePoint prima che un utente apra la scheda personale di Teams. L'app Teams carica la web part SPFx da SharePoint all'interno di un iframe: senza di essa, gli utenti visualizzano un errore 404 di SharePoint all'interno di Teams.

Prerequisiti

• Un abbonamento AccessPoint attivo e una chiave API di licenza (ottieni AccessPoint)
• Un abbonamento Azure con diritti Contributor (o superiori) sul gruppo di risorse di destinazione
• Un catalogo app di SharePoint predisposto nel tenant, oltre a diritti di SharePoint Administrator
• Global Administrator o Application Administrator in Entra ID per la concessione delle autorizzazioni Graph e il consenso dell'amministratore
• Teams Administrator (o Global Admin) per pubblicare l'app Teams
• Per le distribuzioni tramite script o manuali: Azure CLI (con accesso tramite az login come utente, non come entità servizio) e il modulo PnP.PowerShell

Non esiste alcuna dipendenza da un particolare livello di licenza Microsoft 365, da Power Platform o da Dataverse: qualsiasi utente con accesso a SharePoint o Teams può utilizzare AccessPoint.

Passaggio 1: distribuire le risorse Azure

Questo passaggio predispone il backend: un App Service Linux (l'API), un database Azure SQL, Blob Storage e Application Insights con Log Analytics. Le risorse vengono denominate {type}-accesspoint-{tenantName} (ad esempio app-accesspoint-contoso) e sono protette per impostazione predefinita (TLS 1.3, autenticazione SQL solo Entra, FTPS e autenticazione di base disabilitati).

Opzione A: Portale Azure (consigliata). Distribuire il modello Bicep/ARM di AccessPoint con un clic dal Portale Azure (il pulsante Distribuisci in Azure). Il modulo di distribuzione richiede l'abbonamento e il gruppo di risorse, il nome del tenant (ad esempio contoso da contoso.sharepoint.com), la chiave API di licenza, lo SKU dell'App Service (B1 per la valutazione, S1 per la produzione standard, P1v3 come impostazione predefinita), un indirizzo e-mail di avviso facoltativo e un interruttore Concedi autorizzazioni Graph (attivo per impostazione predefinita; richiede il ruolo Application Administrator). Il pacchetto API viene distribuito automaticamente nell'App Service — dopo la distribuzione non esiste alcuna dipendenza in fase di esecuzione da servizi esterni.

Opzione B: Bicep + PowerShell. Per pipeline personalizzate o controlli delle modifiche rigorosi, eseguire lo script di distribuzione sul modello ARM pubblicato:

Invoke-WebRequest -Uri "https://get.realizer.io/public/accesspoint/latest/Deploy-AccessPoint.ps1" -OutFile "Deploy-AccessPoint.ps1"

# End-to-end: infrastructure, configuration, and both apps
.\Deploy-AccessPoint.ps1 `
    -SharePointSiteUrl "https://contoso.sharepoint.com/sites/accesspoint" `
    -TemplateUri "https://get.realizer.io/public/accesspoint/latest/main.json" `
    -DeploySharePointApp -DeployTeamsApp

Lo script esegue fino a sette passaggi: infrastruttura, autenticazione SQL solo Entra, concessione delle autorizzazioni Graph, un ciclo di arresto/avvio dell'App Service, l'entità di archiviazione di SharePoint (URL dell'API), le approvazioni delle autorizzazioni API di SPFx e le installazioni facoltative delle app. Ogni passaggio può essere ignorato singolarmente (-SkipInfrastructure, -SkipGraphPermissions, -SkipSharePoint). Bloccare una versione con -ArtifactBaseUrl "https://get.realizer.io/public/accesspoint/1.0.0" per distribuzioni riproducibili e con integrità verificata (lo script controlla lo SHA-256 pubblicato e si interrompe in caso di mancata corrispondenza).

Per eseguire autonomamente solo le parti relative all'infrastruttura:

$TenantName    = "contoso"
$ResourceGroup = "rg-accesspoint-$TenantName"

az group create --name $ResourceGroup --location "canadacentral"

$deployment = az deployment group create `
    --resource-group $ResourceGroup `
    --template-uri "https://get.realizer.io/public/accesspoint/latest/main.json" `
    --parameters tenantName=$TenantName appServiceSku=P1v3 `
    --output json | ConvertFrom-Json

$appName     = $deployment.properties.outputs.appServiceName.value
$apiUrl      = $deployment.properties.outputs.appServiceUrl.value
$principalId = $deployment.properties.outputs.appServicePrincipalId.value

# Disable SQL password auth — Entra ID (managed identity) only
az sql server ad-only-auth enable --resource-group $ResourceGroup `
    --server-name $deployment.properties.outputs.sqlServerName.value

Concessione delle autorizzazioni Graph. L'identità gestita dell'App Service richiede cinque autorizzazioni applicative di Microsoft Graph: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All e AppCatalog.Read.All. Il modello le concede automaticamente (grantGraphPermissions=true, valore predefinito) quando l'utente che esegue la distribuzione dispone del ruolo Application Administrator o dell'autorizzazione AppRoleAssignment.ReadWrite.All. In caso contrario, concederle successivamente:

$graphSpId = az ad sp show --id "00000003-0000-0000-c000-000000000000" --query id -o tsv

$permissions = @(
    @{ Name = "Mail.Send";                            Id = "b633e1c5-b582-4048-a93e-9f11b44c7e96" }
    @{ Name = "User.ReadBasic.All";                   Id = "97235f07-e226-4f63-ace3-39588e11d3a1" }
    @{ Name = "TeamsAppInstallation.ReadForUser.All"; Id = "9ce09611-f4f7-4abd-a629-a05450422a97" }
    @{ Name = "Application.Read.All";                 Id = "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30" }
    @{ Name = "AppCatalog.Read.All";                  Id = "e12dae10-5a57-4817-b79d-dfbec5348930" }
)

foreach ($perm in $permissions) {
    $bodyFile = [System.IO.Path]::GetTempFileName()
    @{ principalId = $principalId; resourceId = $graphSpId; appRoleId = $perm.Id } |
        ConvertTo-Json | Set-Content -Path $bodyFile -Encoding utf8
    az rest --method POST `
        --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$principalId/appRoleAssignments" `
        --body "@$bodyFile" --headers "Content-Type=application/json" --output none
    Remove-Item $bodyFile
}

# Full stop/start (NOT restart) clears the managed identity token cache
az webapp stop  --name $appName --resource-group $ResourceGroup
Start-Sleep -Seconds 10
az webapp start --name $appName --resource-group $ResourceGroup

Verifica: accedere a https://<api-url>/api/health e confermare una risposta corretta.

Passaggio 2: installare le app di AccessPoint

Installare prima la soluzione SharePoint, quindi l'app Teams.

Soluzione SharePoint. Dalla scheda di AppSource, fare clic su Get it now e approvarla nel catalogo app di SharePoint, distribuendola a livello di tenant. In alternativa, caricarla manualmente (Centro di amministrazione di SharePoint > Altre funzionalità > App > Carica, selezionando "Rendi disponibile questa soluzione per tutti i siti") oppure lasciare che sia lo script a farlo.

App Teams. Dalla scheda di AppSource, fare clic su Get it now e approvarla nel Centro di amministrazione Teams, oppure installare entrambe le app tramite lo script (l'utente che accede deve disporre dei ruoli SharePoint admin e Teams admin o Global admin):

.\Deploy-AccessPoint.ps1 `
    -SharePointSiteUrl "https://contoso.sharepoint.com/sites/accesspoint" `
    -SkipInfrastructure -SkipGraphPermissions `
    -DeploySharePointApp -DeployTeamsApp

Non utilizzare la funzione "Sync to Teams" di SharePoint. Sovrascrive silenziosamente il valore webApplicationInfo.id del manifesto, il che interrompe le notifiche del feed attività di Teams. Caricare l'app Teams direttamente nel Centro di amministrazione Teams.

Verifica: la soluzione compare nel catalogo app senza errori e AccessPoint risulta Allowed in Teams Admin Center > Manage apps.

Passaggio 3: approvare le autorizzazioni API

Il pacchetto SPFx richiede autorizzazioni delegate che un amministratore di SharePoint deve approvare. Nel Centro di amministrazione di SharePoint, andare su Avanzate > Accesso API e approvare ogni richiesta di AccessPoint in sospeso (access_as_user sull'API di AccessPoint, oltre ad ambiti Graph come User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read).

In alternativa, approvarle tramite PnP PowerShell:

Connect-PnPOnline -Url "https://contoso-admin.sharepoint.com" -Interactive

$spfxPermissions = @(
    @{ Resource = "ed19c96c-a7c5-4dca-8b47-0899c406329f"; Scope = "access_as_user" }
    @{ Resource = "Microsoft Graph"; Scope = "User.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Sites.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Files.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Mail.Read" }
)
foreach ($perm in $spfxPermissions) {
    Grant-PnPTenantServicePrincipalPermission -Scope $perm.Scope -Resource $perm.Resource
}

Infine, un utente con ruolo Global Administrator concede il consenso dell'amministratore per l'app multi-tenant del fornitore aprendo in un browser l'indirizzo https://login.microsoftonline.com/common/adminconsent?client_id=ed19c96c-a7c5-4dca-8b47-0899c406329f.

Verifica: la pagina di accesso API non mostra più richieste di AccessPoint in sospeso.

Passaggio 4: utilizzare AccessPoint in SharePoint o Teams

SharePoint: modificare o creare una pagina, fare clic su +, cercare AccessPoint, aggiungere la web part e pubblicare.

Teams: gli utenti trovano AccessPoint in Apps > Built for your org (l'indicizzazione della ricerca può richiedere da 15 minuti a diverse ore dopo la prima installazione). Facoltativamente, è possibile bloccarla per tutti tramite Teams Admin Center > App setup policies, aggiungendo AccessPoint sia a Installed apps sia a Pinned apps.

Passaggio 5: configurare l'URL dell'API

Aprire la web part e andare su Impostazioni > Configurazione. Immettere l'URL API (l'URL dell'App Service ottenuto al Passaggio 1, ad esempio https://app-accesspoint-contoso.azurewebsites.net) e l'ID client della registrazione dell'app Entra ID dell'API, quindi fare clic su Salva. Il pannello convalida il formato HTTPS e il formato GUID prima di salvare.

Lo script di distribuzione imposta automaticamente l'entità di archiviazione di SharePoint sottostante. Per impostarla manualmente:

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive
$appCatalogUrl = Get-PnPTenantAppCatalogUrl
Connect-PnPOnline -Url $appCatalogUrl -Interactive   # storage entities live on the App Catalog site

Set-PnPStorageEntity -Key "AccessPoint_ApiUrl" -Value $apiUrl -Description "AccessPoint API base URL"
Get-PnPStorageEntity -Key "AccessPoint_ApiUrl"       # verify

Verifica: ricaricare la web part — viene visualizzata la dashboard invece della richiesta di configurazione.

Passaggio 6: importare un pacchetto di configurazione

Andare su Impostazioni > Pacchetti di configurazione, scegliere il pacchetto per la propria giurisdizione (Canada ATIA, US FOIA, EU GDPR e altri) e fare clic su Importa. Il pacchetto crea tipi di richiesta, motivi di proroga, campi a scelta, modelli di notifica e traduzioni. Rivedere e personalizzare gli elementi importati in un secondo momento.

Passaggio 7: assegnare i ruoli utente

Il primo utente che apre AccessPoint ottiene automaticamente i ruoli Administrator e SAO. Andare su Impostazioni > Gestisci utenti, fare clic su Aggiungi utente, cercare nella directory e assegnare i ruoli: almeno un Administrator e un SAO, oltre ai ruoli Custodian, Contributor, Reviewer e Reader secondo necessità.

A questo punto AccessPoint è pronto per l'uso.

Distribuzione multi-tenant

Utilizzare questo modello quando il backend Azure risiede in un tenant Entra ID diverso da quello Microsoft 365 — ad esempio un team di servizi condivisi che serve più unità aziendali, un MSP che offre hosting per i clienti, oppure tenant Azure e M365 separati per motivi di governance. Un'unica distribuzione può servire più tenant M365: l'API isola i dati in base all'ID tenant presente nel token di ciascun utente, con filtri delle query del database limitati al tenant e percorsi blob con prefisso di tenant. Ogni tenant M365 richiede comunque un proprio abbonamento, una propria distribuzione SPFx e relative approvazioni delle autorizzazioni API, oltre a proprie credenziali Graph e una propria casella di posta per le notifiche.

Registrazione dell'app Graph. Un'identità gestita funziona solo nel proprio tenant di origine; è quindi necessario creare una registrazione dell'app a tenant singolo nel tenant M365 (ad esempio AccessPoint Graph Connector), concederle le stesse cinque autorizzazioni applicative Graph elencate al Passaggio 1 con il consenso dell'amministratore, quindi creare un segreto client e collegarlo all'App Service tramite Key Vault:

# In the M365 tenant: create the client secret
$secret = az ad app credential reset --id $appId --display-name "AccessPoint" --years 2 --query password -o tsv

# In the Azure subscription: store the secret and reference it from the App Service
az keyvault secret set --vault-name $vaultName --name "GraphClientSecret" --value $secret

az webapp config appsettings set --resource-group $ResourceGroup --name $appName --settings `
    "Graph__TenantId=$m365TenantId" `
    "Graph__ClientId=$appId" `
    "Graph__ClientSecret=@Microsoft.KeyVault(SecretUri=https://$vaultName.vault.azure.net/secrets/GraphClientSecret)"

az webapp restart --resource-group $ResourceGroup --name $appName

Non archiviare mai il segreto direttamente nelle impostazioni dell'App Service; l'identità gestita dell'App Service richiede il ruolo Key Vault Secrets User sul Key Vault. Quando tutte e tre le impostazioni Graph__* sono presenti, l'API utilizza la registrazione dell'app; quando sono assenti, ricorre invece all'identità gestita per le distribuzioni nello stesso tenant.

Cassetta postale condivisa e criteri di accesso alle applicazioni. Creare una cassetta postale condivisa senza licenza nel tenant M365 per le notifiche via e-mail e limitare Mail.Send in modo che l'app possa inviare messaggi solo da quella cassetta postale:

Connect-ExchangeOnline -Organization "contoso.onmicrosoft.com"

New-Mailbox -Name "AccessPoint Notifications" -Alias "accesspoint-noreply" -Shared

New-DistributionGroup -Name "AccessPoint Mail Senders" -Type Security -ManagedBy "admin@contoso.com"
Add-DistributionGroupMember -Identity "AccessPoint Mail Senders" -Member "accesspoint-noreply@contoso.com"

New-ApplicationAccessPolicy -AppId $appId -PolicyScopeGroupId "AccessPoint Mail Senders" `
    -AccessRight RestrictAccess -Description "AccessPoint may send only from the shared mailbox"

# Verify (propagation can take up to 30 minutes)
Test-ApplicationAccessPolicy -AppId $appId -Identity "accesspoint-noreply@contoso.com"   # expect: Granted
Test-ApplicationAccessPolicy -AppId $appId -Identity "someother@contoso.com"             # expect: Denied

Ciascun tenant M365 ripete quindi i Passaggi 2–5 (app, approvazioni, URL dell'API — lo stesso URL API serve tutti i tenant). Le notifiche del feed attività di Teams richiedono inoltre il consenso dell'amministratore per l'applicazione aziendale Realizer e per l'app Teams installata per gli utenti; per i dettagli, vedere Configurazione iniziale.

Rollback e operazioni

I meccanismi standard di Azure coprono il rollback: ridistribuire un pacchetto API precedente dalla cronologia del Centro distribuzione dell'App Service, ripristinare Azure SQL con il ripristino temporizzato (fino a 35 giorni) e ricaricare nel catalogo app una versione precedente del file .sppkg. Le importazioni dei pacchetti di configurazione sono additive e vengono annullate tramite ripristino del database. Per il runbook operativo completo — procedure di rollback dettagliate, monitoraggio e attività di manutenzione — contattare il nostro team di supporto.