Création de compléments SharePoint à haut niveau de fiabilité

Un complément à haut niveau de fiabilité est un complément SharePoint hébergé par un fournisseur qui utilise des certificats numériques pour établir une approbation entre l’application web à distance et SharePoint. Le « haut niveau de fiabilité » n’est pas la « confiance totale ». Un complément à haut niveau de fiabilité doit toujours demander des autorisations de complément. Le complément est considéré comme ayant un « haut niveau de fiabilité » car il est habilité à utiliser toute identité d’utilisateur dont le complément a besoin, parce que le complément est chargé de la création de la partie utilisateur du jeton d’accès qui transite vers SharePoint.

Un module complémentaire SharePoint de confiance élevée est principalement destiné à être utilisé dans un environnement sur site. Le module complémentaire à niveau de confiance élevé ne peut pas être installé sur Microsoft SharePoint Online et les composants distants sont généralement installés sur place, à l'intérieur du pare-feu de l'entreprise. Ainsi, les instances du complément SharePoint sont spécifiques à chaque entreprise.

(Un complément hébergé par un fournisseur et conçu pour utiliser Microsoft Azure Access Control Service (ACS) car son courtier d’approbation doit être modifié pour fonctionner comme une application à haut niveau de fiabilité.) Les compléments à haut niveau de fiabilité nécessitent une configuration sur la batterie de serveurs SharePoint et sur le serveur qui héberge l’application web à distance.

Dans SharePoint, le service de jeton de sécurité serveur-à-serveur (STS) fournit des jetons d'accès pour l'authentification serveur-à-serveur. Le STS permet d'utiliser des jetons d'accès temporaires pour accéder à d'autres services d'application tels que Exchange, Lync et des modules complémentaires pour SharePoint. Vous établissez une relation de confiance entre les services d'application (par exemple, établir la confiance entre SharePoint et un add-in distant) à l'aide des cmdlets Windows PowerShell et d'un certificat.

Notes

Le STST de serveur à serveur n’est pas destiné à l’authentification des utilisateurs. Par conséquent, le STS de serveur à serveur ne figure pas dans la page de connexion de l’utilisateur, dans la section Fournisseur d’authentification de l’Administration centrale ou dans le Sélecteur de personnes de SharePoint.

Cet article montre comment créer un complément à haut niveau de fiabilité et fournit des instructions de configuration pour l’exécuter dans Visual Studio en sélectionnant F5. Vous allez apprendre à :

  • configurer un complément à utiliser en tant que complément à haut niveau de fiabilité ;
  • configurer SharePoint pour utiliser des compléments à haut niveau de fiabilité ;
  • créer un complément à haut niveau de fiabilité de base ;

La configuration d’un environnement de test, intermédiaire ou de production est légèrement différente et est décrite dans la rubrique Empaquetage et publication de compléments SharePoint à haut niveau de fiabilité.

Conditions préalables

Pour suivre les procédures décrites dans cet article, veillez à disposer des éléments suivants :

obtenir un certificat ou créer un certificat de test public et privé.

Vous avez besoin d'un certificat numérique X.509 pour l'application Web distante de votre module complémentaire de confiance. Pour tester complètement votre complément SharePoint, vous avez besoin d'un certificat émis par le domaine ou d'un certificat commercial émis par une autorité de certification. Toutefois, pour la phase initiale de débogage, vous pouvez utiliser un certificat auto-signé.

La procédure suivante explique comment créer et exporter un certificat de test à l’aide d’IIS. Vous découvrirez comment remplacer le certificat auto-signé avec un certificat émis par un domaine ou un certificat commercial dans la section Terminer le débogage avec un certificat émis par un domaine ou un certificat commercial plus loin.

Vous pouvez également utiliser le programme de test MakeCert pour générer un certificat X.509. Pour plus d’informations sur l’utilisation de MakeCert, consultez l’article sur la signature et la vérification d’un code avec Authenticode.

Vous allez d'abord créer un fichier de certificat .pfx de test, puis un fichier .cer de test correspondant. Le certificat .pfx contient la clé privée qui est utilisée par l'application Web distante pour signer ses communications avec SharePoint. Le fichier .cer contient la clé publique que SharePoint utilise pour décrypter les messages, vérifier qu'ils proviennent de l'application Web distante et que l'application Web distante possède un jeton d'accès provenant d'un émetteur de jetons auquel SharePoint fait confiance. Pour plus d'informations sur les fichiers .pfx et .cer, voir Certificat d'éditeur de logiciel.

Pour créer un fichier de certificat PFX de test auto-signé, procédez comme suit :

  1. Lorsque vous déboguez un complément SharePoint à haut niveau de fiabilité dans Visual Studio, l’application web à distance est hébergée dans IIS Express sur l’ordinateur où est installé Visual Studio. Par conséquent, l’ordinateur de l’application web à distance ne possède pas de Gestionnaire IIS où vous pouvez créer le certificat. C’est pour cela que vous utilisez IIS sur le serveur de test SharePoint pour créer le certificat.

Dans le Gestionnaire IIS, sélectionnez le nœud ServerName dans l’arborescence sur la gauche.

  1. Sélectionnez l’icône Certificats de serveur, comme illustré dans la figure suivante.

Option Certificats de serveur dans IIS

  1. Sélectionnez le lien Créer un certificat auto-signé dans le jeu de liens sur la droite.

Lien Créer un certificat auto-signé

  1. Nommez le certificat HighTrustSampleCert, puis sélectionnez OK.

  2. Cliquez avec le bouton droit de la souris sur le certificat, puis sélectionnez Exporter.

Exportation d’un certificat de test

  1. Dans Windows, ou au niveau d’une ligne de commande, créez un dossier nommé C:\Certs.

  2. De retour dans IIS Manager, exportez le fichier vers C:\Certs et donnez-lui un mot de passe. Dans cet exemple, le mot de passe est password.

  3. Si votre installation SharePoint de test ne se trouve pas sur l’ordinateur exécutant Visual Studio, créez un dossier C:\Certs sur l’ordinateur exécutant Visual Studio, puis déplacez le fichier HighTrustSampleCert.pfx vers ce dernier. Il s’agit de l’ordinateur sur lequel s’exécute l’application web à distance lorsque vous effectuez un débogage dans Visual Studio.

Pour créer un fichier .cer correspondant, procédez comme suit :

  1. Sur le serveur SharePoint, vérifiez que l’identité du pool de compléments pour les pools de compléments IIS suivants dispose des droits de lecture sur le dossier C:\Certs :
  • 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.

  1. Dans le Gestionnaire des services Internet, sélectionnez le nœud ServerName dans l’arborescence sur la gauche.

  2. Double-cliquez sur Certificats de serveur.

  3. Dans l’affichage Certificats de serveur, double-cliquez sur HighTrustSampleCert pour afficher les détails des certificats.

  4. Dans l’onglet Détails, sélectionnez Copier dans un fichier pour lancer l’Assistant Exportation du certificat, puis sélectionnez Suivant.

  5. Utilisez la valeur par défaut Non, ne pas exporter la clé privée, puis sélectionnez Suivant.

  6. Utilisez les valeurs par défaut, puis sélectionnez Suivant.

  7. Sélectionnez Parcourir, accédez à C:\Certs, nommez le certificat HighTrustSampleCert, puis sélectionnez Enregistrer. Le certificat est enregistré sous forme de fichier .cer.

  8. Sélectionnez Suivant.

  9. Sélectionnez Terminer.

Configurer SharePoint en vue de l’utilisation de certificats et configurer le niveau d’approbation pour votre complément

Le scénario Windows PowerShell que vous créez dans cette section est destiné à prendre en charge l'utilisation de F5 dans Visual Studio. Il ne permettra pas de configurer correctement une installation SharePoint de mise à disposition ou de production. Pour obtenir des instructions sur la configuration d'une installation SharePoint de production afin d'utiliser des certificats, consultez la section Package et publication de modules complémentaires SharePoint de confiance.

Important

Assurez-vous que vous avez suivi la procédure décrite dans la rubrique Configurer les services de SharePoint en vue d’une utilisation des compléments de serveur à serveur (ce qui constitue une condition préalable pour cet article). Si ce n’est pas le cas, vous devez effectuer cette configuration maintenant, avant de continuer.

Pour configurer SharePoint, procédez comme suit :

  1. Dans un éditeur de texte ou dans l’éditeur Windows PowerShell, créez un fichier et ajoutez-y les lignes suivantes pour créer un objet certificat :
  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
  1. Ajoutez la ligne suivante pour vous assurer que SharePoint traite le certificat comme une autorité racine.
  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate 
  1. Ajoutez la ligne suivante pour obtenir l’ID du domaine d’autorisation.
  $realm = Get-SPAuthenticationRealm
  1. Votre application web à distance utilise un jeton d’accès pour accéder aux données SharePoint. Le jeton d’accès doit être émis par un émetteur de jetons approuvé par SharePoint. Dans un complément SharePoint à haut niveau de fiabilité, le certificat est l’émetteur du jeton. Ajoutez les lignes suivantes pour créer un ID d’émetteur dans un format requis par SharePoint : _GUID_émetteur_spécifique_@_GUID_domaine_.
  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm 

Notes

La valeur $specificIssuerId doit être un GUID car, dans un environnement de production, chaque certificat doit avoir un émetteur unique. Toutefois, dans ce contexte, où vous utilisez le même certificat pour déboguer tous vos compléments à haut niveau de fiabilité, vous pouvez coder en dur la valeur. Si, pour une raison donnée, vous utilisez un GUID différent de celui utilisé ici, assurez-vous que les lettres dans le GUID sont en minuscules. L’infrastructure de SharePoint nécessite actuellement des minuscules pour les GUID d’émetteur du certificat.

  1. Ajoutez les lignes suivantes pour enregistrer le certificat en tant qu'émetteur de jetons de confiance. Le -Nameparamètre doit être unique, donc dans une configuration de production, il est courant d'utiliser un GUID comme partie (ou tout) du nom, mais dans ce contexte, vous pouvez utiliser un nom amical. Le -IsTrustBrokercommutateur est nécessaire pour garantir que vous pouvez utiliser le même certificat pour tous les compléments de haute confiance que vous développez. iisresetLa commande est nécessaire pour que votre émetteur de jetons soit enregistré immédiatement. Sans elle, vous devrez peut-être attendre jusqu'à 24 heures pour que le nouvel émetteur soit enregistré.
  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset 
  1. Normalement, SharePoint n’accepte pas les certificats auto-signés. Par conséquent, lorsque vous utilisez un certificat auto-signé pour le débogage, ajoutez les lignes suivantes pour désactiver l’exigence normale de SharePoint selon laquelle HTTPS doit être utilisé lorsque les applications web à distance appellent SharePoint. Dans le cas contraire, vous obtenez un message 403 (interdit) lorsque l’application web à distance appelle SharePoint à l’aide d’un certificat auto-signé. Vous annulerez cette étape lors d’une procédure décrite plus loin. Désactiver l’exigence HTTPS signifie que les demandes provenant de l’application web à distance vers SharePoint ne sont pas chiffrées, mais que le certificat est toujours utilisé comme émetteur approuvé de jetons d’accès, ce qui constitue son principal objectif dans les compléments à haut niveau de fiabilité.
  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()
  1. Enregistrez le fichier avec le nom HighTrustConfig-ForDebugOnly.ps1.

  2. Ouvrez SharePoint Management Shell en tant qu’administrateur, puis exécutez le fichier avec la ligne suivante :

  ./HighTrustConfig-ForDebugOnly.ps1

Pour créer un complément SharePoint à haut niveau de fiabilité, procédez comme suit :

Dans cette section, vous allez créer un complément SharePoint à haut niveau de fiabilité à l’aide de Visual Studio.

Notes

Comme indiqué dans la section Conditions préalables requises pour créer des compléments à haut niveau de fiabilité, cet article suppose que vous savez comment créer un complément SharePoint hébergé par un fournisseur. Pour plus d’informations, consultez la rubrique Commencer à créer des compléments hébergés par un fournisseur pour SharePoint.

Pour créer un complément SharePoint à haut niveau de fiabilité

  1. Dans Visual Studio, sélectionnez Fichier > Nouveau > Projet.

  2. Dans l’Assistant Nouveau projet, développez le nœud Visual C# ou Visual Basic, puis développez le nœud Office/SharePoint.

  3. Sélectionnez Compléments, puis optez pour la création d’un projet de Complément pour SharePoint.

  4. Nommez le projet HighTrustSampleApp.

  5. Enregistrez le projet à l’emplacement choisi, puis sélectionnez OK.

  6. Indiquez l'URL complète du site de développement SharePoint. Par exemple,http://TestServer/sites/devsite/.

  7. Sélectionnez l’option Hébergement par le fournisseur, puis sélectionnez Suivant.

  8. Si vous êtes invité à spécifier le type de projet web, sélectionnez Application Web Forms ASP.NET pour l’exemple de cette rubrique, puis sélectionnez Suivant.

  9. La page Configurer les paramètres d’authentification de l’assistant s’ouvre. Les valeurs que vous ajoutez à ce formulaire sont ajoutées automatiquement au fichier web.config. Sous Comment souhaitez-vous procéder pour l’authentification de votre complément ?, sélectionnez Utiliser un certificat.

  10. Cliquez sur Parcourir en regard de la zone Emplacement du certificat et accédez à l’emplacement du certificat auto-signé (fichier .pfx) que vous avez créé (C:\Certs). La valeur de ce champ doit reprendre le chemin d’accès complet C:\Certs\HighTrustSampleCert.pfx.

  11. Tapez le mot de passe de ce certificat dans la case Password. Dans ce cas, c'est le mot de passe.

  12. Saisissez l’ID de l’émetteur (11111111-1111-1111-1111-111111111111) dans la zone ID d’émetteur.

  13. Sélectionnez Terminer. L’essentiel de la configuration a lieu lors de l’ouverture de la solution. Deux projets sont créés dans la solution Visual Studio, un pour le complément SharePoint et un autre pour l’application web ASP.NET.

Pour exécuter et déboguer le complément, procédez comme suit :

  1. Outils Office Developer pour Visual Studio génère automatiquement un fichier default.aspx et default.aspx.cs lors de la création du projet ASP.NET. Le code généré récupère le titre du site Web hôte SharePoint et l'imprime sur la page par défaut de l'application Web distante. Le balisage et le code exacts de ces fichiers varient en fonction de la version des outils. Pour cette rubrique, vous utilisez les fichiers default.aspx et default.aspx.cs générés sans modification.

  2. Pour tester le complément SharePoint et son application web à distance, sélectionnez F5 dans Visual Studio. L’application web se déploie vers IIS Express à localhost. Le complément SharePoint est installé sur le site web SharePoint cible. Vous êtes invité par SharePoint à accorder les autorisations demandées par le complément SharePoint. Certaines versions des outils de développement Office pour Visual Studio lancent le complément immédiatement ; d’autres ouvrent la page Contenu du site de votre site web SharePoint cible et vous visualisez le nouveau complément répertorié ici.

Lancez le complément, s’il ne s’est pas lancé automatiquement. L’application web à distance s’ouvre sur la page spécifiée comme Page de démarrage dans le fichier AppManifest.xml, soit Default.aspx. Votre complément doit ressembler à l’illustration suivante.

Exemple d’application récupérant le titre web

Terminer le débogage avec un domaine émis ou un certificat commercial

Le script Windows PowerShell que vous avez créé précédemment a permis de contourner l'exigence habituelle de SharePoint selon laquelle les applications web à distance doivent utiliser le protocole HTTPS pour accéder à SharePoint. La désactivation du protocole HTTPS peut avoir pour effet qu'en tant que développeur, vous ne détectiez pas certains problèmes relatifs à la création d'un complément, susceptibles de se produire lors d'un déploiement de production où le protocole HTTPS est requis. Par conséquent, vous ne devez pas considérer que les phases de développement et de débogage sont terminées tant que vous n'aurez pas remplacé le certificat de test par un certificat commercial ou émis par un domaine, puis testé à nouveau le complément après avoir réactivé l'exigence HTTPS.

Lorsque vous avez obtenu le nouveau certificat, vous devez lui ajouter un mot de passe, s'il n'en a pas déjà un. Dans un environnement de production, vous utiliserez un mot de passe fort, mais pour le débogage d'un module complémentaire SharePoint, vous pouvez utiliser n'importe quoi. Vous avez besoin du certificat dans deux formats, pfx et cer. S'il n'est pas au format pfx lorsque vous l'obtenez, vous devrez peut-être le convertir en pfx à l'aide d'un utilitaire. Lorsque vous avez un fichier pfx, vous pouvez l'importer dans IIS et exporter le fichier cer comme décrit dans la procédure suivante.

Pour importer le nouveau certificat, procédez comme suit :

  1. Placez le fichier .pfx dans C:\Certs sur le serveur SharePoint. Dans le cadre de cet article, nous supposons que le fichier est nommé « MyCert .pfx ». Vous devez remplacer « MyCert » dans toutes ces instructions par le nom réel de votre certificat.

  2. Dans le Gestionnaire IIS, sélectionnez le nœud ServerName dans l’arborescence sur la gauche.

  3. Double-cliquez sur l’icône Certificats de serveur.

  4. Dans le volet Actions sur la droite, sélectionnez Importer.

  5. Dans la boîte de dialogue Importer un certificat, utilisez le bouton de navigation pour accéder au fichier C:\Certs_MonCert_.pfx, puis saisissez le mot de passe du certificat.

  6. Vérifiez que l’option Autoriser l’exportation du certificat est activée, puis sélectionnez OK.

  7. Dans la liste Certificats de serveur, cliquez avec le bouton droit de la souris sur le certificat, puis sélectionnez Exporter.

  8. Exportez le fichier vers C:\Certs et précisez son mot de passe.

  9. Si votre installation SharePoint de test ne se trouve pas sur l’ordinateur exécutant Visual Studio, déplacez le fichier MyCert.pfx vers le dossier C:\Certs sur l’ordinateur exécutant Visual Studio.

  10. Dans l’affichage Certificats de serveur, double-cliquez sur MonCert pour afficher les détails du certificat.

  11. Dans l’onglet Détails, sélectionnez Copier dans un fichier pour lancer l’Assistant Exportation du certificat, puis sélectionnez Suivant.

  12. Utilisez la valeur par défaut Non, ne pas exporter la clé privée, puis sélectionnez Suivant.

  13. Utilisez les valeurs par défaut. Sélectionnez Suivant.

  14. Sélectionnez Parcourir, accédez à C:\Certs, nommez le certificat MonCert, puis sélectionnez Enregistrer. Le certificat est enregistré sous forme de fichier .cer.

  15. Sélectionnez Suivant.

  16. Sélectionnez Terminer.

Pour configurer SharePoint pour l’utilisation du nouveau certificat, procédez comme suit :

  1. Ouvrez le fichier HighTrustConfig-ForDebugOnly.ps1 pour le modifier et apportez les modifications suivantes :
  • Remplacez HighTrustSampleCert aux deux endroits où cela apparaît par MonCert.

  • Remplacez l’ID d’émetteur spécifique 11111111-1111-1111-1111-111111111111 par 22222222-2222-2222-2222-222222222222.

  • Remplacez « High Trust Sample Cert » par « My Cert » ou un autre nom convivial approprié.

  • Dans la ligne $serviceConfig.AllowOAuthOverHttp = $true, remplacez true par false. Cela active à nouveau l’exigence d’utilisation du protocole HTTPS.

  1. Enregistrez le fichier.

  2. Ouvrez SharePoint Management Shell en tant qu’administrateur, puis exécutez le fichier avec la ligne suivante :

  ./HighTrustConfig-ForDebugOnly.ps1

Pour reconfigurer l’application web à distance, procédez comme suit :

  1. Dans Visual Studio, ouvrez le fichier web.config du projet d’application web et apportez les modifications suivantes :
  • Dans la clé ClientSigningCertificatePath, remplacez C:\Certs\HighTrustSampleCert.pfx par C:\Certs\<MyCert>.pfx.

  • Remplacez la valeur de clé ClientSigningCertificatePassword par le mot de passe réel du certificat.

  • Remplacez la valeur de clé IssuerId par 22222222-2222-2222-2222-222222222222.

  1. Sélectionnez F5 pour déboguer le complément.

Une fois le développement de votre complément à haut niveau de fiabilité terminé, consultez l’article Empaquetage et publication de compléments SharePoint à haut niveau de fiabilité pour obtenir des instructions sur la manière d’empaqueter et de publier ce type de complément SharePoint.

Quel est le rôle des fichiers TokenHelper et SharePointContext ?

Outils Office Developer pour Visual Studio inclut un fichier TokenHelper.cs (ou .vb) dans l'application web distante. Certaines versions des outils incluent également un fichier SharePointContext.cs (ou .vb).

Le code contenu dans ces fichiers effectue les actions suivantes :

  • Il configure .NET pour approuver les certificats lors de la réalisation d’appels réseau.

  • Il récupère un jeton d’accès de serveur à serveur signé par le certificat privé de l’application web à distance pour le compte de l’objet WindowsIdentity spécifié et utilisé par SharePoint pour établir une relation de confiance.

  • Il obtient le certificat du service d’émission de jeton de sécurité (STS) SharePoint.

  • Dans les compléments qui utilisent le système d’autorisation à faible niveau de fiabilité au lieu du système d’autorisation à haut niveau de fiabilité, ces fichiers assurent des tâches supplémentaires, telles que la gestion des jetons OAuth dans le cadre du scénario décrit dans l’article Flux OAuth de jeton de contexte pour les compléments SharePoint. Ce scénario dépasse la portée du présent article.

Dans un complément à haut niveau de fiabilité, il n'existe pas de jeton de contexte. Le jeton de contexte est propre aux configurations qui utilisent l'autorisation à faible niveau de fiabilité. Toutefois, un jeton d'accès reste obligatoire. Si vous utilisez une configuration à haut niveau de fiabilité, votre application web doit authentifier l'utilisateur de la même manière que SharePoint (cela signifie que le complément est responsable de la création du jeton d'accès, y compris des ID de l'utilisateur et du fournisseur d'identité).

Lorsque vous effectuez un débogage dans Visual Studio avec F5, les Outils de développement Microsoft Office pour Visual Studio utilisent l’authentification Windows et les deux fichiers de code générés utilisent l’identité Windows de la personne qui exécute le complément pour créer le jeton d’accès. Lorsque votre complément est publié, vous devez configurer l’application web à distance dans le Gestionnaire IIS pour utiliser l’authentification Windows si vous souhaitez utiliser les deux fichiers générés sans modification.

Si votre module complémentaire n'utilise pas l'authentification Windows dans l'environnement de production, vous devez personnaliser les fichiers de code générés, TokenHelper et/ou SharePointContext, pour utiliser un système d'authentification différent. Vous devez également personnaliser ces fichiers si votre application Web distante accède à SharePoint sous une identité autre que celle de l'utilisateur qui exécute le complément SharePoint. Enfin, si l'application Web distante est en PHP, node.js, Java ou une autre plate-forme non ASP.NET, votre code doit obtenir l'ID de l'utilisateur à partir du système d'authentification utilisé, puis ajouter cet ID dans le jeton d'accès qu'il construit.

Voir aussi