Flux OAuth avec jetons de contexte pour les compléments SharePoint

Dans SharePoint, le flux d’authentification et d’autorisation OAuth pour un complément hébergé par un fournisseur, à faible niveau de fiabilité, implique une série d’interactions entre votre complément, SharePoint, le serveur d’autorisation et le navigateur au moment de l’exécution. Dans ce scénario, le serveur d'autorisation est Microsoft Azure Access Control Service (ACS).

Avec un complément hébergé par un fournisseur, vous disposez d'une application web distante ou d'un service distinct de SharePoint qui ne fait pas partie de la batterie SharePoint ou de la location SharePoint Online. Il peut être hébergé dans le cloud ou sur un serveur local. Dans cet article, le composant distant est appelé Contoso.com.

Contoso.com utilise le modèle objet client (CSOM) SharePoint ou les API REST SharePoint pour appeler SharePoint. L'application Contoso.com utilise un flux de transmission de jeton OAuth pour s'authentifier avec SharePoint. SharePoint et Contoso.com ne font pas confiance l’un à l’autre, mais approuvent les services ACS et acceptent les jetons émis par ACS.

Trois jetons sont impliqués : SharePoint a ACS crée un jeton de contexte que SharePoint transfère à Constoso.com. Contoso.com valide que le jeton de contexte a été émis par le service ACS et l'approuve. Contoso.com extrait ensuite un jeton d’actualisation du jeton de contexte et l’utilise pour obtenir un jeton d’accès directement à partir d’ACS. Il inclut ce jeton d'accès dans toutes ses demandes à SharePoint. SharePoint valide que le jeton d'accès a été émis par le service ACS et répond donc aux demandes de Contoso.com.

Vous fournissez le code de gestion de jeton dans le composant distant (mais si votre composant distant est hébergé sur .NET, les outils de développement Microsoft Office pour Visual Studio fournissent un exemple de code qui fait la plupart du travail à votre place). Pour en savoir plus sur le code de gestion de jeton, reportez-vous à la rubrique Gérer les jetons de sécurité dans les compléments SharePoint de confiance basse hébergés par un fournisseur.

Conditions préalables

Les étapes préliminaires suivantes doivent être effectuées pour qu’un complément SharePoint puisse utiliser le flux de jeton de contexte.

• Les conditions suivantes s’appliquent uniquement si vous installez le complément SharePoint en local en plus de SharePoint Online. Elles ne s’appliquent pas si vous installez uniquement le complément SharePoint sur SharePoint Online

  • La batterie de serveurs doit être configurée de manière à prendre en charge les compléments. Cette condition est requise pour l’installation de tous les compléments SharePoint dans la batterie, même s’ils n’utilisent pas le flux de jeton de contexte. Pour en savoir plus, reportez-vous à la rubrique Outils et environnement pour le développement de compléments SharePoint.
  • Le client qui a installé le complément doit avoir un compte Office 365. Celui-ci est nécessaire pour accéder à ACS. Le client n’a pas à utiliser son compte à d’autres fins.
  • La batterie de serveurs doit être configurée pour partager la relation de confiance qui existe entre Office 365 et ACS. Les scripts Windows PowerShell permettent d’effectuer cette opération facilement. Pour plus d’informations, reportez-vous à Utiliser un site SharePoint Office 365 pour autoriser des compléments hébergés par un fournisseur sur un site SharePoint local.

• Que le complément soit installé sur SharePoint Online ou sur une batterie de serveurs SharePoint locale, le complément SharePoint doit être inscrit auprès d’ACS. Pour plus d’informations sur cette opération, reportez-vous à la rubrique Enregistrement des compléments SharePoint. Entre autres, le complément communique à ACS sont ID et sa clé secrète client dans le cadre de l’inscription.

Étapes du flux de jetons de contexte

Le flux d’autorisation et d’authentification OAuth pour un complément hébergé par un fournisseur SharePoint sont illustrés dans la figure suivante.

Flux de jeton de contexte OAuth

Voici les étapes correspondant aux numéros de la figure :

1. Un utilisateur lance le Complément SharePoint à partir de SharePoint. La conception du complément détermine le déroulement de l'action :

   • Si le complément est conçu pour révéler l’application web distante (sur Contoso.com) dans un composant de complément (qui est pour l’essentiel un wrapper autour d’un IFRAME), son lancement implique simplement d’accéder à une page SharePoint qui contient le composant de complément. (Si l’utilisateur n’est pas déjà connecté, SharePoint invite l’utilisateur à le faire). SharePoint traite la page et détecte qu’elle contient un composant de l’application Contoso.com. (Pour plus d’informations sur les composants des compléments, consultez la section Créer des composants de complément à installer avec votre complément SharePoint.)
   • Si le complément est conçu pour être utilisé comme une page entière dans le navigateur, l’utilisateur le démarre en sélectionnant sa vignette sur la page Contenu du site du site web SharePoint. (Le complément peut également contenir un menu ou un élément de ruban personnalisé qui permet d’ouvrir le composant distant.)

2. Quelle que soit la manière dont le complément est lancé, SharePoint doit obtenir un jeton de contexte qu’il peut envoyer à l’application Contoso.com. Pour ce faire, il demande à ACS de créer un jeton de contexte qui contient des informations sur le contexte SharePoint, y compris l’utilisateur actuel, l’URL du complément distant et d’autres informations. Le jeton de contexte contient également un jeton d’actualisation chiffré.

3. Le service ACS signe le jeton de contexte, à l’aide d’un algorithme qui utilise la clé secrète du complément Contoso.com, et le renvoie à SharePoint. Seuls le service ACS et le complément Contoso.com connaissent la clé secrète.

4. Si l’application Contoso.com est exposée dans un composant de complément, SharePoint affiche la page qui héberge le composant et ajoute le jeton de contexte à l’URL que l’IFRAME du complément appelle pour obtenir son contenu. Si l’application Contoso.com est une page entière, SharePoint redirige le navigateur vers Contoso.com et inclut le jeton de contexte dans le cadre de la réponse de redirection.

5. Le jeton de contexte est inclus dans la demande du navigateur qui est envoyée au serveur Contoso.com.

6. Le serveur Contoso.com obtient le jeton de contexte et valide la signature. Il en a la possibilité puisqu’il connaît la clé secrète client. Contoso.com a ainsi la garantie que le jeton a été émis par ACS et non par un imposteur prétendant être SharePoint. Contoso.com extrait le jeton d’actualisation du jeton de contexte et l’envoie, avec d’autres informations, notamment son ID client et la clé secrète client, au service ACS dans une demande de jeton d’accès qui lui permet d’accéder à SharePoint.

7. ACS valide le jeton d’actualisation pour garantir qu’il a bien émis le jeton, puis renvoie un jeton d’accès à Contoso.com. Contoso.com a également la possibilité de mettre en cache ce jeton d’accès pour éviter d’en demander un au service ACS à chaque fois qu’il accède à SharePoint. Par défaut, les jetons d’accès sont valides pendant quelques heures. (Au moment de la rédaction de cet article, la durée de validité par défaut des jetons d’accès ACS émis vers SharePoint était de 12 heures, mais cette valeur peut changer).

Chaque jeton d’accès est spécifique au compte d’utilisateur spécifié dans la demande d’autorisation d’origine et octroie uniquement un accès au service (ici SharePoint) indiqué dans cette demande. Les jetons d’actualisation ont une durée de vie plus longue (six mois lors de la rédaction de cet article) et peuvent également être mis en cache. Ainsi, un même jeton d’actualisation peut être échangé contre un nouveau jeton d’accès émis par ACS jusqu’à ce que le jeton d’actualisation lui-même arrive à expiration. (Pour plus d’informations sur la mise en cache des jetons, reportez-vous à la rubrique Gérer les jetons de sécurité dans les compléments SharePoint de confiance basse hébergés par un fournisseur.)

Lorsque le jeton d’actualisation expire, Contoso.com peut en recevoir un nouveau en obtenant un nouveau jeton de contexte. Pour plus d’informations, reportez-vous à la rubrique Obtenir un nouveau jeton de contexte.

1. Contoso.com utilise le jeton d’accès pour effectuer un appel d’API REST SharePoint ou une demande CSOM à spnv. Pour cela, il transmet le jeton d’accès OAuth dans l’en-tête HTTP Authorization. (Un exemple de code de création de l’en-tête est fourni dans les outils de développement Office pour Visual Studio si votre composant distant est hébergé sur une plateforme .NET.)
2. SharePoint valide le jeton d'accès pour vérifier qu'il a été émis par le service ACS. Il envoie ensuite à Contoso.com les données que celui-ci demande ou exécute l'opération de création, lecture, mise à jour ou suppression (CRUD) demandée par Contoso.com.
3. La page de l’application Contoso.com s’affiche dans le navigateur (ou dans l’ IFRAME du composant de complément).

Voir aussi

• Autorisations des compléments dans SharePoint
• Aspects importants du contexte de développement et de l’architecture des compléments SharePoint
• Création de compléments SharePoint qui utilisent l’autorisation de confiance basse
• Autorisation et authentification des compléments dans SharePoint