Käyttöönotto-opas

AccessPoint käyttää jaettua käyttöönottomallia: kevyt SPFx-verkko-osa SharePointissa, Teams-sovellus, joka isännöi samaa verkko-osaa henkilökohtaisena välilehtenä, sekä Azure-taustajärjestelmä, joka ajaa API:a ja tallentaa kaiken tiedon. Jokainen osa sijoittuu omaan Microsoft 365 -vuokraajaasi ja Azure-tilaukseesi — mitään ei isännöi julkaisija, eikä asiakastieto poistu ympäristöstäsi.

Yleiskatsaus

Suvereeneja pilviä / hallintopilviä, versiokiinnitystä tai skriptattuja käyttöönottoja varten kaikki artefaktit julkaistaan myös osoitteessa https://get.realizer.io/public/accesspoint/latest/.

Asennusjärjestyksellä on merkitystä. Asenna SharePoint-ratkaisu ennen kuin kukaan käyttäjä avaa Teamsin henkilökohtaisen välilehden. Teams-sovellus lataa SPFx-verkko-osan SharePointista iframe-kehyksessä — ilman sitä käyttäjät näkevät Teamsin sisällä SharePointin 404-virheen.

Edellytykset

• Aktiivinen AccessPoint-tilaus ja lisenssin API-avain (hanki AccessPoint)
• Azure-tilaus, jossa on Contributor-oikeudet (tai korkeammat) kohderesurssiryhmään
• Vuokraajaasi tarjottu SharePoint-sovelluskatalogi sekä SharePoint Administrator -oikeudet
• Global Administrator- tai Application Administrator -oikeudet Entra ID:ssä Graph-käyttöoikeuksien myöntämistä ja järjestelmänvalvojan suostumusta varten
• Teams Administrator (tai Global Administrator) Teams-sovelluksen julkaisemiseen
• Skriptattuja tai manuaalisia käyttöönottoja varten: Azure CLI (kirjautuneena komennolla az login käyttäjänä, ei palvelun päänimenä) sekä PnP.PowerShell-moduuli

Mikään Microsoft 365 -lisenssitaso, Power Platform tai Dataverse-riippuvuus ei ole tarpeen — kuka tahansa käyttäjä, jolla on SharePoint- tai Teams-käyttöoikeus, voi käyttää AccessPointia.

Vaihe 1: Ota käyttöön Azure-resurssit

Tämä vaihe tarjoaa taustajärjestelmän: Linux App Servicen (API), Azure SQL Databasen, Blob Storagen ja Application Insightsin Log Analyticsin kanssa. Resurssit nimetään muotoon {type}-accesspoint-{tenantName} (esimerkiksi app-accesspoint-contoso) ja ne on oletuksena kovennettu (TLS 1.3, vain Entra-pohjainen SQL-todennus, FTPS ja perustodennus pois käytöstä).

Vaihtoehto A: Azure-portaali (suositellaan). Ota AccessPointin Bicep/ARM-malli käyttöön yhdellä napsautuksella Azure-portaalista (Deploy to Azure -painike). Käyttöönottolomake kerää tilauksesi ja resurssiryhmäsi, vuokraajan nimen (esim. contoso osoitteesta contoso.sharepoint.com), lisenssin API-avaimen, App Servicen SKU:n (B1 arviointia varten, S1 vakiotuotantoon, P1v3 oletuksena), valinnaisen hälytyssähköpostiosoitteen sekä Myönnä Graph-käyttöoikeudet -kytkimen (päällä oletuksena; vaatii Application Administrator -oikeudet). API-paketti otetaan käyttöön App Serviceen automaattisesti — käyttöönoton jälkeen ei ole ajonaikaista riippuvuutta ulkoisiin palveluihin.

Vaihtoehto B: Bicep + PowerShell. Mukautettuja putkia tai tiukkaa muutoshallintaa varten aja käyttöönottoskripti julkaistua ARM-mallia vastaan:

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

Skripti suorittaa enintään seitsemän vaihetta — infrastruktuurin, vain Entra-pohjaisen SQL-todennuksen, Graph-käyttöoikeuksien myöntämisen, App Servicen pysäytys/käynnistys-syklin, SharePointin tallennusentiteetin (API-osoite), SPFx:n API-käyttöoikeuksien hyväksynnät sekä valinnaiset sovellusasennukset. Jokainen vaihe voidaan ohittaa erikseen (-SkipInfrastructure, -SkipGraphPermissions, -SkipSharePoint). Kiinnitä versio parametrilla -ArtifactBaseUrl "https://get.realizer.io/public/accesspoint/1.0.0" toistettavia, eheystarkastettuja käyttöönottoja varten (skripti tarkistaa julkaistun SHA-256-tarkisteen ja keskeyttää, jos se ei täsmää).

Jos haluat suorittaa infrastruktuuriosat itse:

$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

Graph-käyttöoikeuksien myöntäminen. App Servicen hallitulla identiteetillä on oltava viisi Microsoft Graph -sovellusoikeutta: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All ja AppCatalog.Read.All. Malli myöntää ne automaattisesti (grantGraphPermissions=true, oletusarvo), kun käyttöönoton suorittavalla käyttäjällä on Application Administrator -oikeudet tai AppRoleAssignment.ReadWrite.All. Jos ei ole, myönnä ne jälkikäteen:

$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

Vahvista: siirry osoitteeseen https://<api-url>/api/health ja varmista, että vastaus on toimiva.

Vaihe 2: Asenna AccessPoint-sovellukset

Asenna SharePoint-ratkaisu ensin, sitten Teams-sovellus.

SharePoint-ratkaisu. Napsauta AppSource-listauksessa Get it now ja hyväksy se SharePoint-sovelluskatalogiisi käyttöönotettavaksi koko vuokraajan laajuisesti. Vaihtoehtoisesti lataa se manuaalisesti (SharePoint Admin Center > More features > Apps > Upload, valitse "Make this solution available to all sites") tai anna skriptin tehdä se.

Teams-sovellus. Napsauta AppSource-listauksessa Get it now ja hyväksy se Teams Admin Centerissä, tai asenna molemmat sovellukset skriptillä (sisäänkirjautuneella käyttäjällä on oltava SharePoint-järjestelmänvalvojan oikeudet sekä Teams-järjestelmänvalvojan tai Global Administrator -oikeudet):

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

Älä käytä SharePointin "Sync to Teams" -toimintoa. Se ohittaa hiljaisesti manifestin webApplicationInfo.id-kentän, mikä rikkoo Teamsin toimintosyötteen ilmoitukset. Lataa Teams-sovellus suoraan Teams Admin Centeriin.

Vahvista: ratkaisu näkyy sovelluskatalogissa ilman virheitä, ja AccessPoint näkyy tilassa Allowed kohdassa Teams Admin Center > Manage apps.

Vaihe 3: Hyväksy API-käyttöoikeudet

SPFx-paketti pyytää delegoituja käyttöoikeuksia, jotka SharePoint-järjestelmänvalvojan on hyväksyttävä. Siirry SharePoint Admin Centerissä kohtaan Advanced > API access ja hyväksy jokainen odottava AccessPoint-pyyntö (access_as_user AccessPoint-API:lle sekä Graph-laajuudet, kuten User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read).

Tai hyväksy PnP PowerShellin kautta:

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
}

Lopuksi Global Administrator myöntää järjestelmänvalvojan suostumuksen julkaisijan monivuokraaja-sovellukselle avaamalla selaimessa osoitteen https://login.microsoftonline.com/common/adminconsent?client_id=ed19c96c-a7c5-4dca-8b47-0899c406329f.

Vahvista: API-käyttösivulla ei näy odottavia AccessPoint-pyyntöjä.

Vaihe 4: Käytä AccessPointia SharePointissa tai Teamsissa

SharePoint: muokkaa tai luo sivu, napsauta +, hae AccessPoint, lisää verkko-osa ja julkaise.

Teams: käyttäjät löytävät AccessPointin kohdasta Apps > Built for your org (hakuindeksointi voi kestää 15 minuutista useisiin tunteihin ensimmäisen asennuksen jälkeen). Voit valinnaisesti kiinnittää sen kaikille kohdassa Teams Admin Center > App setup policies lisäämällä AccessPointin kohtiin Installed apps ja Pinned apps.

Vaihe 5: Määritä API-osoite

Avaa verkko-osa ja siirry kohtaan Asetukset > Asennus. Syötä API-osoite (App Service -osoite vaiheesta 1, esim. https://app-accesspoint-contoso.azurewebsites.net) ja API:n Entra ID -sovellusrekisteröinnin asiakastunnus, ja napsauta sitten Tallenna. Paneeli tarkistaa HTTPS-muodon ja GUID-muodon ennen tallennusta.

Käyttöönottoskripti asettaa taustalla olevan SharePoint-tallennusentiteetin puolestasi. Aseta se manuaalisesti näin:

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

Vahvista: lataa verkko-osa uudelleen — kojelauta latautuu asennuskehotteen sijaan.

Vaihe 6: Tuo määrityspaketti

Siirry kohtaan Asetukset > Määrityspaketit, valitse omaa lainkäyttöaluettasi vastaava paketti (Kanada ATIA, Yhdysvallat FOIA, EU GDPR ja muut) ja napsauta Tuo. Paketti luo pyyntötyypit, jatkoaikaperusteet, valintakentät, ilmoitusmallit ja käännökset. Tarkista ja mukauta tuodut kohteet tuonnin jälkeen.

Vaihe 7: Määritä käyttäjäroolit

Ensimmäiselle käyttäjälle, joka avaa AccessPointin, myönnetään automaattisesti Administrator- ja SAO-roolit. Siirry kohtaan Asetukset > Käyttäjien hallinta, napsauta Lisää käyttäjä, hae hakemistostasi ja määritä roolit: vähintään yksi Administrator ja yksi SAO, sekä tarpeen mukaan Custodian-, Contributor-, Reviewer- ja Reader-roolit.

AccessPoint on nyt valmis käyttöön.

Monivuokraajakäyttöönotto

Käytä tätä mallia, kun Azure-taustajärjestelmä sijaitsee eri Entra ID -vuokraajassa kuin Microsoft 365 -vuokraajasi — esimerkiksi jaettujen palveluiden tiimi, joka palvelee useita liiketoimintayksiköitä, MSP-toimija, joka isännöi asiakkaille, tai Azure- ja M365-vuokraajat, jotka on eriytetty hallinnollisista syistä. Yksi käyttöönotto voi palvella useita M365-vuokraajia: API eristää tiedot kunkin käyttäjän tunnisteessa olevan vuokraajatunnuksen perusteella, käyttäen vuokraajakohtaisia tietokantakyselysuodattimia ja vuokraajan etuliitteellä varustettuja blob-polkuja. Jokainen M365-vuokraaja tarvitsee silti oman lisenssinsä, oman SPFx-käyttöönottonsa ja API-käyttöoikeushyväksyntänsä sekä omat Graph-tunnuksensa ja ilmoituspostilaatikkonsa.

Graph-sovellusrekisteröinti. Hallittu identiteetti toimii vain kotivuokraajassaan, joten luo yksittäisvuokraaja-sovellusrekisteröinti M365-vuokraajaan (esim. AccessPoint Graph Connector), myönnä sille samat viisi Graph-sovellusoikeutta, jotka on lueteltu vaiheessa 1, järjestelmänvalvojan suostumuksella, ja luo sitten asiakassalaisuus (client secret) ja kytke se App Serviceen Key Vaultin kautta:

# 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

Älä koskaan tallenna salaisuutta suoraan App Servicen asetuksiin; App Servicen hallitulla identiteetillä on oltava Key Vault Secrets User -rooli säilössä. Kun kaikki kolme Graph__*-asetusta ovat läsnä, API käyttää sovellusrekisteröintiä; kun ne puuttuvat, se käyttää oletuksena hallittua identiteettiä samassa vuokraajassa tapahtuvissa käyttöönotoissa.

Jaettu postilaatikko ja sovelluksen käyttöoikeuskäytäntö. Luo lisensoimaton jaettu postilaatikko M365-vuokraajaan sähköposti-ilmoituksia varten, ja rajaa Mail.Send-oikeuden laajuus niin, että sovellus voi lähettää vain kyseisestä postilaatikosta:

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

Jokainen M365-vuokraaja toistaa sen jälkeen vaiheet 2–5 (sovellukset, hyväksynnät, API-osoite — sama API-osoite palvelee kaikkia vuokraajia). Teamsin toimintosyötteen ilmoitukset edellyttävät lisäksi järjestelmänvalvojan suostumusta Realizerin yrityssovellukselle (enterprise application) sekä käyttäjille asennetulle Teams-sovellukselle; katso lisätietoja kohdasta Alkuasetukset.

Palautus ja käyttötoiminnot

Vakiomuotoiset Azure-mekanismit kattavat palautuksen: ota käyttöön aiempi API-paketti App Servicen Deployment Center -historiasta, palauta Azure SQL ajankohtaan perustuvalla palautuksella (enintään 35 päivää) ja lataa uudelleen aiempi versioitu .sppkg-tiedosto sovelluskatalogiin. Määrityspakettien tuonnit ovat lisääviä, ja ne perutaan tietokannan palautuksella. Täydellisen operatiivisen toimintaohjeen — yksityiskohtaiset palautusmenettelyt, valvonta ja ylläpitotehtävät — saat ottamalla yhteyttä tukitiimiimme.