Verwenden von ACS zum Autorisieren von vom Anbieter gehosteten Add-Ins mit niedriger Vertrauensebene auf einer lokalen SharePoint-Website

Artikel
04/08/2023

Voraussetzungen

Sorgen Sie dafür, dass Sie über Folgendes verfügen:

Eine lokale SharePoint-Entwicklungsumgebung. Weitere Informationen finden Sie unter Einrichten einer lokalen Entwicklungsumgebung für SharePoint-Add-Ins.
Eine Office 365 SharePoint-Website. Wenn Sie noch keine haben und schnell eine Entwicklungsumgebung einrichten möchten, können Sie eine Entwicklungsumgebung für SharePoint-Add-Ins auf Office 365 einrichten.
Visual Studio wird entweder remote oder auf einem Computer installiert, auf dem SharePoint ausgeführt wird, mit der Workload Office/SharePoint-Entwicklung. Frühere Versionen von Visual Studio erfordern stattdessen die Komponente Microsoft Office Developer Tools für Visual Studio . Die neueste Version dieser Komponente ist hier für Visual Studio 2013 und hier für Visual Studio 2015 verfügbar.

Wichtig

Das Einstellen von ACS seitens Azure Active Directory wirkt sich nicht auf diese Funktionalität von SharePoint aus. Weitere Einzelheiten finden Sie in folgendem Artikel: Auswirkungen der Deaktivierung von Azure Access Control für SharePoint-Add-Ins.

Konfigurieren Ihrer lokalen Installation von SharePoint für die Verwendung von ACS

Die folgende Abbildung zeigt die vier Schritte, um die Verbindungen zu aktivieren, die Sie in der Gesamtarchitektur eines vom Anbieter gehosteten Add-Ins benötigen, das auf einer lokalen Website ausgeführt wird. Sie zeigt außerdem den Fluss von OAuth-Token, wenn das Add-In ausgeführt wird.

Verwenden von ACS mit einer lokalen Installation von SharePoint mithilfe einer Office 365 SharePoint-Website

Verwenden von ACS mit einer lokalen Installation von SharePoint mithilfe einer Office 365-Website

Erstellen Sie in Ihrer lokalen SharePoint-Farm einen ACS-Proxy.
Installieren Sie das Signaturzertifikat Ihres lokalen Servers auf Ihrem Office 365-Mandanten.
Fügen Sie die vollständig qualifizierten Domänennamen auf Ihrer SharePoint-Farm, auf der Sie Add-Ins ausführen möchten, der Sammlung der Dienstprinzipalnamen auf Ihrem Office 365-Mandanten hinzu.
Erstellen Sie in Ihrer SharePoint-Farm einen Add-In-Verwaltungsproxy.

Die folgende Funktion führt alle Schritte zum Konfigurieren Ihrer lokalen SharePoint-Website aus, um ACS zu verwenden. Sie können diese Funktion auch verwenden, um einige Bereinigungsaufgaben auszuführen, wenn Sie frühere Konfigurationen entfernen müssen. Es gibt viele verschiedene Arten die Funktion in der PowerShell ausführen. Nachfolgend finden Sie eine dieser Methoden:

Konfigurieren Ihrer lokalen SharePoint-Website für die Verwendung von ACS

Kopieren Sie auf dem lokalen SharePoint-Server den Code der Funktion Connect-SPFarmToAAD (unten verfügbar) in eine Textdatei mit dem Namen MySharePointFunctions.psm1, und speichern Sie ihn in einem der folgenden Ordner (nicht beide). Möglicherweise müssen Sie Teile des Pfads erstellen, wenn er Ordner enthält, die noch nicht vorhanden sind. Beachten Sie, dass in beiden Fällen der niedrigste Ordner im Pfad den gleichen Namen wie die Datei haben muss.

Tipp

Die Datei muss im ANSI-Format und nicht in UTF-8 gespeichert werden. PowerShell kann Syntaxfehler zurückgeben, wenn es eine Datei in einem anderen Format als ANSI lädt. Windows NotePad speichert die Datei standardmäßig im ANSI-Format. Wenn Sie einen anderen Editor verwenden, um die Datei zu speichern, stellen Sie sicher, dass Sie sie im ANSI-Format speichern.
- C:\users\username\documents\windowspowershell\modules\MySharePointFunctions, wobei username für den Farmadministrator steht, der die Datei ausführt.
- C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions
Die Funktion Connect-SPFarmToAAD erfordert, dass das NuGet-Paket MSOnlineExt funktioniert. Installieren Sie es mit dem folgenden Cmdlet.
```
Install-Module -Name MSOnlineExt
```
Öffnen Sie die SharePoint-Verwaltungsshell als Administrator, und führen Sie das folgende Cmdlet aus, um überprüfen, ob das MySharePointFunctions-Modul aufgeführt wird.
```
Get-Module -listavailable
```
Führen Sie das folgende Cmdlet aus, um das Modul zu importieren.
```
Import-Module MySharePointFunctions
```
Führen Sie das folgende Cmdlet aus, um sicherzustellen, dass die Connect-SPFarmToAAD-Funktion als Teil des Moduls aufgeführt wird.
```
Get-Command -module MySharePointFunctions
```
Führen Sie das folgende Cmdlet aus, um sicherzustellen, dass die Connect-SPFarmToAAD-Funktion geladen ist.
```
ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}
```
Führen Sie die Connect-SPFarmToAAD-Funktion aus. Geben Sie die erforderlichen Parameter und alle optionalen Parameter an, die sich auf Ihre Entwicklerumgebung beziehen. Im nächsten Abschnitt finden Sie nähere Informationen und Beispiele.

Parameter der Connect-SPFarmToAAD-Funktion

Parameter	Wert
`-AADDomain` (erforderlich)	Die .onmicrosoft.com-Domäne, die Sie bei der Anmeldung für Ihre Office 365-Website erstellt haben (yourcustomdomain. onmicrosoft.com). Wenn das Skript Sie zur Authentifizierung aufgefordert, verwenden Sie den Benutzernamen und das Kennwort, das Sie für diese Domäne erstellt haben: Benutzername@yourcustomdomain*. onmicrosoft.com.
`-SharePointOnlineUrl` (erforderlich)	Die URL Ihrer Office 365 SharePoint-Website (`_https://yourcustomdomain_.sharepoint.com`). Beachten Sie, dass die übergeordnete Domäne nicht onmicrosoft.com ist.
`-SharePointWeb` (manchmal erforderlich)	Die vollständige URL (einschließlich des Protokolls) der lokalen SharePoint-Webanwendung, in der Sie vom Anbieter gehostete Add-Ins ausführen werden. Diese Funktion fügt nur eine SharePoint-Webanwendung aus Ihrer lokalen Farm zu ACS hinzu. Wenn Sie dafür keinen Wert angeben, wird wählt das Skript die ersten Webanwendung in Ihrer Farm aus. Wenn Sie eine Hostname-Websitesammlung (HNSC) verwenden, die mit Platzhalterzeichen definiert werden kann, (z. B. http://.contoso.com), können Sie diese Zeichenfolge als Wert für diesen Parameter verwenden. Wenn die Webanwendung eine alternative Zugriffszuordnung (AAM) für die Internetzone besitzt, müssen Sie diese AAM-URL für diesen Parameter verwenden. Wenn die SharePoint-Webanwendung nicht für HTTPS konfiguriert ist, müssen Sie HTTP als Protokoll und den Switch -AllowOverHttp (siehe weiter unten in dieser Tabelle) verwenden.* Wenn Sie vom Anbieter gehostete Add-Ins ausführen möchten, die ACS für mehrere Webanwendungen in Ihrer Farm verwenden, müssen Sie sie zur Dienstprinzipalnamen-Sammlung hinzufügen. Das Windows PowerShell-Skript, das der `Connect-SPFarmToAAD`-Funktion folgt, zeigt Ihnen, wie Sie alle Webanwendungen Ihrer Farm zur Dienstprinzipalnamen-Sammlung hinzufügen.
`-AllowOverHttp` (optional)	Verwenden Sie diesen Switch, wenn Sie mit einer Entwicklerumgebung arbeiten und für Ihre Add-Ins kein SSL verwenden möchten. Sie müssen diesen Switch verwenden, wenn die SharePoint-Webanwendung nicht für HTTPS konfiguriert ist.
`-O365Credentials` (optional)	Das erste Zeichen ist ein großes "O" und keine Null. Wenn Sie das Skript wiederholt zum Debuggen ausführen müssen, können Sie mit diesem Switch vermeiden, dass Sie Ihren O365-Namen und das Kennwort jedes Mal manuell eingeben müssen. Bevor Sie diesen Parameter verwenden können, müssen Sie das Anmeldeinformationenobjekt erstellen, das Sie mit diesen Cmdlets zuweisen:`$User = "username@yourcustomdomain.onmicrosoft.com"$PWord = ConvertTo-SecureString -String "the_password" -AsPlainText -Force$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord` Verwenden Sie `$Credential` als Wert des `-O365Credentials` Parameters.
`-Verbose` (optional)	Dieser Switch generiert ausführlicheres Feedback, das hilfreich sein kann, wenn die Funktion nicht funktioniert und Sie sie zum Debuggen erneut ausführen müssen.
`-RemoveExistingACS` (optional)	Verwenden Sie diesen Switch, wenn Sie eine vorhandene Verbindung mit Azure Active Directory ersetzen. Ein vorhandener ACS-Proxy wird entfernt, wenn Sie bereits einen in Ihrer Farm erstellt haben.
`-RemoveExistingSTS` (optional)	Verwenden Sie diesen Switch, wenn Sie eine vorhandene Verbindung mit Azure Active Directory ersetzen. Ein vorhandener vertrauenswürdiger Sicherheitstoken-Herausgeber, der von einer früheren Verbindung zu ACS übrig geblieben ist, wird entfernt.
`-RemoveExistingSPOProxy` (optional)	Verwenden Sie diesen Switch, wenn Sie eine vorhandene Verbindung mit Azure Active Directory ersetzen. Ein vorhandener Add-In-Verwaltungsproxy wird entfernt, wenn Sie bereits einen in Ihrer Farm erstellt haben.
`-RemoveExistingAADCredentials` (optional)	Verwenden Sie diesen Switch, wenn Sie die Office 365-SharePoint-Website ersetzen.

Es folgen Beispiele:

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb https://fabrikam.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp -RemoveExistingACS -RemoveExistingSTS -RemoveExistingSPOProxy -RemoveExistingAADCredentials

Inhalt von MySharePointFunctions.psm1

function Connect-SPFarmToAAD {
param(
    [Parameter(Mandatory)][String]   $AADDomain,
    [Parameter(Mandatory)][String]   $SharePointOnlineUrl,
    #Specify this parameter if you don't want to use the default SPWeb returned
    [Parameter()][String]            $SharePointWeb,
    [Parameter()][System.Management.Automation.PSCredential] $O365Credentials,
    #Use these switches if you're replacing an existing connection to AAD.
    [Parameter()][Switch]            $RemoveExistingACS,
    [Parameter()][Switch]            $RemoveExistingSTS,
    [Parameter()][Switch]            $RemoveExistingSPOProxy,
    #Use this switch if you're replacing the Office 365 SharePoint site.
    [Parameter()][Switch]            $RemoveExistingAADCredentials,
    #Use this switch if you don't want to use SSL when you launch your app.
    [Parameter()][Switch]            $AllowOverHttp
)
    #Prompt for credentials right away.
    if (-not $O365Credentials) {
        $O365Credentials = Get-Credential -Message "Admin credentials for $AADDomain"
    }
    Add-PSSnapin Microsoft.SharePoint.PowerShell
    #Import the Microsoft Online Services Sign-In Assistant.
    Import-Module -Name MSOnline
    #Import the Microsoft Online Services Module for Windows PowerShell.
    Import-Module MSOnlineExt -force -verbose 
    #Set values for Constants.
    New-Variable -Option Constant -Name SP_APPPRINCIPALID -Value '00000003-0000-0ff1-ce00-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPRINCIPALID -Value '00000001-0000-0000-c000-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPROXY_NAME -Value ACS
    New-Variable -Option Constant -Name SPO_MANAGEMENT_APPPROXY_NAME -Value 'SPO Add-in Management Proxy'
    New-Variable -Option Constant -Name ACS_STS_NAME -Value ACS-STS
    New-Variable -Option Constant -Name AAD_METADATAEP_FSTRING -Value 'https://accounts.accesscontrol.windows.net/{0}/metadata/json/1'
    New-Variable -Option Constant -Name SP_METADATAEP_FSTRING -Value '{0}/_layouts/15/metadata/json/1'
    #Get the default SPWeb from the on-premises farm if no $SharePointWeb parameter is specified.
    if ([String]::IsNullOrEmpty($SharePointWeb)) {
        $SharePointWeb = Get-SPSite | Select-Object -First 1 | Get-SPWeb | Select-Object -First 1 | % Url
    }

    #Configure the realm ID for local farm so that it matches the AAD realm.
    $ACSMetadataEndpoint = $AAD_METADATAEP_FSTRING -f $AADDomain
    $ACSMetadata = Invoke-RestMethod -Uri $ACSMetadataEndpoint
    $AADRealmId = $ACSMetadata.realm

    Set-SPAuthenticationRealm -ServiceContext $SharePointWeb -Realm $AADRealmId
    
    $LocalSTS = Get-SPSecurityTokenServiceConfig
    $LocalSTS.NameIdentifier = '{0}@{1}' -f $SP_APPPRINCIPALID,$AADRealmId
    $LocalSTS.Update()

    #Allow connections over HTTP if the switch is specified.
    if ($AllowOverHttp.IsPresent -and $AllowOverHttp -eq $True) {
        $serviceConfig = Get-SPSecurityTokenServiceConfig
        $serviceConfig.AllowOAuthOverHttp = $true
        $serviceConfig.AllowMetadataOverHttp = $true
        $serviceConfig.Update()
    }

    #Step 1: Set up the ACS proxy in the on-premises SharePoint farm. Remove the existing ACS proxy
    #if the switch is specified.
    if ($RemoveExistingACS.IsPresent -and $RemoveExistingACS -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME)) {
        $AzureACSProxy = New-SPAzureAccessControlServiceApplicationProxy -Name $ACS_APPPROXY_NAME -MetadataServiceEndpointUri $ACSMetadataEndpoint -DefaultProxyGroup
    }

    #Remove the existing security token service if the switch is specified.
    if ($RemoveExistingSTS.IsPresent) {
        Get-SPTrustedSecurityTokenIssuer | ? Name -EQ $ACS_STS_NAME | Remove-SPTrustedSecurityTokenIssuer -Confirm:$false
    }
    if (-not (Get-SPTrustedSecurityTokenIssuer | ? DisplayName -EQ $ACS_STS_NAME)) {
        $AzureACSSTS = New-SPTrustedSecurityTokenIssuer -Name $ACS_STS_NAME -IsTrustBroker -MetadataEndPoint $ACSMetadataEndpoint
    }

    #Update the ACS Proxy for OAuth authentication.
    $ACSProxy = Get-SPServiceApplicationProxy | ? Name -EQ $ACS_APPPROXY_NAME
    $ACSProxy.DiscoveryConfiguration.SecurityTokenServiceName = $ACS_APPPRINCIPALID
    $ACSProxy.Update()

    #Retrieve the local STS signing key from JSON metadata.
    $SPMetadata = Invoke-RestMethod -Uri ($SP_METADATAEP_FSTRING -f $SharePointWeb)
    $SPSigningKey = $SPMetadata.keys | ? usage -EQ "Signing" | % keyValue
    $CertValue = $SPSigningKey.value
    
    #Connect to Office 365.
    Connect-MsolService -Credential $O365Credentials
    #Remove existing connection to an Office 365 SharePoint site if the switch is specified.
    if ($RemoveExistingAADCredentials.IsPresent -and $RemoveExistingAADCredentials -eq $true) {
        $msolserviceprincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
        [Guid[]] $ExistingKeyIds = Get-MsolServicePrincipalCredential -ObjectId $msolserviceprincipal.ObjectId -ReturnKeyValues $false | % {if ($_.Type -ne "Other") {$_.KeyId}}
        Remove-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -KeyIds $ExistingKeyIds
    }
    #Step 2: Upload the local STS signing certificate
    New-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -Type Asymmetric -Value $CertValue -Usage Verify

    #Step 3: Add the service principal name of the local web application, if necessary.
    $indexHostName = $SharePointWeb.IndexOf('://') + 3
    $HostName = $SharePointWeb.Substring($indexHostName)
    $NewSPN = '{0}/{1}' -f $SP_APPPRINCIPALID, $HostName
    $SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
        $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
        Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }

    #Remove the existing SharePoint Online proxy if the switch is specified.
    if ($RemoveExistingSPOProxy.IsPresent -and $RemoveExistingSPOProxy -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    #Step 4: Add the SharePoint Online proxy
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME)) {
        $spoproxy = New-SPOnlineApplicationPrincipalManagementServiceApplicationProxy -Name $SPO_MANAGEMENT_APPPROXY_NAME -OnlineTenantUri $SharePointOnlineUrl -DefaultProxyGroup
    }  
}

Konfigurieren des Add-Ins und der SharePoint-Webanwendung für den Office Store

Es gibt einen optionalen Konfigurationsschritt, den Farmadministratoren in Produktionsumgebungen ausführen sollten, wenn sie möchten, dass Benutzer vom Anbieter gehostete Add-Ins, die ACS aus dem Office Store verwenden, installieren können. (Dies ist nur dann zweckmäßig für Ihre SharePoint-Entwicklungsumgebung, wenn Sie planen, Add-Ins in dieser Umgebung zu installieren, die ACS aus dem Store verwenden.) Dies wird durch das folgende Cmdlet ermöglicht. Dieser Code kann zur vorhergehenden Funktion hinzugefügt werden.

New-SPMarketplaceWebServiceApplicationProxy -Name "ApplicationIdentityDataWebServiceProxy" -ServiceEndpointUri "https://oauth.sellerdashboard.microsoft.com/ApplicationIdentityDataWebService.svc" -DefaultProxyGroup

Dies empfiehlt sich auch bei Produktions-SharePoint-Webanwendungen, um das Feature Add-Ins, die zugängliche und für das Internet verwendete Endpunkte erfordern zu aktivieren, nachdem die Konfigurationsschritte abgeschlossen wurden. (Siehe die folgenden Anweisungen). Dieses Funktion hat keine Auswirkungen. Sie dient lediglich als Kennzeichnung, die dem Office Store mitteilt, dass vom Anbieter gehostete Add-Ins, die ACS verwenden, auf Websites in der SharePoint-Webanwendung installiert werden können.

Dieses System hat möglicherweise Auswirkungen auf das Add-In-Manifest Ihres SharePoint-Add-Ins. Falls Sie Ihr Add-In über den Store verkaufen möchten, sollten Sie die folgende AppPrerequiste dem AppPrerequisites-Abschnitt des Add-In-Manifests hinzufügen:

<AppPrerequisite Type="Feature" ID="{7877bbf6-30f5-4f58-99d9-a0cc787c1300}" />

Die Auswirkung der Voraussetzung ist, dass Ihr Add-In ausgegraut und als nicht installierbar dargestellt wird, wenn Benutzer den Store von einer lokalen SharePoint-Farm aus durchsuchen und wenn die übergeordnete SharePoint-Webanwendung das Feature Add-Ins, die verfügbare Internet-Endpunkte benötigen nicht aktiviert haben. Diese Vorgehensweise stellt sicher, dass Benutzer, die Ihr Add-In auf einer lokalen SharePoint-Website installiert haben und feststellen, dass es nicht funktioniert, sich nicht beschweren.

Es gibt zwei Möglichkeiten, die Funktion zu aktivieren. Die erste besteht darin, das folgende PowerShell-Cmdlet (kann am Ende der vorausgehenden Funktion hinzugefügt werden) auf einem beliebigen SharePoint-Server durchzuführen:

Enable-SPFeature -identity "7877bbf6-30f5-4f58-99d9-a0cc787c1300" -Url http://domain_of_the_SharePoint_web_application

Die andere Methode zum Aktivieren der Funktion besteht darin, folgende Schritte in der Zentraladministration durchzuführen:

Gehen Sie in SharePoint-Zentraladministration zu Anwendungsverwaltung>Webanwendungen verwalten.
Wählen Sie auf der Seite Webanwendungen verwalten die zu ändernde Webanwendung.
Wählen Sie im Menüband Features verwalten aus.
Wählen Sie in der Liste der Features neben Add-Ins, die verfügbare Internet-Endpunkte benötigen die Option Aktivieren aus.
Wählen Sie OK aus.

Konfigurieren weiterer SharePoint-Webanwendungen in der Farm

Wenn sich in Ihrer SharePoint-Farm weitere Webanwendungen befinden und Sie auf diesen vom Anbieter gehostete Add-Ins ausführen möchten, die eine ACS-Vertrauensstellung verwenden, können Sie dieses Windows PowerShell-Skript (in SharePoint-Verwaltungsshell) verwenden, um sie zur Sammlung der Dienstprinzipalnamen hinzuzufügen.

$SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId 00000003-0000-0ff1-ce00-000000000000
$id = "00000003-0000-0ff1-ce00-000000000000/"

Get-SPWebApplication | ForEach-Object {
    $hostName = $_.Url.substring($_.Url.indexof("//") + 2)
    $hostName = $hostName.Remove($hostName.Length - 1, 1)

    $NewSPN = $id + $hostName

    Write-Host "Adding SPN for" $NewSPN

    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
       $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
       Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }
}