Partager via

Scripts de configuration à haut niveau de fiabilité pour SharePoint

  • Article

Les scripts suivants servent à désigner un ou plusieurs certificats numériques X.509 comme émetteurs approuvés de jetons d’accès dans une batterie de serveurs Microsoft SharePoint intermédiaire ou de production. Pour un script plus adapté à un environnement de développement de compléments SharePoint, consultez la rubrique Création de compléments SharePoint à haut niveau de fiabilité. Aucun jeu simple de scripts ne peut fonctionner pour chaque batterie de serveurs SharePoint, car les certificats peuvent être acquis et stockés de trop nombreuses façons différentes. Pour cette raison, veuillez noter ce qui suit :

  • Les scripts sont destinés à être exécutés dans SharePoint Management Shell sur n’importe quel serveur SharePoint de la batterie de serveurs.

  • Ces scripts doivent être considérés comme des brouillons devant être personnalisés.

  • Ils sont utilisés dans le cadre du processus global de publication d’un complément SharePoint à haut niveau de fiabilité. Ils doivent être utilisés uniquement par une personne connaissant les rubriques Création de compléments SharePoint qui utilisent l’autorisation à haut niveau de fiabilité et Empaquetage et publication de compléments SharePoint à haut niveau de fiabilité, ainsi que les conditions préalables qui y sont énumérées.

  • Ils doivent être vérifiés et personnalisés par une personne connaissant les stratégies de certificat du client de complément.

  • Les deux principaux scripts ci-dessous, HighTrustConfig-ForSharedCertificate.ps1 et HighTrustConfig-ForSingleApp.ps1, supposent qu’un administrateur a acquis un certificat pour le composant d’application web à distance du ou des compléments et que cet administrateur a stocké temporairement une version .cer du certificat (qui ne contient pas la clé privée) dans un dossier pour lequel les comptes d’utilisateur des pools d’applications IIS suivants sur les serveurs SharePoint ont un accès en lecture :

    • SecurityTokenServiceApplicationPool

    • Le pool de compléments servant le site web IIS qui héberge l’application web SharePoint parent pour votre site web SharePoint test. Pour le site web IIS SharePoint - 80, le pool s’appelle OServerPortalAppPool.

      Pour déterminer le compte d'utilisateur employé par un pool d'applications, ouvrez le Gestionnaire IIS sur un serveur SharePoint et double-cliquez sur Pools d'applications dans le volet Connexions. La colonne Identité de la liste Pools d'applications affiche les utilisateurs des pools d'applications.

  • Les instructions pour les deux principaux scripts supposent également que les certificats ont été installées pour IIS sur des serveurs hébergeant les applications web à distance. Pour connaître les instructions, consultez la rubrique Configurer le serveur web distant avec le certificat.

Consultez les remarques d’utilisation spécifique de chaque script dans les sections ci-dessous.

AddSPRootAuthority.ps1

Le certificat du composant d’application web à distance du complément SharePoint à haut niveau de fiabilité est obtenu auprès d’une autorité de certification (CA) commerciale ou d’une CA de domaine. Dans les deux cas, ce certificat est le lien le plus faible dans une chaîne de certificats, où chacun se fie à celui qui est au-dessus de lui, qui trouve son origine auprès d’une CA racine (commerciale ou de domaine). SharePoint exige que tous les certificats de la chaîne soient ajoutés à la liste SharePoint des autorités racines de confiance.

Le script suivant peut être utilisé pour ajouter chaque certificat de la chaîne, à l’exception du certificat le plus faible, à la liste. Le certificat le plus faible de la chaîne, le certificat qui dépend directement de l’application web à distance, est ajouté aux autorités racines dans l’un des principaux scripts décrits dans les sections ultérieures.

Les paramètres du script sont les suivants :

Paramètre Valeur
-CertPath Chemin d’accès complet et nom de fichier du certificat (fichier .cer).
-CertName Nom du certificat. Pour connaître le nom, affichez les propriétés du certificat.

Par exemple, si le certificat de l'application web est émis par un serveur d'autorité de certification intermédiaire (également appelé « entreprise ») et que son certificat, à son tour, est émis par un serveur d'autorité de certification racine (également appelé « autonome »), le script doit être exécuté une fois pour chaque certificat des deux serveurs d'autorité de certification. L'exemple suivant illustre cette situation :

./AddSPRootAuthority.ps1 -CertPath "\\CertStorage\RootCA.cer" -CertName "Contoso Root CA"

./AddSPRootAuthority.ps1 -CertPath "C:\RegionalCerts\NorthRegion.cer" -CertName "North Region Intermediate CA"

Si tous les certificats des compléments SharePoint à haut niveau de fiabilité du client proviennent de la même chaîne de certificats, comme c’est généralement le cas, ce script n’est utilisé qu’une seule fois.

Voici le code pour le script. Il vous suffit de le copier dans un éditeur de texte ou dans l’éditeur PowerShell (IPowerShell ISE) et de l’enregistrer sous le nom AddSPRootAuthority.ps1.

Remarque

Le fichier doit être enregistré au format ANSI, et non UTF-8. PowerShell peut donner des erreurs de syntaxe lorsqu’il exécute un fichier dans un format non-ANSI. Le Bloc-notes et l’éditeur PowerShell l’enregistrent par défaut au format ANSI. Si vous utilisez un autre éditeur pour enregistrer le fichier, assurez-vous que vous l’enregistrez au format ANSI.

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

Les tâches principales de ce script visent à enregistrer le certificat partagé des composants d’application web à distance dans plusieurs compléments SharePoint à haut niveau de fiabilité, avec SharePoint à la fois comme autorité racine et comme émetteur de jetons d’accès approuvé. Ce script n'est pas utilisé si le client a recours à des certificats distincts pour chaque Complément SharePoint à haut niveau de fiabilité. Pour ce scénario, consultez HighTrustConfig-ForSingleApp.ps1. Si tous les compléments utilisent le même certificat, ce script n’est exécuté qu’une seule fois. Si certains jeux de compléments utilisent un certificat différent des autres jeux, ce script est exécuté une fois pour chaque jeu.

Le tableau suivant décrit les paramètres et les commutateurs du script. La personnalisation du script peut nécessiter des modifications par rapport à ce tableau.

Paramètre Valeur
-CertPath (obligatoire) Chemin d'accès complet au fichier *.cer partagé.
-CertName (obligatoire) Nom du certificat partagé. Pour trouver le nom, ouvrez IIS sur le serveur web à distance qui héberge l’application web à distance. Mettez en surbrillance le nœud du nom du serveur et double-cliquez sur Certificats. Le certificat est répertorié par son nom.
-TokenIssuerFriendlyName
(facultatif)		 Nom convivial unique pour l’émetteur de jetons, jusqu’à 50 caractères. Cela peut être utile si vous déboguez les problèmes dus à des émetteurs de jetons.

Le nom indiqué doit être unique. L’inclusion d’un GUID garantirait qu’il l’est, mais un GUID utilise jusqu’à 32 des 50 caractères, envisagez donc de convertir un GUID en chaîne de base 64, qui peut être réduite à 22 caractères.

Si ce paramètre n’est pas utilisé, le script utilise le nom High-Trust Add-ins <base64 version of issuer GUID>.

Voici un exemple de l’exécution de ce script.

./HighTrustConfig-ForSharedCertificate.ps1 -CertPath "C:\Certs\MyCert.cer" -CertName "My Cert" -TokenIssuerFriendlyName "SharePoint High-Trust Add-ins Token Issuer"

Importante

L’inscription du certificat en tant qu’émetteur de jeton n’est pas immédiatement effective. 24 heures peuvent s’écouler avant que tous les serveurs SharePoint ne reconnaissent le nouvel émetteur de jeton. L’exécution d’un iisreset sur tous les serveurs SharePoint les amène à reconnaître immédiatement l’émetteur, si vous pouvez le faire sans déranger les utilisateurs SharePoint.

Ouvrez un nouveau fichier dans un éditeur de texte, ou l’éditeur PowerShell, et copiez ce qui suit dans un fichier texte et enregistrez-le sous HighTrustConfig-ForSharedCertificate.ps1. Utilisez le format ANSI, et non 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"

Conseil

Si le script génère une erreur après que la ligne New-SPTrustedRootAuthority a été exécutée correctement, le script ne peut pas être exécuté de nouveau tant que cet objet n’a pas été supprimé. Utilisez la cmdlet suivante, pour laquelle la valeur du paramètre -Identity est identique à celui utilisé pour le paramètre -CertName dans le script : Remove-SPTrustedRootAuthority -Identity <certificate name>

Si l’émetteur de jetons doit être supprimé pour une raison donnée, utilisez la cmdlet suivante : Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>

Si le paramètre -TokenIssuerFriendlyName a été utilisé, utilisez la même valeur pour -Identity.

Si le paramètre -TokenIssuerFriendlyName n’a pas été utilisé, un GUID aléatoire fait partie du nom de l’émetteur. Pour obtenir la valeur nécessaire pour -Identity, exécutez la cmdlet suivante. Ouvrez le fichier TokenIssuers.txt produit et recherchez l’émetteur dont le nom est High-Trust Add-ins <base64 version of issuer GUID>. Utilisez ce nom complet pour -Identity.

Get-SPTrustedSecurityTokenIssuer | Out-File -FilePath "TokenIssuers.txt"

HighTrustConfig-ForSingleApp.ps1

Les tâches principales de ce script visent à enregistrer le certificat de l’application web à distance dans un complément SharePoint à haut niveau de fiabilité, avec SharePoint à la fois comme autorité racine et comme émetteur de jetons d’accès approuvé. Ce script n’est pas utilisé si le client utilise un certificat unique pour plusieurs compléments SharePoint. Pour ce scénario, consultez la rubrique HighTrustConfig- ForSharedCertificate.ps1. Ce script est exécuté pour chaque complément SharePoint à haut niveau de fiabilité.

Le tableau suivant décrit les paramètres et les commutateurs du script. La personnalisation du script peut nécessiter des modifications par rapport à ce tableau.

Paramètre Valeur
-CertPath (obligatoire) Chemin d'accès complet au fichier *.cer partagé.
-CertName (obligatoire) Nom du certificat partagé. Pour trouver le nom, ouvrez IIS sur le serveur web à distance qui héberge l’application web à distance. Mettez en surbrillance le nœud du nom du serveur et double-cliquez sur Certificats. Le certificat est répertorié par son nom.
-SPAppClientID (obligatoire) ID client (GUID) utilisé lors de l'inscription du Complément SharePoint sur appregnew.aspx.
Il est utilisé comme ID de l’émetteur pour l’émetteur de jetons. Le script s’assure qu’il est en minuscules, condition requise pour les ID d’émetteur.
-TokenIssuerFriendlyName
(facultatif)		 Nom convivial unique pour l’émetteur de jetons, jusqu’à 50 caractères. Cela peut être utile si vous déboguez les problèmes dus à des émetteurs de jetons.
Le nom doit être unique. Envisagez d’utiliser le nom du complément SharePoint. Si ce paramètre n’est pas utilisé, le script utilise la valeur de -SPAppClientID comme nom.

Voici un exemple de l’appel de ce script :

./HighTrustConfig-ForSingleApp.ps1 -CertPath "\\MyServer\Certs\MyCert.cer" -CertName "My Cert" -SPAppClientID "afe332f4-1f87-4c31-89b8-9c343ad7f24e" -TokenIssuerFriendlyName "Payroll add-in"

Importante

L’inscription du certificat en tant qu’émetteur de jeton n’est pas immédiatement effective. Cela peut prendre 24 heures pour que tous les serveurs SharePoint reconnaissent le nouvel émetteur de jeton. L'exécution d'une commande IISreset sur tous les serveurs SharePoint permet la reconnaissance immédiate de l'émetteur par tous ces serveurs, si ceci est réalisable sans déranger les utilisateurs SharePoint.

Ouvrez un nouveau fichier dans un éditeur de texte, ou l’éditeur PowerShell, et copiez ce qui suit dans un fichier texte et enregistrez-le sous HighTrustConfig-ForSingleApp.ps1. Utilisez le format ANSI, et non 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

Conseil

Les conseils donnés à la fin de la section précédente s’appliquent également ici, mais pour le paramètre -Identity de la cmdlet Remove-SPTrustedSecurityTokenIssuer, utilisez l’ID client si le paramètre -TokenIssuerFriendlyName n’a pas été utilisé avec HighTrustConfig-ForSingleApp.ps1.

Modifications nécessaires pour les abonnements de site

Un abonnement de site, parfois appelé architecture, est un sous-ensemble des collections de sites sur une batterie de serveurs SharePoint. Les abonnements de site sont généralement créés sur des batteries de serveurs SharePoint hébergées. Si le client du complément SharePoint à haut niveau de fiabilité souhaite installer le complément sur une batterie de serveurs configurée pour les abonnements de site, le script HighTrustConfig-*.ps1 utilisé, quel qu’il soit, doit être modifié.

Chaque abonnement de site possède son propre ID de domaine, mais la ligne $realm = Get-SPAuthenticationRealm dans les scripts renvoie toujours le domaine de la batterie de serveurs. Les jetons d’accès émis par un émetteur de jetons sont considérés par SharePoint comme valables uniquement pour le domaine spécifié après le caractère « @ » dans l’ID d’émetteur complet.

Pour obtenir le domaine correct pour le site web où va être installé le complément, le script doit utiliser le paramètre -ServiceContext dans l’appel vers Get-SPAuthenticationRealm. L’objet de contexte service, en retour, est créé à partir de la collection de sites parent du site web cible.

Voici un exemple où $WebURL est une chaîne de variable avec l’URL complète d’un site web SharePoint, comme http://marketing.contoso.com/sites/northteam/july. Ce code permet l’exécution du complément à haut niveau de fiabilité, non seulement sur le site web spécifié, mais sur tous les sites web au sein du même abonnement de site.

$Web = Get-SPWeb $WebURL
$sc = Get-SPServiceContext -Site $Web.Site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc

Pour terminer la modification du script, ajoutez un paramètre obligatoire supplémentaire $WebURL à la liste des paramètres au début du fichier, comme ceci :

param (
  # other parameters omitted
  [Parameter()][String] $WebURL
)

N’oubliez pas d’ajouter une virgule après le paramètre qui précède le nouveau paramètre. Développez l’exemple « Utilisation » sur la ligne supérieure pour prendre en compte le nouveau paramètre avec quelque chose comme ça :

-WebURL <full URL where SP add-in will be installed>

Pour que le complément SharePoint soit fiable pour chaque abonnement de site, obtenez une référence à la batterie de serveurs avec la cmdlet Get-SPFarm, puis itérez-la dans sa propriété SiteSubscriptions. Passez chaque objet SPSiteSubscription à la cmdlet Get-SPServiceContext en tant que valeur du paramètre -SiteSubscription. Voici un exemple.

$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

Voir aussi