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

In SharePoint, the OAuth authentication and authorization flow for a provider-hosted, low-trust, add-in involves a series of interactions among your add-in, SharePoint, the authorization server, and the browser at runtime. The authorization server in this scenario is Microsoft Azure Access Control Service (ACS).

Important

Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.

With a provider-hosted add-in, you have a remote web application or service that is separate from SharePoint, and not part of the SharePoint farm or SharePoint Online tenancy. It can be hosted in the cloud or on an on-premises server. In this article, the remote component is called Contoso.com.

Notes

The remote component can also host event receivers that respond to events that occur to SharePoint items, such as lists or list items. Examples of remote events that Contoso.com might want to respond to are list events, such as adding or removing a list item; or web events, such as adding or deleting a site. For more information about how to create remote event receivers, see Create a remote event receiver in SharePoint Add-ins.

Contoso.com uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. The Contoso.com application uses an OAuth token-passing flow to authenticate with SharePoint. SharePoint and Contoso.com do not trust each other; but both trust ACS and accept tokens issued by ACS.

There are three tokens involved: SharePoint has ACS create a context token that SharePoint forwards to Constoso.com. Contoso.com validates that the context token was issued by ACS so it trusts it. Contoso.com then extracts a refresh token from the context token and uses it to get an access token directly from ACS. It includes the access token in all its requests to SharePoint. SharePoint validates that the access token was issued by ACS, so it responds to the requests from 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

  • 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

Flux de processus d’autorisation 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 la façon de procéder :

    • 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é, Microsft Office SharePoint Online 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 le secret du complément Contoso.com et le renvoie à Microsoft Office SharePoint Online. Seuls ACS et le complément Contoso.com connaissent le secret.

  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 reçoit le jeton de contexte et valide la signature, ce qu'il peut faire, car il connaît la clé secrète client. Ceci permet à Contoso.com de s'assurer que le jeton a été émis par ACS et non pas par un imposteur se faisant passer pour SharePoint. Contoso.com extrait le jeton d'actualisation du jeton de contexte et l'envoie, avec d'autres informations comprenant son ID client et sa clé secrète client, à ACS sous la forme d'une demande de jeton d'accès qui lui permettra 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 appeler l'API REST SharePoint ou effectuer une demande CSOM auprès de SharePoint. Pour ce faire, 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