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 complément SharePoint à haut niveau de fiabilité est essentiellement destiné à une utilisation dans un environnement local. Le complément à haut niveau de fiabilité ne peut pas être installé sur Microsoft SharePoint Online et les composants à distance sont généralement installés en local également, au sein du pare-feu d’entreprise. Par conséquent, les instances du complément SharePoint sont spécifiques à chaque entreprise individuelle.

Un complément à haut niveau de fiabilité utilise un certificat à la place d’un jeton de contexte pour établir une approbation. (Un complément hébergé par un fournisseur qui est conçu pour utiliser Microsoft Azure Access Control Service (ACS) comme son répartiteur d’approbation doit être modifié pour fonctionner comme une application à haut niveau de fiabilité.) Cette rubrique décrit les étapes de configuration nécessaires pour faire fonctionner le débogage vsnv (F5).

Dans SharePoint, le service d’émission de jeton de sécurité (STS) de serveur à serveur fournit des jetons d’accès pour l’authentification de serveur à serveur. Le STS de serveur à serveur permet aux jetons d’accès temporaires d’accéder à d’autres services d’application, comme Exchange, Lync et les compléments pour SharePoint. Vous établissez une relation d’approbation entre les services d’application (par exemple, en établissant une approbation entre SharePoint et un complément à distance) à l’aide des cmdlets Windows PowerShell et d’un certificat.

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 :

• Un environnement de développement SharePoint en local. Voir Configurer un environnement de développement local pour les compléments SharePoint pour connaître les instructions de configuration. Assurez-vous notamment que vous avez effectué les étapes décrites dans la section Configurer les services de SharePoint en vue d’une utilisation des compléments de serveur à serveur.

• Expérimentez la création d’un complément SharePoint hébergé par un fournisseur. Consultez l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint.

• Visual Studio installé à distance ou sur l’ordinateur sur lequel vous avez installé SharePoint.

• Outils de développement Microsoft Office pour Visual Studio.

• Connaissance des certificats numériques (leur définition et leur mode d’utilisation). Voir l’article relatif aux

  • Certificats numériques
  • Utilisation des certificats

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 à distance de votre complément à haut niveau de fiabilité. Pour tester totalement votre complément SharePoint, vous avez besoin d’un certificat émis par un 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 créer un fichier de certificat .pfx de test, puis un fichier .cer de test correspondant. Le certificat .pfx contient la clé privée utilisée par l’application web à distance pour signer ses communications vers SharePoint. Le fichier .cer contient la clé publique que SharePoint utilise pour déchiffrer les messages, vérifier qu’ils proviennent de l’application web à distance et vérifier que l’application web à distance dispose d’un jeton d’accès émis par un émetteur de jetons approuvé par SharePoint. Pour plus d’informations sur les fichiers .pfx et .cer, consultez la rubrique Software Publisher Certificate.

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.

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

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

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

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

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

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

8. Si votre installation SharePoint de test n’est pas sur le même ordinateur que celui où Visual Studio est en cours d’exécution, créez un dossier C:\Certs sur l’ordinateur Visual Studio et déplacez-y le fichier HighTrustSampleCert.pfx. 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.

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

3. Double-cliquez sur Certificats de serveur.

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

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

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

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

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

9. Sélectionnez Suivant.

10. Sélectionnez Terminer.

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

Le script Windows PowerShell que vous créez dans cette section est conçu pour prendre en charge l’utilisation de F5 dans Visual Studio. Il ne configure pas correctement une installation SharePoint intermédiaire ou de production. Pour obtenir des instructions sur la configuration d’un SharePoint de production pour utiliser des certificats, consultez la rubrique Empaquetage et publication de compléments SharePoint à haut niveau de fiabilité.

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)

2. Ajoutez la ligne suivante pour vous assurer que SharePoint traite le certificat comme une autorité racine.

  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate 

3. Ajoutez la ligne suivante pour obtenir l’ID du domaine d’autorisation.

  $realm = Get-SPAuthenticationRealm

4. 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 construire un ID d’émetteur au format requis par SharePoint : _specific_issuer_GUID_@_realm_GUID_.

  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm 

5. Ajoutez les lignes suivantes pour enregistrer le certificat comme un émetteur de jetons approuvé. Le paramètre -Name doit être unique de telle sorte que, dans une configuration de production, il soit courant d’utiliser un GUID comme tout ou partie du nom, mais dans ce contexte, vous pouvez utiliser un nom convivial. Le commutateur -IsTrustBroker est nécessaire pour vous assurer que vous pouvez utiliser le même certificat pour tous les compléments à haut niveau de fiabilité que vous développez. La commande iisreset est requise pour enregistrer immédiatement votre émetteur de jetons. Sans cela, vous devrez peut-être patienter 24 heures pour que le nouvel émetteur soit inscrit.

  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset 

6. 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()

7. Enregistrez le fichier avec le nom HighTrustConfig-ForDebugOnly.ps1.

8. 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.

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. Spécifiez l’URL complète du site du développeur 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. Saisissez le mot de passe de ce certificat dans la zone Mot de passe. Dans le cas présent, c’est password.

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. Les Outils de développement Office pour Visual Studio génèrent automatiquement des fichiers default.aspx et default.aspx.cs lorsque le projet ASP.NET est créé. Le code généré extrait le titre du site web hôte SharePoint et l’imprime sur la page par défaut de l’application web à distance. La marque de révision et le code exacts dans ces fichiers varie selon 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.

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 y ajouter un mot de passe, s’il n’en a pas encore. Dans un environnement de production, vous utiliseriez un mot de passe fort, mais pour le débogage d’un complément SharePoint, vous pouvez utiliser n’importe quel mot de passe. 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 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. Pour les besoins de cet article, nous supposons que le fichier est nommé « MyCert.pfx ». Vous devez remplacer « MonCert » dans toutes les 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 n’est pas sur le même ordinateur que celui où Visual Studio est en cours d’exécution, déplacez le fichier MyCert.pfx vers le dossier C:\Certs sur l’ordinateur 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.

2. Enregistrez le fichier.

3. 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.

2. 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 ?

Les Outils de développement Office pour Visual Studio comprennent un fichier TokenHelper.cs (ou .vb) dans l’application web à distance. 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 complément 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 qu’ils utilisent un système d’authentification différent. Vous devrez également personnaliser ces fichiers si votre application web à distance accède à SharePoint avec une identité autre que celle de l’utilisateur qui exécute le complément SharePoint. Enfin, si l’application web à distance est PHP, node.js, Java ou certaines autres plates-formes non-ASP.NET, votre code doit obtenir l’ID d’utilisateur auprès du système d’authentification utilisé et ajouter cet ID dans le jeton d’accès qu’il crée.

Voir aussi

• Conseils supplémentaires pour dépanner les compléments à haut niveau de fiabilité sur SharePoint
• Utilisation des compléments SharePoint avec des sites SAML et FBA dans SharePoint
• L’assistance SharePointContext dans les compléments pour SharePoint 2013
• Créer et utiliser des jetons d’accès dans des compléments SharePoint à haut niveau de fiabilité hébergés par un fournisseur
• Enregistrement des compléments SharePoint
• Création de compléments pour SharePoint qui utilisent l’autorisation à haut niveau de fiabilité
• Autorisation et authentification des compléments dans SharePoint