Enregistrement des compléments SharePoint

  • Article

Enregistrer vos compléments SharePoint dans Azure ACS à l’aide de Visual Studio, de Mon tableau de bord vendeur ou d’une page AppRegNew.aspx et récupérer les informations d’inscription.

Importante

Le contrôle d’accès Azure (ACS), un service d’Azure Active Directory (Azure AD), ne sera plus disponible à partir du 7 novembre 2018. Ce retrait n?a aucune incidence sur le mod?le de compl?ments SharePoint, qui utilise lehttps://accounts.accesscontrol.windows.net nom d?h?te (qui n?est pas affect? par ce retrait). Pour plus d’informations, reportez-vous à Conséquences du retrait du contrôle d’accès Azure pour les compléments SharePoint.

Pour que les composants distants d’un complément SharePoint hébergé par un fournisseur interagissent avec SharePoint à l’aide d’OAuth, le complément doit tout d’abord être inscrit auprès du service basé sur le cloud Azure ACS et du service de gestion des applications SharePoint du client ou de la batterie de serveurs. (Il est appelé « service de gestion », car les compléments SharePoint étaient initialement appelés « applications pour SharePoint ».)

Remarque

Cela n’est pas obligatoire pour les compléments hébergés par SharePoint.

Pour inscrire votre complément auprès d’Azure ACS, spécifiez les informations suivantes :

  • Le GUID du complément, appelé ID client.
  • Le mot de passe du complément, appelé clé secrète client.
  • Le nom d'affichage du complément qui apparaît sur la page de consentement lorsque l'utilisateur est invité à approuver le complément.
  • L'URL du domaine dans lequel le complément distant est hébergé.
  • L’URL de redirection.

Une fois que vous avez enregistré votre complément, il possède une identité de complément et est un principal de sécurité, considéré comme un principal de complément. Lorsque vous installez votre complément, les administrateurs SharePoint peuvent récupérer des informations sur ce principal de complément particulier.

Lorsqu’un utilisateur accorde initialement à un complément des autorisations d’accès aux ressources SharePoint (lors de l’installation ou de l’exécution, en fonction de la conception de l’application), SharePoint récupère des informations sur le complément à partir d’Azure ACS. SharePoint stocke ensuite ces informations dans la base de données du service de gestion des applications du client ou de la batterie de serveurs SharePoint. La clé secrète client est stockée uniquement avec Azure ACS. SharePoint n’a jamais connaissance de la clé secrète du complément. Le service de base de données de contenu et d’autres composants, tels que le service de profil utilisateur, peuvent obtenir directement le nom d’affichage et d’autres informations de base sur le complément à partir du service partagé de gestion des applications. Pour plus d’informations, reportez-vous à la rubrique Récupérer les informations d’inscription du complément et les informations du principal de complément dans cet article.

Remarque

Cet article part du principe que vous êtes familiarisé avec les concepts et les principes de base relatifs à OAuth 2.0 Framework. Pour plus d’informations, consultez OAuth.net et Protocole d’autorisation web (oauth).

Enregistrer votre complément SharePoint dans Azure ACS

Vous pouvez inscrire votre complément pour obtenir son identité de trois façons différentes. La méthode que vous choisissez dépend de votre avancement dans le cycle de développement du complément, de l'architecture de votre complément et de son mode de commercialisation prévu.

Méthode d’inscription Détails
Utilisez Visual Studio et les outils de développement Microsoft Office pour que Visual Studio crée une identité de complément temporaire. L’Assistant Outils de développement Office pour Visual Studio crée une inscription temporaire pour votre complément auprès d’ACS et du service de gestion des applications de votre site web SharePoint de test.

Lorsque vous exécutez le complément à partir de Visual Studio (F5), c’est cette identité qui est utilisée. Les outils insèrent également l’ID client et la clé secrète client dans les fichiers web.config et AppManifest.xml.

Lorsque vous êtes prêt à publier votre complément, vous pouvez utiliser l’Assistant Publication de Visual Studio pour accéder au service Mon tableau de bord vendeur pour l’inscrire. Si vous ne commercialisez pas votre complément SharePoint dans l’Office Store, utilisez AppRegNew.aspx pour effectuer cette opération. (Les étapes exactes sont indiquées dans la section suivante.)

Remarque : si votre complément demande l’autorisation d’accéder dynamiquement aux ressources SharePoint au moment de l’exécution, au lieu d’une installation de complément, vous ne pouvez pas utiliser Visual Studio pour créer des identités de complément.
Inscrire le complément via Mon tableau de bord vendeur. Si vous comptez utiliser votre complément dans plusieurs clients ou batteries de serveurs SharePoint, utilisez le tableau de bord vendeur pour inscrire votre complément, indépendamment du fait qu’il soit commercialisé dans l’Office Store ou mis à disposition via le catalogue de compléments.

Lorsque vous l’inscrivez dans le tableau de bord vendeur, vous pouvez concevoir votre complément avec une architecture mutualisée sans qu’il ne soit nécessaire qu’un administrateur client ou de batterie de serveurs l’inscrive séparément.

Par ailleurs, si vous envisagez de publier votre complément dans l’Office Store, vous devez utiliser le tableau de bord vendeur pour l’inscrire. Il n’est pas nécessaire d’utiliser le Store pour publier un complément qui est inscrit avec le service Mon tableau de bord vendeur. Pour plus d’informations, reportez-vous à la rubrique Création ou mise à jour d’ID et de clés secrètes client dans le service Mon tableau de bord vendeur.
Utilisez la page AppRegNew.aspx. Utilisez le formulaire AppRegNew pour inscrire votre complément SharePoint si vous envisagez d’utiliser le complément uniquement dans un client ou dans une batterie de serveurs.

Par exemple, si vous créez des compléments pour une organisation et que vous allez les distribuer via le catalogue de compléments de l’organisation, vous pouvez utiliser la page AppRegNew.aspx d’un site web dans un client ou une batterie de serveurs pour inscrire le complément.

Vous ne pouvez pas publier un complément inscrit via la page AppRegNew.aspx dans le Office Store. Pour les compléments publiés dans le Office Store, vous devez obtenir une identité à partir du Mon tableau de bord vendeur.

S’inscrire à l’aide de AppRegNew.aspx

  1. Accédez à <site collection url>/_layouts/15/AppRegNew.aspx au moyen d’un navigateur web.

    Formulaire de page AppRegNew

    Formulaire de la page Nouveau registre de l’application avec des zones pour l’ID client, la clé secrète client, le titre, le domaine de l’application et l’URL de redirection. Les boutons nommés « générer » sont en regard des deux premiers. Dans le coin se trouvent les boutons Créer et Annuler.

  2. Entrez des valeurs pour les champs du formulaire suivants :

    • ID du complément. Également appelé ID client ; un GUID peut être généré (lorsque vous sélectionnez Générer) ou collé dans AppRegNew.aspx. La valeur doit être unique pour chaque complément et doit être en minuscules.

    • Question secrète du complément. Également appelée clé secrète client, une chaîne opaque. Elle est générée sur la page AppRegNew.aspx à l’aide du bouton Générer. Voici un exemple de question secrète du complément : xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=

      Importante

      Les clés secrètes de complément ont une durée de validité. Si vous inscrivez le complément dans le tableau de bord vendeur, vous pouvez définir une durée allant jusqu’à trois ans avant l’expiration. Dans le tableau de bord, vous pouvez également ajouter de nouvelles clés secrètes lorsque les anciennes atteignent leur date d’expiration. La nouvelle clé secrète sera activée sur toutes les instances du complément. Si vous inscrivez le complément avec AppRegNew.aspx, la question secrète expire un an plus tard. Pour plus de détails, reportez-vous à la rubrique Remplacement d’une clé secrète client arrivant à expiration dans un complément pour SharePoint.

    • Titre titre convivial ; par exemple, Complément d’impression de photos Contoso. Les utilisateurs sont invités à accorder ou à refuser au complément les autorisations qu’il demande. Ce titre s’affiche en tant que nom du complément à l’invite de consentement.

    • Domaine de complément. Nom d’hôte du composant distant du complément SharePoint. Si l’application distante n’utilise pas le port 443, le domaine du complément doit également inclure le numéro de port. Le domaine du complément doit correspondre aux liaisons d’URL que vous utilisez pour votre application web. N’incluez pas le protocole (« https: ») ou les caractères « / » dans cette valeur. Si l’hôte de votre application web utilise un alias DNS CNAME, utilisez-le. Quelques exemples :

    • URI de redirection :. Le point de terminaison de votre application ou service distant auquel ACS envoie un code d’authentification. En réalité, les compléments SharePoint n’utilisent pas cette valeur. L’URI de redirection est requis pour les applications web qui sont lancées en dehors de SharePoint et qui utilisent le flux de code d’authentification pour obtenir une autorisation d’accès aux données SharePoint.

      L’URI de redirection est ignoré pour les véritables compléments SharePoint (lancés à partir de SharePoint et utilisant le flux de jetons de contexte).

      L’URI de redirection est généralement la page, le contrôleur la méthode ou la méthode de service web qui a demandé le code d’authentification à ACS, mais il peut s’agir d’un autre point de terminaison. Le point de terminaison doit avoir une logique qui récupère le code d’autorisation dans la réponse HTTP envoyée par ACS, puis utilise ce code pour demander un accès et un jeton d’actualisation. Pour plus d’informations, reportez-vous à la rubrique Flux OAuth avec code d’autorisation pour les compléments SharePoint.

      Le formulaire vous demande d’entrer une valeur valide, même pour les véritables compléments SharePoint, bien qu’elle ne soit pas utilisée. Il doit s’agir d’une URL de point de terminaison complète avec son protocole, qui doit être HTTPS. Par exemple:

  3. Sélectionnez Créer sur le formulaire. La page se recharge et affiche une confirmation des valeurs que vous avez entrées. Notez ces valeurs sous un format facile à copier et à coller. Vous devrez entrer les valeurs dans les fichiers web.config et AppManifest.xml ou dans l’Assistant Publication de Visual Studio.

Quelle que soit la manière dont vous inscrivez votre complément SharePoint, lorsque vous êtes prêt à déployer le complément dans un environnement intermédiaire ou de production, vous devez saisir des valeurs d’inscription dans les fichiers web.config et AppManifest.xml. Si vous utilisez Visual Studio, les outils de développement Microsoft Office pour Visual Studio effectuent cette configuration pour vous.

Entrez les valeurs de l’inscription dans les fichiers web.config et AppManifest.xml

Avant d'inclure le Complément SharePoint dans un package et de déployer ses composants distants, entrez une partie des valeurs d'inscription dans les fichiers AppManifest.xml et web.config.

Conseil

Si vous publiez votre complément SharePoint à l’aide de l’Assistant Publication de Visual Studio, Visual Studio vous invite à entrer un ID client et une clé secrète client au cours du processus de publication, puis insère ces informations aux emplacements appropriés à votre place.

  1. Dans le fichier web.config de votre projet Visual Studio, entrez la valeur d'ID du complément pour la valeur de ClientId (elle remplace la valeur temporaire entrée par les outils).

    Importante

    Toutes les lettres du GUID de l’ID client doivent être en minuscules.

    Voici un exemple.

    <appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  .  .  .
</appSettings>

  2. Entrez la valeur de la clé secrète du complément pour la valeur de ClientSecret (elle remplace la valeur temporaire entrée par les outils).

    Voici un exemple de la façon dont les valeurs sont utilisées dans le fichier Web.config d’une application web.

    <appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
</appSettings>

  3. Dans le fichier AppManifest.xml de votre projet Visual Studio, entrez la valeur de l’ID du complément pour la valeur de ClientId, en minuscules.

    Remarque

    Le manifeste de complément ne s’applique pas aux applications web qui demandent l’autorisation d’accès aux ressources SharePoint à la volée. En effet, celles-ci ne sont pas vraiment des « compléments SharePoint ». Elles ne sont pas installées sur SharePoint et n’ont pas de manifeste de complément. Pour plus d’informations, reportez-vous à la rubrique Flux OAuth avec code d’autorisation pour les compléments SharePoint.

    L’exemple suivant illustre l’utilisation de la valeur ClientId dans le fichier AppManifest.xml.

    <AppPrincipal>
  <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
</AppPrincipal>

  4. Les outils de développement Office pour Visual Studio utilisent le jeton ~remoteAppUrl dans l’élément StartPage. (Par exemple, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>.) Ce jeton renvoie l’URL du composant à distance si vous utilisez l’Assistant Publication dans Visual Studio. Si vous n’utilisez pas l’Assistant (ou si vous l’utilisez mais publiez le composant distant dans Azure), vous devez remplacer manuellement le jeton par la valeur de domaine de complément valeur que vous avez utilisée lors de l’inscription du complément. Il doit s’agir de la même valeur exactement, avec son numéro de port éventuel, mais à laquelle vous ajoutez le protocole HTTPS. Voici un exemple.

    <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>

  5. Vous pouvez utiliser la même valeur pour l'élément Title dans le fichier AppManifest.xml que celle que vous avez utilisée pour le champ Titre dans AppRegNew.aspx. La valeur de l'élément Title est le nom du complément que les utilisateurs peuvent voir sur le complément après son installation. Le fait que le complément porte un nom différent dans la boîte de dialogue de consentement et dans l'interface utilisateur SharePoint peut perturber les utilisateurs.

    L’exemple suivant montre ces valeurs dans le manifeste de complément.

    <Properties>
  <Title>Contoso photo printing app</Title>
  <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
</Properties>

Utiliser l’URL de redirection dans un complément pour demander des autorisations à la volée

Si votre application web est lancée en dehors de SharePoint (et n’est donc pas un véritable complément SharePoint), elle doit avoir été conçue pour demander des autorisations à SharePoint lors de l’exécution. Elle doit comporter du code qui utilise l’URI de redirection, ainsi que d’autres informations, pour obtenir un jeton d’accès à partir d’ACS. Recherchez l’emplacement où cet URI est défini et utilisez la valeur exacte que vous avez utilisée pour le champ URI de redirection sur AppRegNew.aspx ou dans le tableau de bord vendeur. Il peut s’agir d’un fichier de code ou d’un fichier de configuration.

Récupérer les informations d’inscription du complément et les informations du principal de complément

Vous pouvez récupérer des informations d’inscription de complément et des informations du principal de complément pour les compléments que vous avez installés ou enregistrés sur SharePoint.

Pour rechercher des informations d’inscription pour un complément que vous avez enregistré, accédez à http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

Pour effectuer une recherche, vous devez mémoriser l'ID client (également appelé ID du complément) utilisé pour inscrire le complément. La recherche renvoie les informations suivantes pour un ID client spécifique :

  • Titre
  • Domaine de complément
  • URL de redirection (il s’agit de la même chose que l’URI de redirection)

La recherche ne renvoie pas la valeur de la clé secrète du complément.

Pour afficher la liste des principaux de complément enregistrés, accédez à : http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx.

Voir aussi