Composants WebPart isolés

À l’aide de cette fonctionnalité, vous pouvez créer des composants WebPart qui communiquent en toute sécurité avec les API sécurisées avec Azure AD, sans exposer le jeton d’accès à d’autres composants sur la page ou les scripts dans le client.

Utilisation des composants WebPart isolés

Pour autoriser vos solutions SharePoint Framework à accéder en toute sécurité aux API sécurisées avec Azure AD, vous pouvez utiliser la gestion des API pour spécifier les API qui sont accessibles par les scripts dans votre client, et avec quelles autorisations. Ensuite, avec SharePoint Framework, vous pouvez facilement récupérer un jeton d’accès pour l’API spécifique. Outre la simplification considérable de la communication avec les API sécurisées avec Azure AD, cette fonction autorise tous les scripts, et pas seulement des solutions SharePoint Framework spécifiques, à obtenir un jeton d’accès aux API approuvées. Si l’un des scripts que vous utilisez dans votre client a été exploité, il peut accéder aux API approuvées pour le compte de l’utilisateur actuel.

Les composants WebPart isolés représentent un nouveau moyen d’isoler l’accès aux API sécurisées avec Azure AD et de vous assurer que seuls certains composants WebPart SharePoint Framework spécifiques sont autorisés à obtenir un jeton d’accès à l’API donnée.

Fonctionnement des composants WebPart isolés

Important

La fonctionnalité de composants WebPart isolés est disponible uniquement dans SharePoint Framework v1.8 et dans les versions ultérieures. Les composants WebPart isolés sont uniquement pris en charge sur les pages modernes. Même si vous pouvez ajouter des composants WebPart isolés à des pages classiques, lors de la publication, le composant WebPart ne s’affiche pas et génère une erreur. Les composants WebPart isolés ne peuvent être installés que dans le catalogue d’applications client. Ils ne fonctionnent pas à partir d’un catalogue d’applications collection de sites.

Les solutions qui utilisent la fonctionnalité de composants WebPart isolés contiennent un indicateur spécifique défini dans les métadonnées du projet dans le fichier *.sppkg. Lors du déploiement de ces solutions dans le catalogue d’applications, toutes les demandes d’autorisations d’API sont spécifiées comme isolées.

Après l’approbation d’une demande d’autorisation d’API isolée, SharePoint crée une application Azure AD distincte dans l’instance Azure AD associée au client Microsoft 365. Cette application Azure AD est propre à la solution SharePoint Framework qui a demandé les autorisations d’API. Des autorisations OAuth seront définies comme le requiert cette solution. L’URL de renvoi de cette application Azure AD, utilisée par le flux implicite OAuth, sera définie sur un domaine unique lié à cette application SharePoint Framework spécifique.

Un fois ajoutés à une page, tous les composants WebPart de solutions utilisant des autorisations isolées sont affichés à l’aide d’un iframe pointant vers un domaine unique lié à une solution SharePoint Framework précise. Ainsi, SharePoint Framework peut appliquer des autorisations d’API uniques. Vous êtes donc certain qu’aucune autre solution ou aucun autre script dans le client ne peut obtenir de jeton d’accès à ces API.

Génération de modèles automatique pour un projet qui utilise des autorisations isolées

Lorsque vous générez la structure d’un nouveau projet SharePoint Framework qui cible SharePoint Online, le générateur Yeoman SharePoint Framework affiche l’invite suivante :

Les composants de la solution nécessiteront-ils des autorisations pour accéder aux API Web qui sont uniques et qui ne sont pas partagées avec d'autres composants du client ? :

Si vous répondez Oui, le générateur ajoute un indicateur à la configuration de votre projet dans le fichier config/package-solution.json, en définissant la propriété isDomainIsolated sur true. Étant donné que la fonctionnalité de composants WebPart isolés s’applique uniquement aux composants WebPart, le générateur vous permet uniquement de créer des composants WebPart dans votre projet.

Important

En théorie, vous pouvez créer manuellement une extension SharePoint Framework dans un projet qui utilise des autorisations isolées. Toutefois, c’est une mauvaise idée, vous devriez éviter de le faire et non pris en charge.

Si l’extension que vous avez ajoutée a communiqué avec des API sécurisées avec Azure AD, elle ne pourrait pas récupérer le jeton d’accès de manière isolée et l’exécution échouerait.

Communication avec les API

Malgré le composant WebPart utilisant des autorisations isolées, votre code ne spécifie aucun mode d’obtention d’un jeton d’accès à une API sécurisée avec Azure AD. Par ailleurs, même si, lors de l’exécution, les composants WebPart isolés sont chargés dans un iframe pointant vers un domaine unique, vous pouvez communiquer avec les API REST SharePoint de la même façon que dans des composants WebPart non isolés.

Déploiement de solutions avec des composants WebPart isolés

Les solutions contenant des composants WebPart isolés sont déployées de la même manière que les solutions SharePoint Framework normales. La seule différence est que les demandes d’autorisations d’API sont déployées de manière isolée. C’est clairement visible dans la page de gestion des API, qui regroupe les demandes d’autorisations d’API selon les solutions auxquelles elles s’appliquent.

Les autorisations d’API accordées au niveau du client peuvent être utilisées par toute solution SharePoint Framework ou par une portion de script sur le client. En revanche, seule la solution ayant demandé des autorisations isolées peut utiliser ces dernières.

Utilisation de composants WebPart isolés

Une fois ajoutés à la page, les composants WebPart isolés sont affichés à l’aide d’un iframe. Cet iframe pointe vers un domaine unique affecté à la solution SharePoint Framework où se trouve le composant WebPart. Ce domaine est également référencé dans l’URL de renvoi de l’application Azure AD créée pour héberger les autorisations isolées pour la solution SharePoint Framework particulière. En utilisant un domaine unique, vous êtes sûr que seuls les composants WebPart de la solution SharePoint Framework spécifique obtiennent un jeton d’accès au jeu d’autorisations isolé.

Volet de propriétés pour les composants web isolés

Le volet de propriétés des composants Web isolés est rendu sous la forme d’un iframe distinct avec une instance supplémentaire du même composant Web. Il apporte certaines caractéristiques que les développeurs doivent connaître :

• Les événements de cycle de vie du composant Web isolé, par render exemple, seront appelés deux fois : une fois pour le composant Web lui-même et une fois pour le volet de propriétés.
• La taille d’iframe du volet de propriétés est limitée aux dimensions du panneau. Prenez-en compte si vous envisagez d’utiliser des modales ou des contrôles larges dans votre volet de propriétés.

Élimination des composants Web isolés

onDispose La méthode pour les composants Web isolés peut ne pas être appelée car la suppression d’iframe du DOM nettoie automatiquement toutes les ressources, y compris les connexions de socket, associées au document de l’iframe.

Mise à niveau d’un projet existant pour utiliser des autorisations isolées

Si vous mettez à niveau un projet SharePoint Framework vers la version 1.8.0 pour utiliser la fonctionnalité d’autorisations isolées, dans le fichier config/package-solution.json, définissez la propriété isDomainIsolated sur true. Veuillez vérifier que votre projet contient seulement des composants WebPart.

Après avoir modifié le projet pour utiliser des autorisations isolées, vous devez le redéployer. Cette opération entraîne l’émission de nouvelles demandes d’autorisations d’API isolées pour votre solution, qui doive être approuvées par l’administrateur du client.

Suppression de solutions avec des autorisations isolées

Une fois les autorisations d’API isolées approuvées, SharePoint crée une application Azure AD dédiée spécifiquement à la solution SharePoint Framework ayant demandé des autorisations. Lorsque la solution SharePoint Framework est supprimée du catalogue d’applications, les autorisations d’API et l’application Azure AD ne sont pas supprimées.