Bereitstellungshandbuch

AccessPoint verwendet ein geteiltes Bereitstellungsmodell: ein schlankes SPFx Web Part in SharePoint, eine Teams-App, die dasselbe Web Part als persönliche Registerkarte hostet, und ein Azure-Backend, das die API ausführt und alle Daten speichert. Jede Komponente landet in Ihrem eigenen Microsoft 365-Mandanten und Azure-Abonnement — nichts wird vom Herausgeber gehostet, und keine Kundendaten verlassen Ihre Umgebung.

Überblick

Für souveräne/Regierungs-Clouds, Versionsfixierung oder skriptbasierte Bereitstellungen werden alle Artefakte zusätzlich unter https://get.realizer.io/public/accesspoint/latest/ veröffentlicht.

Die Installationsreihenfolge ist wichtig. Installieren Sie die SharePoint-Lösung, bevor ein Benutzer die persönliche Teams-Registerkarte öffnet. Die Teams-App lädt das SPFx Web Part aus SharePoint in einem iframe — ohne dieses sehen Benutzer innerhalb von Teams einen SharePoint-404-Fehler.

Voraussetzungen

• Ein aktives AccessPoint-Abonnement und einen Lizenz-API-Schlüssel (AccessPoint beziehen)
• Ein Azure-Abonnement mit Contributor-Rechten (oder höher) für die Ziel-Ressourcengruppe
• Ein in Ihrem Mandanten bereitgestellter SharePoint-App-Katalog sowie SharePoint Administrator-Rechte
• Global Administrator oder Application Administrator in Entra ID für die Erteilung von Graph-Berechtigungen und die Administratoreinwilligung
• Teams Administrator (oder Global Admin) zum Veröffentlichen der Teams-App
• Für skriptbasierte oder manuelle Bereitstellungen: Azure CLI (angemeldet mit az login als Benutzer, nicht als Dienstprinzipal) und das PnP.PowerShell-Modul

Es besteht keine Abhängigkeit von einer bestimmten Microsoft 365-Lizenzstufe, von Power Platform oder Dataverse — jeder Benutzer mit SharePoint- oder Teams-Zugriff kann AccessPoint verwenden.

Schritt 1: Azure-Ressourcen bereitstellen

Dieser Schritt stellt das Backend bereit: einen App Service unter Linux (die API), eine Azure SQL-Datenbank, Blob Storage und Application Insights mit Log Analytics. Die Ressourcen werden nach dem Schema {type}-accesspoint-{tenantName} benannt (zum Beispiel app-accesspoint-contoso) und sind standardmäßig gehärtet (TLS 1.3, reine Entra-SQL-Authentifizierung, FTPS und Basisauthentifizierung deaktiviert).

Option A: Azure-Portal (empfohlen). Stellen Sie die AccessPoint-Bicep/ARM-Vorlage mit einem Klick aus dem Azure-Portal bereit (die Schaltfläche In Azure bereitstellen). Das Bereitstellungsformular erfasst Ihr Abonnement und Ihre Ressourcengruppe, den Mandantennamen (z. B. contoso aus contoso.sharepoint.com), den Lizenz-API-Schlüssel, die App Service-SKU (B1 für die Evaluierung, S1 für die Standardproduktion, P1v3 als Standard), eine optionale E-Mail-Adresse für Warnungen und einen Umschalter Graph-Berechtigungen erteilen (standardmäßig aktiviert; erfordert Application Administrator). Das API-Paket wird automatisch im App Service bereitgestellt — nach der Bereitstellung besteht keine Laufzeitabhängigkeit von externen Diensten.

Option B: Bicep + PowerShell. Führen Sie für benutzerdefinierte Pipelines oder eine strenge Änderungskontrolle das Bereitstellungsskript mit der veröffentlichten ARM-Vorlage aus:

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

Das Skript führt bis zu sieben Schritte aus — Infrastruktur, reine Entra-SQL-Authentifizierung, Erteilung von Graph-Berechtigungen, einen Stopp-/Startzyklus des App Service, die SharePoint-Speicherentität (API-URL), Genehmigungen der SPFx-API-Berechtigungen und optionale App-Installationen. Jeder Schritt ist einzeln überspringbar (-SkipInfrastructure, -SkipGraphPermissions, -SkipSharePoint). Fixieren Sie eine Version mit -ArtifactBaseUrl "https://get.realizer.io/public/accesspoint/1.0.0" für reproduzierbare, integritätsgeprüfte Bereitstellungen (das Skript prüft den veröffentlichten SHA-256-Hash und bricht bei Abweichung ab).

Um die Infrastrukturkomponenten stattdessen selbst auszuführen:

$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

Erteilung von Graph-Berechtigungen. Die verwaltete Identität des App Service benötigt fünf Microsoft Graph-Anwendungsberechtigungen: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All und AppCatalog.Read.All. Die Vorlage erteilt sie automatisch (grantGraphPermissions=true, der Standard), wenn der bereitstellende Benutzer über Application Administrator oder AppRoleAssignment.ReadWrite.All verfügt. Andernfalls erteilen Sie sie im Nachhinein:

$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

Überprüfung: Rufen Sie https://<api-url>/api/health auf und bestätigen Sie eine fehlerfreie Antwort.

Schritt 2: Die AccessPoint-Apps installieren

Installieren Sie zuerst die SharePoint-Lösung, dann die Teams-App.

SharePoint-Lösung. Klicken Sie im AppSource-Eintrag auf Get it now und genehmigen Sie sie mandantenweit in Ihrem SharePoint-App-Katalog. Alternativ können Sie sie manuell hochladen (SharePoint Admin Center > Weitere Features > Apps > Hochladen, das Kontrollkästchen „Diese Lösung für alle Websites verfügbar machen" aktivieren) oder das Skript dies erledigen lassen.

Teams-App. Klicken Sie im AppSource-Eintrag auf Get it now und genehmigen Sie sie im Teams Admin Center, oder installieren Sie beide Apps über das Skript (der angemeldete Benutzer benötigt SharePoint-Administrator- sowie Teams-Administrator- oder Global-Admin-Rechte):

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

Verwenden Sie NICHT die SharePoint-Funktion „Sync to Teams". Sie überschreibt stillschweigend die webApplicationInfo.id des Manifests, wodurch die Benachrichtigungen im Teams-Aktivitätsfeed nicht mehr funktionieren. Laden Sie die Teams-App direkt in das Teams Admin Center hoch.

Überprüfung: Die Lösung erscheint fehlerfrei im App-Katalog, und AccessPoint wird unter Teams Admin Center > Apps verwalten als Zulässig angezeigt.

Schritt 3: API-Berechtigungen genehmigen

Das SPFx-Paket fordert delegierte Berechtigungen an, die ein SharePoint-Administrator genehmigen muss. Wechseln Sie im SharePoint Admin Center zu Erweitert > API-Zugriff und genehmigen Sie jede ausstehende AccessPoint-Anforderung (access_as_user für die AccessPoint-API sowie Graph-Bereiche wie User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read).

Oder genehmigen Sie über 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
}

Abschließend erteilt ein Global Administrator die Administratoreinwilligung für die Mehrmandanten-App des Herausgebers, indem er https://login.microsoftonline.com/common/adminconsent?client_id=ed19c96c-a7c5-4dca-8b47-0899c406329f in einem Browser öffnet.

Überprüfung: Die Seite für den API-Zugriff zeigt keine ausstehenden AccessPoint-Anforderungen mehr an.

Schritt 4: AccessPoint in SharePoint oder Teams verwenden

SharePoint: Bearbeiten oder erstellen Sie eine Seite, klicken Sie auf +, suchen Sie nach AccessPoint, fügen Sie das Web Part hinzu und veröffentlichen Sie die Seite.

Teams: Benutzer finden AccessPoint unter Apps > Built for your org (die Suchindizierung kann nach der Erstinstallation 15 Minuten bis mehrere Stunden dauern). Optional können Sie es über Teams Admin Center > App-Setuprichtlinien für alle anheften, indem Sie AccessPoint zu Installierte Apps und Angeheftete Apps hinzufügen.

Schritt 5: Die API-URL konfigurieren

Öffnen Sie das Web Part und wechseln Sie zu Einstellungen > Einrichtung. Geben Sie die API-URL (die App Service-URL aus Schritt 1, z. B. https://app-accesspoint-contoso.azurewebsites.net) und die Client-ID der Entra ID-App-Registrierung der API ein und klicken Sie dann auf Speichern. Der Bereich validiert HTTPS und das GUID-Format vor dem Speichern.

Das Bereitstellungsskript legt die zugrunde liegende SharePoint-Speicherentität für Sie fest. Um sie manuell festzulegen:

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

Überprüfung: Laden Sie das Web Part neu — das Dashboard wird anstelle der Einrichtungsaufforderung geladen.

Schritt 6: Ein Konfigurationspaket importieren

Wechseln Sie zu Einstellungen > Konfigurationspakete, wählen Sie das Paket für Ihre Rechtsordnung (Canada ATIA, US FOIA, EU GDPR und weitere) und klicken Sie auf Importieren. Das Paket erstellt Antragstypen, Verlängerungsgründe, Auswahlfelder, Benachrichtigungsvorlagen und Übersetzungen. Überprüfen und passen Sie die importierten Elemente anschließend an.

Schritt 7: Benutzerrollen zuweisen

Dem ersten Benutzer, der AccessPoint öffnet, werden automatisch die Rollen Administrator und SAO zugewiesen. Wechseln Sie zu Einstellungen > Benutzer verwalten, klicken Sie auf Benutzer hinzufügen, durchsuchen Sie Ihr Verzeichnis und weisen Sie Rollen zu: mindestens einen Administrator und einen SAO sowie bei Bedarf die Rollen Custodian, Contributor, Reviewer und Reader.

AccessPoint ist jetzt einsatzbereit.

Mehrmandanten-Bereitstellung

Verwenden Sie dieses Muster, wenn das Azure-Backend in einem anderen Entra ID-Mandanten liegt als Ihr Microsoft 365-Mandant — etwa bei einem Shared-Services-Team, das mehrere Geschäftsbereiche bedient, einem MSP, der für Kunden hostet, oder getrennten Azure-/M365-Mandanten aus Governance-Gründen. Eine einzelne Bereitstellung kann mehrere M365-Mandanten bedienen: Die API isoliert Daten anhand der Mandanten-ID im Token jedes Benutzers, mit mandantenbezogenen Datenbankabfragefiltern und mandantenpräfixierten Blob-Pfaden. Jeder M365-Mandant benötigt dennoch eine eigene Lizenz, eine eigene SPFx-Bereitstellung und API-Berechtigungsgenehmigungen sowie eigene Graph-Anmeldeinformationen und ein eigenes Benachrichtigungspostfach.

Graph-App-Registrierung. Eine verwaltete Identität funktioniert nur in ihrem Heimatmandanten. Erstellen Sie daher eine App-Registrierung für einen einzelnen Mandanten (Single-Tenant) im M365-Mandanten (z. B. AccessPoint Graph Connector), erteilen Sie ihr mit Administratoreinwilligung dieselben fünf Graph-Anwendungsberechtigungen aus Schritt 1, erstellen Sie dann ein Clientgeheimnis und verbinden Sie es über Key Vault mit dem App Service:

# 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

Speichern Sie das Geheimnis niemals direkt in den App Service-Einstellungen; die verwaltete Identität des App Service benötigt die Rolle Key Vault Secrets User für den Tresor. Wenn alle drei Graph__*-Einstellungen vorhanden sind, verwendet die API die App-Registrierung; fehlen sie, greift sie für Bereitstellungen im selben Mandanten auf die verwaltete Identität zurück.

Freigegebenes Postfach und Anwendungszugriffsrichtlinie. Erstellen Sie im M365-Mandanten ein nicht lizenziertes freigegebenes Postfach für E-Mail-Benachrichtigungen und begrenzen Sie Mail.Send so, dass die App nur aus diesem einen Postfach senden kann:

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

Jeder M365-Mandant wiederholt anschließend die Schritte 2–5 (Apps, Genehmigungen, API-URL — dieselbe API-URL bedient alle Mandanten). Teams-Aktivitätsfeed-Benachrichtigungen erfordern zusätzlich die Administratoreinwilligung für die Realizer-Unternehmensanwendung und die für Benutzer installierte Teams-App; Einzelheiten finden Sie unter Erste Einrichtung.

Rollback und Betrieb

Standardmäßige Azure-Mechanismen decken das Rollback ab: Stellen Sie ein vorheriges API-Paket aus dem Verlauf des App Service-Bereitstellungscenters erneut bereit, stellen Sie Azure SQL per Zeitpunktwiederherstellung (bis zu 35 Tage) wieder her und laden Sie eine frühere versionierte .sppkg erneut in den App-Katalog hoch. Importe von Konfigurationspaketen sind additiv und werden über eine Datenbankwiederherstellung rückgängig gemacht. Für das vollständige Betriebsrunbook — detaillierte Rollback-Verfahren, Überwachung und Wartungsaufgaben — wenden Sie sich an unser Support-Team.