Przewodnik wdrożeniowy

AccessPoint wykorzystuje podzielony model wdrożenia: lekki web part SPFx w SharePoint, aplikację Teams, która hostuje ten sam web part jako kartę osobistą, oraz backend w Azure, który obsługuje API i przechowuje wszystkie dane. Każdy komponent trafia do Twojej własnej dzierżawy Microsoft 365 i subskrypcji Azure — nic nie jest hostowane przez wydawcę, a żadne dane klienta nie opuszczają Twojego środowiska.

Przegląd

Dla chmur suwerennych/rządowych, przypinania konkretnej wersji lub wdrożeń skryptowych wszystkie artefakty są również publikowane pod adresem https://get.realizer.io/public/accesspoint/latest/.

Kolejność instalacji ma znaczenie. Zainstaluj rozwiązanie SharePoint zanim jakikolwiek użytkownik otworzy osobistą kartę Teams. Aplikacja Teams ładuje web part SPFx z SharePoint w ramach elementu iframe — bez niego użytkownicy zobaczą błąd SharePoint 404 wewnątrz Teams.

Wymagania wstępne

• Aktywna subskrypcja AccessPoint oraz klucz API licencji (pobierz AccessPoint)
• Subskrypcja Azure z uprawnieniami Contributor (lub wyższymi) w docelowej grupie zasobów
• SharePoint App Catalog przygotowany w Twojej dzierżawie oraz uprawnienia SharePoint Administrator
• Rola Global Administrator lub Application Administrator w Entra ID — do przyznawania uprawnień Graph i wyrażania zgody administratora (admin consent)
• Rola Teams Administrator (lub Global Admin) — do publikacji aplikacji Teams
• Do wdrożeń skryptowych lub ręcznych: Azure CLI (zalogowane poleceniem az login jako użytkownik, a nie jednostka usługi) oraz moduł PnP.PowerShell

Nie istnieje żadna zależność od poziomu licencji Microsoft 365, Power Platform ani Dataverse — z AccessPoint może korzystać każdy użytkownik mający dostęp do SharePoint lub Teams.

Krok 1: Wdrożenie zasobów Azure

Ten krok tworzy backend: App Service na Linuksie (API), bazę danych Azure SQL Database, Blob Storage oraz Application Insights wraz z Log Analytics. Zasoby są nazywane według wzorca {type}-accesspoint-{tenantName} (na przykład app-accesspoint-contoso) i są domyślnie zabezpieczone (TLS 1.3, uwierzytelnianie SQL wyłącznie przez Entra, wyłączone FTPS i podstawowe uwierzytelnianie).

Opcja A: portal Azure (zalecana). Wdróż szablon Bicep/ARM AccessPoint jednym kliknięciem z poziomu portalu Azure (przycisk Deploy to Azure). Formularz wdrożenia zbiera Twoją subskrypcję i grupę zasobów, nazwę dzierżawcy (np. contoso z contoso.sharepoint.com), klucz API licencji, SKU App Service (B1 do celów ewaluacyjnych, S1 do standardowej produkcji, domyślnie P1v3), opcjonalny adres e-mail do alertów oraz przełącznik Grant Graph Permissions (domyślnie włączony; wymaga roli Application Administrator). Pakiet API wdraża się automatycznie do App Service — po wdrożeniu nie występuje żadna zależność od usług zewnętrznych w czasie działania.

Opcja B: Bicep + PowerShell. W przypadku niestandardowych potoków wdrożeniowych lub rygorystycznej kontroli zmian uruchom skrypt wdrożeniowy względem opublikowanego szablonu ARM:

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

Skrypt wykonuje do siedmiu kroków — infrastrukturę, uwierzytelnianie SQL wyłącznie przez Entra, przyznanie uprawnień Graph, cykl zatrzymania/uruchomienia App Service, storage entity SharePoint (adres URL API), zatwierdzenie uprawnień API SPFx oraz opcjonalną instalację aplikacji. Każdy z tych kroków można pominąć niezależnie (-SkipInfrastructure, -SkipGraphPermissions, -SkipSharePoint). Przypnij konkretną wersję za pomocą -ArtifactBaseUrl "https://get.realizer.io/public/accesspoint/1.0.0", aby uzyskać powtarzalne wdrożenia z weryfikacją integralności (skrypt sprawdza opublikowany skrót SHA-256 i przerywa działanie w przypadku niezgodności).

Aby samodzielnie wykonać poszczególne elementy infrastruktury:

$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

Przyznawanie uprawnień Graph. Managed identity App Service wymaga pięciu uprawnień aplikacji Microsoft Graph: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All oraz AppCatalog.Read.All. Szablon przyznaje je automatycznie (grantGraphPermissions=true, wartość domyślna), gdy użytkownik przeprowadzający wdrożenie ma rolę Application Administrator lub uprawnienie AppRoleAssignment.ReadWrite.All. Jeśli nie, przyznaj je później:

$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

Weryfikacja: przejdź do https://<api-url>/api/health i potwierdź prawidłową odpowiedź.

Krok 2: Instalacja aplikacji AccessPoint

Najpierw zainstaluj rozwiązanie SharePoint, a następnie aplikację Teams.

Rozwiązanie SharePoint. Na stronie w AppSource kliknij Get it now i zatwierdź je do swojego SharePoint App Catalog, wdrożonego w całej dzierżawie. Możesz też przesłać je ręcznie (SharePoint Admin Center > More features > Apps > Upload, zaznacz „Make this solution available to all sites”) albo pozwolić, by zrobił to skrypt.

Aplikacja Teams. Na stronie w AppSource kliknij Get it now i zatwierdź ją w Teams Admin Center, albo zainstaluj obie aplikacje za pomocą skryptu (zalogowany użytkownik potrzebuje uprawnień SharePoint admin oraz Teams admin lub Global admin):

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

NIE używaj funkcji SharePoint „Sync to Teams”. Cicho nadpisuje ona webApplicationInfo.id w manifeście, co powoduje przerwanie powiadomień w kanale aktywności Teams. Prześlij aplikację Teams bezpośrednio do Teams Admin Center.

Weryfikacja: rozwiązanie pojawia się w katalogu aplikacji bez błędów, a AccessPoint jest oznaczony jako Allowed w Teams Admin Center > Manage apps.

Krok 3: Zatwierdzenie uprawnień API

Pakiet SPFx żąda uprawnień delegowanych, które musi zatwierdzić administrator SharePoint. W SharePoint Admin Center przejdź do Advanced > API access i zatwierdź każde oczekujące żądanie AccessPoint (access_as_user dla API AccessPoint oraz zakresy Graph, takie jak User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read).

Możesz też zatwierdzić je za pomocą 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
}

Na koniec Global Administrator udziela zgody administratora (admin consent) dla wielodzierżawcowej aplikacji wydawcy, otwierając w przeglądarce adres https://login.microsoftonline.com/common/adminconsent?client_id=ed19c96c-a7c5-4dca-8b47-0899c406329f.

Weryfikacja: strona API access nie pokazuje już żadnych oczekujących żądań AccessPoint.

Krok 4: Korzystanie z AccessPoint w SharePoint lub Teams

SharePoint: edytuj lub utwórz stronę, kliknij +, wyszukaj AccessPoint, dodaj web part i opublikuj stronę.

Teams: użytkownicy znajdą AccessPoint w Apps > Built for your org (indeksowanie wyszukiwania może potrwać od 15 minut do kilku godzin po pierwszej instalacji). Opcjonalnie możesz przypiąć aplikację dla wszystkich za pomocą Teams Admin Center > App setup policies, dodając AccessPoint do Installed apps i Pinned apps.

Krok 5: Konfiguracja adresu URL API

Otwórz web part i przejdź do Settings > Setup. Wprowadź API URL (adres URL App Service z kroku 1, np. https://app-accesspoint-contoso.azurewebsites.net) oraz Client ID rejestracji aplikacji Entra ID dla API, a następnie kliknij Save. Przed zapisaniem panel weryfikuje użycie HTTPS oraz format GUID.

Skrypt wdrożeniowy ustawia za Ciebie odpowiedni storage entity SharePoint. Aby ustawić go ręcznie:

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

Weryfikacja: odśwież web part — powinien załadować się pulpit zamiast monitu konfiguracyjnego.

Krok 6: Import pakietu konfiguracyjnego

Przejdź do Settings > Configuration Packs, wybierz pakiet odpowiedni dla Twojej jurysdykcji (Canada ATIA, US FOIA, EU GDPR i inne) i kliknij Import. Pakiet tworzy typy wniosków, powody przedłużenia, pola wyboru, szablony powiadomień oraz tłumaczenia. Po imporcie przejrzyj i dostosuj zaimportowane elementy.

Krok 7: Przypisanie ról użytkowników

Pierwszy użytkownik, który otworzy AccessPoint, automatycznie otrzymuje role Administrator i SAO. Przejdź do Settings > Manage Users, kliknij Add User, wyszukaj użytkowników w swoim katalogu i przypisz role: co najmniej jednego Administrator i jednego SAO, a w razie potrzeby także role Custodian, Contributor, Reviewer i Reader.

AccessPoint jest teraz gotowy do użycia.

Wdrożenie wielodzierżawcowe

Zastosuj ten wzorzec, gdy backend Azure znajduje się w innej dzierżawie Entra ID niż Twoja dzierżawa Microsoft 365 — na przykład zespół usług wspólnych obsługujący kilka jednostek biznesowych, dostawca MSP hostujący usługę dla klientów, lub rozdzielone dzierżawy Azure/M365 z powodów zarządczych. Pojedyncze wdrożenie może obsługiwać wiele dzierżaw M365: API izoluje dane według identyfikatora dzierżawcy zawartego w tokenie każdego użytkownika, stosując filtry zapytań do bazy danych ograniczone do danej dzierżawy oraz ścieżki blobów z prefiksem dzierżawcy. Każda dzierżawa M365 nadal wymaga własnej licencji, własnego wdrożenia SPFx i zatwierdzeń uprawnień API oraz własnych poświadczeń Graph i skrzynki powiadomień.

Rejestracja aplikacji Graph. Managed identity działa wyłącznie we własnej dzierżawie macierzystej, dlatego utwórz jednodzierżawcową rejestrację aplikacji w dzierżawie M365 (np. AccessPoint Graph Connector), przyznaj jej te same pięć uprawnień aplikacji Graph wymienionych w kroku 1 wraz ze zgodą administratora (admin consent), a następnie utwórz sekret klienta i połącz go z App Service za pośrednictwem 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

Nigdy nie przechowuj sekretu bezpośrednio w ustawieniach App Service; managed identity App Service musi mieć rolę Key Vault Secrets User w magazynie kluczy. Gdy obecne są wszystkie trzy ustawienia Graph__*, API korzysta z rejestracji aplikacji; gdy ich brak, powraca do managed identity w przypadku wdrożeń w tej samej dzierżawie.

Skrzynka współdzielona i zasady dostępu aplikacji. Utwórz w dzierżawie M365 nielicencjonowaną skrzynkę współdzieloną na potrzeby powiadomień e-mail i ogranicz Mail.Send tak, aby aplikacja mogła wysyłać wiadomości wyłącznie z tej jednej skrzynki:

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

Następnie każda dzierżawa M365 powtarza kroki 2–5 (aplikacje, zatwierdzenia, adres URL API — ten sam adres URL API obsługuje wszystkie dzierżawy). Powiadomienia w kanale aktywności Teams dodatkowo wymagają zgody administratora dla aplikacji korporacyjnej Realizer oraz zainstalowanej dla użytkowników aplikacji Teams; szczegóły znajdziesz w Konfiguracji wstępnej.

Wycofywanie zmian i operacje

Standardowe mechanizmy Azure obejmują wycofywanie zmian: ponowne wdrożenie poprzedniego pakietu API z historii Deployment Center App Service, przywrócenie Azure SQL za pomocą przywracania do punktu w czasie (do 35 dni) oraz ponowne przesłanie poprzedniej wersji pliku .sppkg do katalogu aplikacji. Importy pakietów konfiguracyjnych są addytywne i można je cofnąć poprzez przywrócenie bazy danych. Pełny plan operacyjny — szczegółowe procedury wycofywania zmian, monitorowanie i zadania konserwacyjne — uzyskasz, kontaktując się z naszym zespołem wsparcia.