Konfigurationsskripts mit hoher Vertrauenswürdigkeit für SharePoint
Die folgenden Skripts werden verwendet, um ein oder mehrere digitale X.509-Zertifikate als vertrauenswürdige Herausgeber eines Zugriffstokens in einer Staging- oder Produktionsfarm in Microsoft SharePoint festzulegen. Ein Skript, das besser für eine Entwicklungsumgebung für SharePoint-Add-Ins geeignet ist, finden Sie unter Erstellen besonders vertrauenswürdiger Add-Ins für SharePoint. Es kann kein einzelner Satz von Skripts für jede SharePoint-Farm verwendet werden, da es zu viele verschiedene Arten gibt, um Zertifikate zu erhalten und speichern. Beachten Sie aus diesem Grund bitte Folgendes:
Die Skripts sind zum Ausführen in einer SharePoint-Verwaltungsshell auf einem SharePoint-Server in der Farm vorgesehen.
Diese Skripts sollten als Entwürfe betrachtet werden, die ggf. angepasst werden müssen.
Sie werden als Teil des gesamten Veröffentlichungsvorgangs einer besonders vertrauenswürdigen SharePoint-Add-In verwendet. Sie sollten nur von jemandem verwendet werden, der mit den Themen Erstellen von Add-Ins für SharePoint, die eine Autorisierung mit hoher Vertrauenswürdigkeit verwenden und Packen und Veröffentlichen besonders vertrauenswürdiger Add-Ins für SharePoint und den darin aufgeführten Voraussetzungen vertraut ist.
Sie sollten von jemandem geprüft und angepasst werden, der mit den Kundenzertifikatsrichtlinien des Add-Ins vertraut ist.
Bei den zwei folgenden Hauptskripts, HighTrustConfig-ForSharedCertificate.ps1 und HighTrustConfig-ForSingleApp.ps1, wird davon ausgegangen, dass der Administrator ein Zertifikat für die Remote-Webanwendungskomponente des Add-Ins oder der Add-Ins abgerufen hat und eine CER-Version des Zertifikats (das nicht den privaten Schlüssel enthält) in einem Ordner gespeichert hat, zu dem die Benutzerkonten für folgende IIS-Anwendungspools auf den SharePoint-Servern Lesezugriff besitzen:
SecurityTokenServiceApplicationPool
Der Add-In-Pool, der der IIS-Website dient, die die übergeordnete SharePoint-Webanwendung für Ihre Test-SharePoint-Website hostet. Für die SharePoint - 80 IIS-Website wird der Pool als OServerPortalAppPool bezeichnet.
Um das Benutzerkonto zu finden, das ein Anwendungspool verwendet, öffnen Sie den IIS-Manager auf einem SharePoint-Server und klicken Sie im Bereich Verbindungen doppelt auf Anwendungspools. Die Spalte Identität in der Liste Anwendungspools zeigt die Benutzer für die Anwendungspools an.
Bei den Anweisungen für die zwei wichtigsten Skripts wird zudem davon ausgegangen, dass die Zertifikate für IIS auf Servern installiert wurden, auf denen die Remote-Webanwendungen gehostet werden. Eine Anleitung finden Sie unter Konfigurieren des Remotewebservers mit dem Zertifikat.
Verwendungshinweise zu den Skripts finden Sie in den folgenden Abschnitten.
AddSPRootAuthority.ps1
Das Zertifikat für die Remote-Webanwendungskomponente des SharePoint-Add-Ins mit hoher Vertrauenswürdigkeit ist entweder bei einer kommerziellen Zertifizierungsstelle (CA) oder eine Domänen-Zertifizierungsstelle erhältlich. In beiden Fällen ist das Zertifikat das unterste Glied in eine Kette von Zertifikaten, die jeweils auf das übergeordnete Zertifikat vertrauen, und es stammt von einer Stammzertifizierungsstelle (kommerziell oder Domäne). SharePoint erfordert, dass alle Zertifikate in der Kette zur SharePoint-Liste der vertrauenswürdigen Stammzertifizierungsstellen hinzugefügt werden.
Das folgende Skript kann verwendet werden, um die Zertifikate der Kette zur Liste hinzufügen, mit Ausnahme des niedrigsten Zertifikats. Das niedrigste Zertifikat der Kette, das Zertifikat, das direkt mit der Remote-Webanwendung verbunden ist, wird in einem der in späteren Abschnitten beschriebenen Hauptskripts zu den Stammzertifizierungsstellen hinzugefügt.
Die Parameter für das Skript lauten wie folgt:
| Parameter | Wert |
|---|---|
-CertPath |
Der vollständige Pfad und der Dateiname des Zertifikats (die CER-Datei). |
-CertName |
Der Name des Zertifikats. Um den Namen zu finden, müssen Sie die Eigenschaften des Zertifikats anzeigen. |
In dem gängigen Szenario, in dem das Zertifikat der Webanwendung von einem Zertifizierungsstellenserver auf mittlerer Ebene (auch als „Enterprise" bezeichnet) ausgestellt wird und das Zertifikat beispielsweise wiederum von einem Stammzertifizierungsserver (auch als „eigenständig" bezeichnet) ausgestellt wird, sollte das Skript je einmal für die Zertifikate und die beiden Zertifizierungsstellenserver ausgeführt werden. Dies wird im folgenden Absatz verdeutlicht:
./AddSPRootAuthority.ps1 -CertPath "\\CertStorage\RootCA.cer" -CertName "Contoso Root CA"
./AddSPRootAuthority.ps1 -CertPath "C:\RegionalCerts\NorthRegion.cer" -CertName "North Region Intermediate CA"
Wenn alle Zertifikate der besonders vertrauenswürdigen SharePoint-Add-Ins des Kunden aus der gleichen Zertifikatskette stammen, wie es in der Regel der Fall wäre, wird dieses Skript nicht erneut verwendet.
Im Folgenden ist der Code für dieses Skript aufgeführt. Fügen Sie ihn einfach in einen Text-Editor oder den PowerShell-Editor (IPowerShell ISE) ein, und speichern Sie ihn als „AddSPRootAuthority.ps1".
Hinweis
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 ausführt. NotePad und der PowerShell-Editor speichern Dateien 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.
param(
[Parameter(Mandatory)][String] $CertName = $(throw "Usage: AddSPRootAuthority.ps1 -CertPath <full path to .cer file> -CertName <name of certificate>"),
[Parameter(Mandatory)][String] $CertPath
)
# Stop if there's an error
$ErrorActionPreference = "Stop"
# Make the certificate a trusted root authority in SharePoint
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
New-SPTrustedRootAuthority -Name $CertName -Certificate $cert
HighTrustConfig-ForSharedCertificate.ps1
Die Hauptaufgaben dieses Skripts bestehen darin, das gemeinsam genutzte Zertifikat der Remote-Webanwendungskomponenten in mehreren SharePoint-Add-Ins mit hoher Vertrauenswürdigkeit mit SharePoint als Stammzertifizierungsstelle und als vertrauenswürdiger Zugriffstoken-Herausgeber zu registrieren. Dieses Skript wird nicht verwendet, wenn der Kunde separate Zertifikate für jede besonders vertrauenswürdige SharePoint-Add-In verwendet. Informationen zu diesem Szenario finden Sie unterHighTrustConfig-ForSingleApp.ps1. Wenn alle Add-Ins das gleiche Zertifikat verwenden, wird dieses Skript nur einmal ausgeführt. Wenn einige Add-In-Sätze ein anderes Zertifikat als andere Sätze verwenden, wird das Skript einmal für jeden Satz ausgeführt.
In der folgenden Tabelle werden die Parameter und Schalter für das Skript erläutert. Durch Anpassungen des Skripts sind möglicherweise Änderungen an dieser Tabelle erforderlich.
| Parameter | Wert |
|---|---|
-CertPath (erforderlich) |
Der vollständige Pfad zur freigegebenen CER-Datei. |
-CertName (erforderlich) |
Der Name des freigegebenen Zertifikats. Um den Namen zu finden, öffnen Sie IIS auf dem Remotewebserver, auf dem die Remote-Webanwendung gehostet wird. Markieren Sie den Knoten Servername, und doppelklicken Sie auf Zertifikate. Das Zertifikat wird nach dem Namen aufgeführt. |
-TokenIssuerFriendlyName(optional) |
Einen eindeutiger benutzerfreundlicher Name für den Token-Herausgeber mit bis zu 50 Zeichen. Dies kann beim Debuggen von Problemen mit Tokenausstellern hilfreich sein. Der Name muss eindeutig sein. Das Einbeziehen einer GUID würde dies gewährleisten, aber eine GUID besteht aus 32 bis 50, konvertieren Sie daher eine GUID in eine Base-64-Zeichenfolge, die auf 22 Zeichen reduziert werden kann. Wenn dieser Parameter nicht verwendet wird, verwendet das Skript den Namen High-Trust Add-ins <base64 version of issuer GUID>. |
Im Folgenden finden Sie ein Beispiel zum Ausführen dieses Skripts.
./HighTrustConfig-ForSharedCertificate.ps1 -CertPath "C:\Certs\MyCert.cer" -CertName "My Cert" -TokenIssuerFriendlyName "SharePoint High-Trust Add-ins Token Issuer"
Wichtig
Die Registrierung des Zertifikats als Tokenaussteller wird nicht sofort wirksam. Es kann bis zu 24 Stunden dauern, bis alle SharePoint-Server den neuen Tokenherausgeber erkennen. Das Ausführen eines iisreset auf allen SharePoint-Servern würde dazu führen, dass der Aussteller sofort erkannt wird, wenn Sie dies tun können, ohne SharePoint-Benutzer zu stören.
Beginnen Sie eine neue Datei in einem Text-Editor oder dem PowerShell-Editor und kopieren Sie das Folgende in eine Textdatei und speichern Sie sie als HighTrustConfig-ForSharedCertificate.ps1. Verwenden Sie dazu das ANSI-Format, nicht UTF-8.
param(
[Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
[Parameter(Mandatory)][String] $CertName,
[Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"
# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}
# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate
# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm
# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()
# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm
# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
$tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
$tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}
# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId | Out-File -FilePath "SecureTokenIssuerID.txt"
Tipp
Wenn das Skript einen Fehler auslöst, nachdem die Zeile New-SPTrustedRootAuthority erfolgreich ausgeführt wurde, kann das Skript erst wieder ausgeführt werden, nachdem das Objekt entfernt wurde. Verwenden Sie das folgende Cmdlet, in dem den Wert des Parameters -Identity dem entspricht, der für den Parameter -CertName im Skript verwendet wurde: Remove-SPTrustedRootAuthority -Identity <certificate name>
Wenn der Token-Herausgeber entfernt werden muss, verwenden Sie folgendes Cmdlet: Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>
Wenn der -TokenIssuerFriendlyName-Parameter verwendet wurde, verwenden Sie denselben Wert für -Identity.
Wenn der -TokenIssuerFriendlyName-Parameter nicht verwendet wurde, ist eine zufällige GUID Bestandteil des Namens des Herausgebers. Zum Abrufen des Werts für -Identity führen Sie das folgende Cmdlet aus. Öffnen Sie die Datei TokenIssuers.txt, die erstellt wird, und suchen Sie den Herausgeber namens High-Trust Add-ins <base64 version of issuer GUID>. Verwenden Sie den ganzen Namen für -Identity.
Get-SPTrustedSecurityTokenIssuer | Out-File -FilePath "TokenIssuers.txt"
HighTrustConfig-ForSingleApp.ps1
Die Hauptaufgaben dieses Skripts bestehen darin, das Zertifikat der Remote-Webanwendung in einer SharePoint-Add-In mit hoher Vertrauenswürdigkeit mit SharePoint als Stammzertifizierungsstelle und als vertrauenswürdiger Zugriffstoken-Herausgeber zu registrieren. Dieses Skript wird nicht verwendet, wenn der Kunde ein einzelnes Zertifikat für mehrere SharePoint-Add-Ins verwendet. Dieses Szenario finden Sie unter HighTrustConfig-ForSharedCertificate.ps1. Dieses Skript wird für jede SharePoint-Add-In mit hoher Vertrauenswürdigkeit ausgeführt.
In der folgenden Tabelle werden die Parameter und Schalter für das Skript erläutert. Durch Anpassungen des Skripts sind möglicherweise Änderungen an dieser Tabelle erforderlich.
| Parameter | Wert |
|---|---|
-CertPath (erforderlich) |
Der vollständige Pfad zur freigegebenen CER-Datei. |
-CertName (erforderlich) |
Der Name des freigegebenen Zertifikats. Um den Namen zu finden, öffnen Sie IIS auf dem Remotewebserver, auf dem die Remote-Webanwendung gehostet wird. Markieren Sie den Knoten Servername, und doppelklicken Sie auf Zertifikate. Das Zertifikat wird nach dem Namen aufgeführt. |
-SPAppClientID (erforderlich) |
Die Client-ID (eine GUID), die beim Registrieren der SharePoint-Add-In auf appregnew.aspx verwendet wurde. Wird als Herausgeber-ID für den Token-Herausgeber verwendet. Das Skript stellt sicher, dass Kleinbuchstaben verwendet werden, was eine Voraussetzung für Herausgeber-IDs ist. |
-TokenIssuerFriendlyName(optional) |
Einen eindeutiger benutzerfreundlicher Name für den Token-Herausgeber mit bis zu 50 Zeichen. Dies kann beim Debuggen von Problemen mit Tokenausstellern hilfreich sein. Der Name muss eindeutig sein. Ziehen Sie in Betracht, den Namen des SharePoint-Add-Ins zu verwenden. Wenn dieser Parameter nicht verwendet wird, verwendet das den Wert von -SPAppClientID als Namen. |
Im Folgenden finden Sie ein Beispiel zum Aufrufen des Skripts:
./HighTrustConfig-ForSingleApp.ps1 -CertPath "\\MyServer\Certs\MyCert.cer" -CertName "My Cert" -SPAppClientID "afe332f4-1f87-4c31-89b8-9c343ad7f24e" -TokenIssuerFriendlyName "Payroll add-in"
Wichtig
Die Registrierung des Zertifikats als Tokenaussteller wird nicht sofort wirksam. Es kann bis zu 24 Stunden dauern, bis alle SharePoint-Server den neuen Tokenaussteller erkannt haben. Durch Ausführen von "iisreset" auf allen SharePoint-Servern wird der Aussteller sofort erkannt, wenn dies möglich ist, ohne die SharePoint-Benutzer zu stören.
Beginnen Sie eine neue Datei in einem Text-Editor oder dem PowerShell-Editor und kopieren Sie das Folgende in eine Textdatei und speichern Sie sie als HighTrustConfig-ForSingleApp.ps1. Verwenden Sie dazu das ANSI-Format, nicht UTF-8.
param(
[Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSingleApp.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-SPAppClientID <client ID of SharePoint add-in>] [-TokenIssuerFriendlyName <friendly name>]"),
[Parameter(Mandatory)][String] $CertName,
[Parameter(Mandatory)][String] $SPAppClientID,
[Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"
# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}
# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate
# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm
# Must use the client ID as the specific issuer ID. Must be lower-case!
$specificIssuerId = New-Object System.String($SPAppClientID).ToLower()
# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm
# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
$tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
$tokenIssuerName = $specificIssuerId
}
# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier
Tipp
Die Tipps am Ende des vorherigen Abschnitts gelten auch hier, verwenden Sie jedoch für den Parameter -Identity des Cmdlets Remove-SPTrustedSecurityTokenIssuer die Client-ID, wenn der Parameter -TokenIssuerFriendlyName nicht mit HighTrustConfig-ForSingleApp.ps1. verwendet wurde.
Erforderliche Änderungen für Website-Abonnements
Ein Websiteabonnement, manchmal auch Mandant genannt, ist eine Teilmenge der Websitesammlungen auf einer SharePoint-Farm. Websiteabonnements werden in der Regel auf gehosteten SharePoint-Farmen erstellt. Wenn der Kunde der SharePoint-Add-In mit hoher Vertrauenswürdigkeit das Add-In in einer Farm installieren möchte, die für Websiteabonnements konfiguriert wurde, muss das verwendete HighTrustConfig-*.ps1-Skript geändert werden.
Jedes Websiteabonnement verfügt über eine eigene Bereichs-ID, aber die Zeile $realm = Get-SPAuthenticationRealm in den Skripts gibt immer den Bereich der Farm zurück. Die von einem Token-Herausgeber ausgestellten Zugriffstoken werden von SharePoint nur als gültig für den Bereich betrachtet, der nach dem "@"-Zeichen in der vollständigen Herausgeber-ID angegeben ist.
Um den richtigen Bereich für die Website zu erhalten, in dem das Add-In installiert werden soll, muss das Skript den -ServiceContext-Parameter im Aufruf an Get-SPAuthenticationRealm verwenden. Das Dienstkontextobjekt wird hingegen von der übergeordneten Websitesammlung der Zielwebsite erstellt.
Im folgenden Beispiel ist $WebURL eine Zeichenfolgenvariable, die die vollständige URL einer SharePoint-Website enthält, z. B. http://marketing.contoso.com/sites/northteam/july. Mit diesem Code kann das Add-In mit hoher Vertrauenswürdigkeit nicht nur auf der angegebene Website, sondern auf jeder Website innerhalb des gleichen Websiteabonnements ausgeführt werden.
$Web = Get-SPWeb $WebURL
$sc = Get-SPServiceContext -Site $Web.Site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc
Um die Änderung des Skripts abzuschließen, fügen Sie oben in der Datei einen zusätzlichen erforderlichen Parameter $WebURL wie folgt zur Parameterliste hinzu:
param (
# other parameters omitted
[Parameter()][String] $WebURL
)
Achten Sie darauf, nach dem Parameter ein Komma zu setzen, der vor dem neuen steht. Und erweitern Sie das Verwendungsbeispiel in der oberen Zeile, um den neuen Parameter folgendermaßen zu berücksichtigen:
-WebURL <full URL where SP add-in will be installed>
Damit die SharePoint-Add-In bei jedem Websiteabonnement vertrauenswürdig ist, müssen Sie mit dem Get-SPFarm-Cmdlet einen Verweis zur Farm abrufen, und anschließend die SiteSubscriptions-Eigenschaft durchlaufen. Übergeben Sie jedes SPSiteSubscription-Objekt als Wert des Get-SPServiceContext-Parameters an das -SiteSubscription-Cmdlet. Es folgt ein Beispiel.
$Farm = Get-SPFarm
foreach ($ss in $Farm.SiteSubscriptions)
{
$sc = Get-SPServiceContext -SiteSubscription $ss
$realm = Get-SPAuthenticationRealm -ServiceContext $sc
# All of the lines from the draft script below the call to
# Get-SPAuthenticationRealm are inserted here inside the loop.
}
# end of script