Gérer des jetons de sécurité dans les compléments SharePoint de confiance basse hébergés par un fournisseur
Importante
Cet article dans son intégralité traite de l’utilisation des jetons de sécurité dans le système d’autorisation à faible niveau de fiabilité, et non dans le système à haut niveau de fiabilité. Pour plus d’informations sur l’utilisation de jetons dans le système à haut niveau de fiabilité, consultez la rubrique Créer et utiliser des jetons d’accès dans des compléments SharePoint à haut niveau de fiabilité hébergés par un fournisseur.
Les compléments SharePoint qui utilisent le système d’autorisation à faible niveau de fiabilité pour accéder à des données SharePoint participent à un flux OAuth qui implique le transfert de jetons de sécurité (au format JSON Web Token) entre SharePoint, Microsoft Azure Access Control Service (ACS), les composants à distance du complément SharePoint et, dans certains cas, le navigateur de l’utilisateur.
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. Cette mise hors service n’a pas d’impact sur le modèle de complément SharePoint, qui utilise le https://accounts.accesscontrol.windows.net nom d’hôte (qui n’est pas affecté par cette mise hors service). Pour plus d’informations, reportez-vous à Conséquences du retrait du contrôle d’accès Azure pour les compléments SharePoint.
Il existe différents flux en fonction de la conception du complément, mais tous impliquent au moins les deux types de jetons suivants :
- Jeton d’accès. Inclus dans chaque demande de création, lecture, mise à jour ou suppression (CRUD) provenant des composants à distance du complément pour SharePoint. SharePoint valide le jeton et effectue la demande.
- Jeton d’actualisation. Utilisé pour obtenir un premier jeton d’accès dans le flux du jeton de contexte et pour remplacer les jetons d’accès expirés à la fois dans le flux de jeton de contexte et dans le flux du code d’autorisation du système d’autorisation à faible niveau de fiabilité.
En fonction du flux OAuth que le complément utilise, l’une ou l’autre des opérations suivantes fait également partie du processus :
- Jeton de contexte. Utilisé dans le flux du jeton de contexte pour fournir au composant à distance un jeton d’actualisation et des informations qui lui sont nécessaires pour demander un jeton d’accès auprès d’Azure ACS.
- Code d’autorisation. Il ne s’agit pas d’un jeton mais d’un code d’autorisation propre à chaque paire formée par l’utilisateur et l’application. Il est utilisé dans le flux du Code d’autorisation pour obtenir un premier jeton d’accès et un jeton d’actualisation.
Jetons d’accès
Dans le système d’autorisation à faible niveau de fiabilité, les jetons d’accès sont créés par Azure ACS et envoyés au composant à distance de votre complément SharePoint. (Lorsque cet article a été écrit, les jetons d’accès émis par ACS pour SharePoint avaient une durée de vie de 12 heures, mais cela pourrait changer.) Les principales actions que le code de votre complément SharePoint doit implémenter sont les suivantes :
- Demander un jeton d’accès à Azure ACS. En fonction du flux OAuth utilisé, le complément utilise soit un code d’autorisation, soit des informations d’autorisation qu’il extrait d’un jeton de contexte pour effectuer la demande.
- Inclure le jeton dans chaque requête HTTP vers SharePoint. Le jeton est ajouté comme un en-tête Autorisation à la demande. La valeur de l’en-tête est le mot « Support » suivi d’un espace, puis du jeton d’accès codé en base 64.
- Mettre en cache le jeton d’accès pour le réutiliser lors de demandes ultérieures (facultatif mais recommandé).
- Facultatif, transférer le jeton d’accès aux systèmes principaux afin qu’ils puissent accéder directement à SharePoint.
Ces tâches doivent être effectués avec le code côté serveur. Si vous utilisez du code managé, un exemple de code pour certaines de ces tâches est disponible dans les fichiers SharePointContext.cs (ou .vb) et TokenHelper.cs (ou .vb) qui font partie des Outils de développement Microsoft Office pour Visual Studio. Pour consulter un exemple de code PHP qui effectue certains de ces tâches, consultez la rubrique MSDN : SharePoint 2013 : Comprendre et utiliser l’interface REST de SharePoint.
Mettre en cache le jeton d’accès
Selon l’architecture et la plate-forme d’hébergement de votre complément SharePoint, il existe plusieurs manières de mettre en cache le jeton d’accès sur le serveur :
- Dans l’état de session
- Dans l’état de l’application
- Dans la mise en cache de Windows Server AppFabric ou son équivalent dans un système d’exploitation autre que Microsoft
- Dans le Service de mise en cache Microsoft Azure ou son équivalent dans un service cloud autre que Microsoft
- Dans une base de données
- Dans un système memcached
Remarque
Dans la plupart des scénarios, vous ne pourrez pas utiliser des termes aussi simples que « AccessToken » comme clé de mise en cache, car votre complément doit conserver séparément les jetons pour les différents utilisateurs et les batteries de serveurs/architectures SharePoint. Si votre complément utilise leFlux de jeton de contexte, il existe une clé CacheKey spéciale fournie par SharePoint, qui peut être utilisée pour distinguer les jetons mis en cache. Cette section décrit les problèmes connus et les solutions à adopter lorsque votre application n'utilise pas le Flux de jeton de contexte.
La mise en cache du jeton d’accès dans l’état de session suffit pour la plupart des scénarios. Si l’application web distante accède à d’autres services qui utilisent OAuth (en plus de SharePoint) et met en cache les différents jetons d’accès dans l’état de session, veillez à utiliser des clés de cache distinctes pour les jetons ; par exemple, au lieu de « AccessToken », utilisez « SharePoint_AccessToken », « Facebook_AccessToken », « SAP_Gateway_AccessToken », etc. (Si vous n’utilisez pas l’état de session ou certaines autres mises en cache qui séparent automatiquement le cache de chaque utilisateur, vous devez relativiser vos clés pour les utilisateurs.)
Si l’application accède à plusieurs batteries de serveurs ou architecture en ligne SharePoint, vous pouvez utiliser le domaine SharePoint dans le cadre de la clé de mise en cache principale de l’application (SharePoint<mydomain>.sharepoint.com_AccessToken) ou utiliser le domaine de la batterie de serveurs/l’architecture (SharePoint<realmGUID>_AccessToken), qui peuvent tous deux être lus à partir du jeton d’accès. (Votre code doit inverser l’encodage Base 64 du jeton pour le lire. Dans le code managé, le fichier TokenHelper.cs ou .vb contient un exemple de code à cet effet qui utilise des classes des espaces de noms Microsoft.IdentityModel.S2S.Tokens et System.IdentityModel.Tokens .) Une autre option est disponible lorsque l’application utilise le flux de jeton de contexte, comme décrit dans le paragraphe suivant.
Il se peut que, dans certains scénarios, votre application ait besoin de mettre en cache le jeton d’accès à un emplacement disponible pour l’application pour toutes les sessions ou après l’arrêt d’une session. Par exemple, l’application peut être conçue pour permettre aux utilisateurs de planifier des actions à réaliser après que l’utilisateur a fermé l’application. Si ces actions incluent l’accès à SharePoint, le complément doit récupérer le jeton d’accès. Dans ce type de scénario, votre application doit conserver séparément les jetons d’accès des différents utilisateurs.
Si vous utilisez le flux du jeton de contexte, une chaîne de clé de cache est fournie à cet effet dans le jeton de contexte que SharePoint transmet au composant à distance de votre complément SharePoint lorsque ce dernier est lancé. Pour plus d’informations concernant cette clé de cache spécial et son utilisation, consultez la rubrique Comprendre la clé de cache. Vous pouvez également utiliser cette chaîne pour le scénario décrit précédemment. Le système de planification offre différents moyens de stocker les données de configuration dont il a besoin, comme le moment où le travail planifié s’exécute et ce qu’il doit faire. Utilisez ce stockage pour conserver la clé de cache pour le jeton d’accès.
Si le cache inter-zone que vous utilisez est également partagé par plusieurs applications, les clés de cache doivent être mises en relation avec les applications et avec les utilisateurs et les domaines SharePoint. La clé de cache fournie dans le jeton de contexte est propre aux applications et aux utilisateurs et aux domaines SharePoint.
Si votre application utilise le flux du code d’autorisation, il n’y a aucun jeton de contexte et, par conséquent, aucune clé de cache spécifique. Dans ce scénario, vous devez créer votre propre système de clés pour les données mises en cache qui sont liées à une ou plusieurs opérations suivantes, en fonction des éventuels conflits de nom qui pourraient se produire, étant donné les cas d’utilisation de votre application : l’utilisateur, le domaine SharePoint et l’application. Vous pouvez utiliser les revendications présentes dans le jeton d’accès à cet effet, par exemple, les éléments nameId et aud (consultez les tableaux suivants). Votre code peut simplement concaténer les chaînes ou les utiliser comme des graines pour créer un hachage unique qui peut servir de clé de cache.
Enfin, si votre application effectue des appels compléments uniquement et utilisateur+complément vers SharePoint, elle disposera de deux jetons d’accès différents, vous aurez donc des clés de cache distinctes. Une fois que vous avez choisi une clé de cache de base, ajoutez-y simplement « _add-in-only » ou « _add-in+utilisateur ».
Avertissement
Le stockage du jeton d’accès dans un cookie n’est pas une pratique sûre. Il est généralement conseillé d’éviter que le jeton d’accès ne passe par le navigateur.
Transférer le jeton d’accès aux systèmes principaux
Un complément SharePoint peut avoir des serveurs principaux qui ne sont pas hébergés dans le même domaine que l’application web à distance. Lorsqu’un serveur principal doit effectuer des opérations CRUD sur SharePoint, le complément les effectue plus vite si ces opérations peuvent passer directement du système principal à SharePoint. Heureusement, le domaine n’est important que si votre application obtient un jeton d’accès auprès d’ACS. Lorsqu’il a le jeton, il peut le transférer aux services de serveur principal et ceux-ci peuvent appeler SharePoint en utilisant ce jeton.
Le code de ces systèmes doit gérer les jetons d’accès expirés et envoyer une demande de nouveau jeton à l’application web parent enregistrée auprès d’ACS (consultez la rubrique Gérer les jetons d’accès arrivés à expiration). Cette technique doit être utilisée uniquement pour vos serveurs principaux de l’application, et non pour les services web externes. Par ailleurs, si vous utilisez cette technique, envisagez de concevoir les services principaux pour qu’ils utilisent des appels complément uniquement dès que possible.
Gérer les jetons d’accès arrivés à expiration
Un jeton d’accès expire après quelques heures (12 heures au moment où cet article a été rédigé, mais cela peut changer). Si l’application accède toujours à SharePoint après l’expiration du jeton d’accès, la première demande vers SharePoint après l’expiration génère une erreur 401 Non autorisé. Votre code doit gérer cette réponse.
Par ailleurs, le code peut tester le délai d’expiration du jeton d’accès avant de l’utiliser. Votre code utilise le jeton d’actualisation pour obtenir un autre jeton d’accès auprès d’ACS. Dans le flux du jeton de contexte, le jeton d’actualisation est inclus dans le jeton de contexte que votre complément reçoit de la part de SharePoint au début de sa première session avec SharePoint. Dans le flux du code d’autorisation, il est transmis à l’application en même temps que le premier jeton d’accès. Votre code doit le mettre en cache pour qu’il soit disponible en cas de besoin. Le jeton d’actualisation dure quelques mois et peut être conservé dans un cookie ou un stockage côté serveur. Pour plus d’informations, consultez la rubrique Comprendre la gestion et la mise en cache des jetons d’actualisation.
Exemples de jetons d’accès pour le système d’autorisation à faible niveau de fiabilité
Cette section décrit les jetons d’accès, avec des exemples, et illustre leurs différences en fonction de la stratégie d’autorisation utilisée.
Stratégie utilisateur+complément
Voici un exemple décodé d’un jeton d’accès utilisateur+complément généré par ACS pour être utilisé lors des appels vers SharePoint à l’aide de la stratégie utilisateur+complément. Un espace blanc a été ajouté pour la lisibilité. Le jeton est conforme au protocole JSON Web Token. L’objet JavaScript Object Notation (JSON) dans le jeton est appelé ensemble de revendications (consultez le Tableau 1 pour plus de détails sur les propriétés de l’ensemble de revendications).
Notez que toutes les valeurs doivent être en minuscules. (Les jetons d’accès utilisateur+complément sont identiques dans le flux du jeton de contexte et le flux du code d’autorisation.)
{
"aud": "00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
"iss": "00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
"nbf": 1377549246,
"exp": 1377592446,
"nameid": "2303000085ff9abc",
"actor": "964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73",
"identityprovider": "urn:federation:microsoftonline"
}
Tableau 1 : Utilisateur émis par les services ACS + revendications de jetons d’accès de complément
| Revendication | Description | Valeur correspondante dans l’exemple de jeton d’accès |
|---|---|---|
aud |
Abrégé pour « audience », désignant le principal pour lequel le jeton est prévu. Le format est audience principal ID/SharePoint domain@SharePoint realm, où audience principal ID est un ID de principal de sécurité permanent pour SharePoint (consultez la rubrique Microsoft Product Application Principal Constants).SharePoint realm est le GUID de l’architecture SharePoint Online, ou de la batterie de serveurs SharePoint locale, à laquelle le jeton d’accès permet d’accéder. Ce GUID fonctionne comme l’ID de domaine pour l’émetteur du jeton, en l’occurrence Azure ACS. |
00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73 |
iss |
Abrégé pour « émetteur ». Il représente le principal qui a créé le jeton. Le format est Issuer GUID@SharePoint realm GUID. Dans le système d’autorisation à faible niveau de fiabilité, l’émetteur est Azure ACS et son GUID est 00000001-0000-0000-c000-000000000000. |
00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73 |
nbf |
Abrégé pour « pas avant ». Il représente l’heure à laquelle le jeton commence à être valable, en secondes depuis le 1er janvier 1970 à minuit. Par défaut, il est défini sur le moment où le jeton a été créé (consultez la rubrique Valeurs de temps JWT). | 1377549246 |
exp |
Abrégé pour « expiration ». Elle représente l’heure à laquelle le jeton expire. Par défaut, c’est 12 heures après le temps nbf (consultez la rubrique Valeurs de temps JWT). | 1377592446 |
nameid |
Identificateur unique pour l’utilisateur pour lequel le jeton est émis. Le format varie en fonction du fournisseur d’identité. Dans cet exemple, le fournisseur est Microsoft Online, mais s’il s’agissait d’Active Directory, l’ID ressemblerait à s-1-5-21-2127521184-1604012920-1887927527-415149. |
2303000085ff9abc |
actor |
Principal qui cherche à accéder à la batterie de serveurs ou l’architecture SharePoint. Il prend la forme Client ID of Application@SharePoint realm. |
964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73 |
identityprovider |
Nom unique du fournisseur d’identité tel qu’inscrit auprès de l’organisme IANA (Internet Assigned Numbers Authority). Pour un complément installé sur SharePoint Online, la valeur est généralement la même que dans cet exemple. Pour un complément installé sur une batterie de serveurs locale, il s’agit généralement d’un fournisseur d’identité local, comme urn:office:idp:activedirectory. |
urn:federation:microsoftonline |
Stratégie complément uniquement
Voici l’exemple décodé d’un jeton d’accès complément uniquement généré par ACS pour servir aux appels vers SharePoint à l’aide de la stratégie complément uniquement. Un espace blanc a été ajouté pour la lisibilité. Le jeton est conforme au protocole JSON Web Token. Consultez le Tableau 2 pour plus de détails sur les propriétés de l’ensemble de revendications. (La stratégie complément uniquement n’est pas disponible pour les applications qui utilisent le flux du code d’autorisation, car elles n’ont pas de fichier de manifeste du complément et, par conséquent, elles ne peuvent pas demander l’autorisation d’utiliser les appels complément uniquement.)
{
"aud":"00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
"iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
"nbf":1403304705,
"exp":1403347905,
"nameid":"c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73",
"sub":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
"oid":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
"trustedfordelegation":"false",
"identityprovider":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73"
}
Tableau 2 : Revendications des jetons d’accès complément uniquement émis par ACS
| Revendication | Description | Valeur correspondante dans l’exemple de jeton d’accès |
|---|---|---|
aud |
Identique au jeton utilisateur+complément du Tableau 1. | 00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73 |
iss |
Identique au jeton utilisateur+complément du Tableau 1. | 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73 |
nbf |
Identique au jeton utilisateur+complément du Tableau 1. | 1403304705 |
exp |
Identique au jeton utilisateur+complément du Tableau 1. | 1403347905 |
nameid |
Identificateur unique du complément, à la place de l’utilisateur, puisque l’identité de l’utilisateur n’a pas d’importance dans le cadre de la stratégie complément uniquement. Le format est client ID@SharePoint realm. |
c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73 |
sub |
Abrégé pour « sujet ». Il représente le sujet du jeton, qui est le principal cherchant à accéder à SharePoint ; dans ce cas, il s’agit de l’application web distante. L’ID d’objet est utilisé pour la valeur. Consultez la revendication oid. |
1d47ac31-498b-4988-8aac-85fc9bd2e1ce |
oid |
Raccourci pour « ID d’objet ». Il s’agit de l’ID d’objet dans Azure Active Directory pour l’application Web distante. Dans un jeton d’accès en complément, l’objet et l’ID d’objet ont la même valeur. | 1d47ac31-498b-4988-8aac-85fc9bd2e1ce |
trustedfordelegation |
Valeur booléenne qui indique si SharePoint doit approuver ou non le complément SharePoint pour authentifier et autoriser l’utilisateur. false dans les appels complémentaires uniquement parce que l’identité de l’utilisateur importe peu. | false |
identityprovider |
Nom unique du fournisseur d’identité. Comme il s’agit du complément, et non d’un utilisateur, dont l’identité est fournie, ACS est le fournisseur d’identité. Le format est ACS GUID@SharePoint realm. |
00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73 |
Jetons de contexte
Un jeton de contexte est utilisé uniquement dans le flux du jeton de contexte du système d’autorisation à faible niveau de fiabilité. Lorsque le complément SharePoint est lancé dans SharePoint, ce dernier demande à Azure ACS de créer un jeton de contexte que SharePoint transmet ensuite au composant à distance du complément SharePoint. Le jeton est transmis sous forme de paramètre de formulaire masqué appelé SPAppToken dans une demande provenant de SharePoint pour la page de démarrage du composant à distance. Le jeton est signé avec une clé secrète client connue uniquement d’ACS et du complément SharePoint.
Le jeton de contexte inclut un jeton d’actualisation que le complément utilise, ainsi que d’autres informations provenant du jeton de contexte, pour demander un jeton d’accès à ACS. (Lorsque cet article a été rédigé, les jetons de contexte émis par ACS pour SharePoint avaient une durée de vie de 12 heures, mais cela pourrait changer).
Les principales tâches du code dans le complément SharePoint sont les suivantes :
- Utiliser la clé secrète client du complément pour valider le jeton de contexte.
- Mettre en cache le jeton de contexte, ou extraire le jeton d’actualisation et certains autres éléments qu’il contient et les mettre en cache séparément.
- Utiliser le jeton d’actualisation et d’autres informations pour demander un jeton d’accès auprès d’ACS (lui-même mis en cache par la suite).
- Mettre en cache la clé CacheKey à partir du jeton de contexte.
Importante
Les deux premières tâches doivent se dérouler avant que l’utilisateur n’accède à une autre page ou n’actualise la page, sans quoi le jeton est perdu. Par exemple, dans une application de formulaires web ASP.NET, envisagez d’effectuer ces tâches dans la méthode Page_Load (dans un bloc de code conditionnel qui s’exécute uniquement lorsque la demande n’est pas une publication). Dans une application MVC ASP.NET, envisagez d’effectuer ces tâches dans la méthode du contrôleur par défaut.
Si vous utilisez du code managé, un exemple de code pour certaines de ces tâches se trouve dans les fichiers SharePointContext.cs (ou .vb) et TokenHelper.cs (ou .vb) inclus dans les Outils de développement Microsoft Office pour Visual Studio. Vous devez seulement envoyer des appels simples aux membres de la classe TokenHelper. Par exemple, votre code peut effectuer la première tâche avec la seule ligne de code suivante :
SharePointContextToken contextToken =
TokenHelper.ReadAndValidateContextToken(contextTokenString,
Request.Url.Authority);
Mettre en cache le jeton de contexte ou des composants de celui-ci
Vous pouvez mettre en cache un jeton de contexte entier, ou simplement le jeton d’actualisation et certains autres éléments contenus à l’intérieur et que votre code utilise pour obtenir des jetons d’accès, dans un stockage côté serveur ou côté client. Pour faire simple, cet article suppose que vous mettez en cache le jeton de contexte comme une seule entité.
Importante
Nous vous rappelons que vous ne devez pas utiliser pas la mise en cache côté client pour le jeton d’accès. Cette pratique d’utilisation n’est sûre que pour le jeton de contexte.
Vous disposez des mêmes options de mise en cache côté serveur que celles répertoriées plus tôt pour le jeton d’accès. Les options côté client incluent un cookie et un champ de formulaire masqué sur une page HTML. Une autre option consiste à stocker le jeton de contexte dans le cache de session, mais stockez la clé CacheKey obtenue à partir de celui-ci sur le client.
Si votre application accède à SharePoint après la fin d’une session, ni la mise en cache de session ni la mise en cache côté client n’est une option, car le jeton d’actualisation doit être disponible pour l’application au cas où le jeton d’accès d’origine aurait expiré lorsque le travail postérieur à la session s’exécute. Dans ce scénario, vous avez besoin d’un cache (inter-zone) durable, partagé par plusieurs utilisateurs et/ou domaines et/ou applications SharePoint. Votre code doit donc utiliser des clés de cache qui distinguent l’utilisateur, le domaine SharePoint et/ou l’application, comme expliqué précédemment dans Mettre en cache le jeton d’accès.
Vous pouvez utiliser la clé de cache spécial qui est à l’intérieur du jeton de contexte à cet effet, tout comme vous l’avez utilisée pour le jeton d’accès (reportez-vous à la section suivante Comprendre la clé de cache).
Comprendre la clé de cache
La clé de cache est une chaîne opaque propre à la combinaison formée par l’utilisateur, l’émetteur du nom d’utilisateur, le complément et la batterie de serveurs SharePoint ou l’architecture SharePoint Online. Avant son chiffrement, elle présente la forme suivante, où Realm est le GUID de la batterie de serveurs SharePoint locale ou de l’architecture SharePoint Online.
UserNameId + « , » + UserNameIdIssuer + « , » + ApplicationId + « , » + Realm
La clé de cache ne contient pas les informations d’URL de site. Chaque architecture SharePoint Online (ou batterie de serveurs SharePoint locale) a un domaine unique. Par conséquent, la clé de cache est unique pour chaque combinaison regroupant le nom d’utilisateur, l’émetteur du nom d’utilisateur, l’application et la batterie de serveurs. Dans l’exemple du jeton de contexte, la valeur de la clé de cache chiffrée est la suivante :
KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=
Comme votre application peut mettre en cache plusieurs éléments, comme les deux jetons d’accès et de contexte dans le même cache avec la même clé de cache, songez à utiliser la clé de cache comme une ressource et à y ajouter, en préfixe ou non, une chaîne spécifique comme « AccessToken » ou « ContextToken » selon les besoins, pour former une clé de cache complète.
Une autre option consiste à créer une classe dotée de propriétés pour les divers éléments que vous souhaitez mettre en cache, puis à mettre en cache un objet de ce type.
La troisième option, si vous utilisez une base de données comme cache, consiste à utiliser une table avec une colonne CacheKey et des colonnes supplémentaires pour les éléments mis en cache (AccessToken, ContextToken, etc.).
Bien entendu, votre application n'est pas tenue d'utiliser le même cache pour tous les éléments. La pratique courante consiste à mettre en cache le jeton d’accès dans le cache de session, le jeton de contexte (ou le jeton d’actualisation qu’il contient) dans une base de données et la clé CacheKey dans un cookie.
Utiliser le jeton de contexte pour obtenir un jeton d’accès
Pour obtenir un jeton d'accès, votre application envoie une demande directement aux services ACS. La demande comprend trois éléments d'information qui sont extraits du jeton de contexte (en plus d'autres informations) :
- Le jeton d’actualisation
- Le GUID du principal d’application de SharePoint
- Le GUID de domaine de la batterie de serveurs SharePoint ou de l’architecture SharePoint Online à laquelle le complément cherche à accéder
Le fichier TokenHelper.cs (ou .vb) contient du code qui crée cette demande. Pour obtenir un exemple de code PHP qui effectue cette opération, voir SharePoint : Effectuer des opérations sur la bibliothèque de documents SharePoint à partir du site PHP.
L’application peut obtenir le domaine de l’architecture ou de la batterie de serveurs SharePoint lors de l’exécution en guise d’alternative à l’analyse à partir du jeton de contexte. Si vous utilisez du code managé, il existe une méthode TokenHelper.GetRealmFromTargetUrl pour obtenir le domaine. Veillez à bien mettre en cache la valeur pour que votre code n’effectue pas un autre appel réseau pour l’obtenir de nouveau.
Obtenir un nouveau jeton de contexte
Si vous avez besoin d’un nouveau jeton de contexte, généralement parce que le jeton d’actualisation (contenu dans les jetons de contexte) a expiré, votre code peut en obtenir un nouveau en redirigeant le navigateur vers une page spéciale sur tous les sites web SharePoint, AppRedirect.aspx. Deux paramètres de requête doivent être joints à l’URL de cette page :
client_id: ID client de votre Complément SharePoint.redirect_uri: URI vers lequel vous souhaitez que le navigateur soit redirigé après l'obtention du nouveau jeton de contexte. SharePoint PUBLIERA le jeton de contexte sur cet URI. Généralement, il s'agit de la même page, la méthode du contrôleur ou une méthode de service web qui a demandé le nouveau jeton de contexte. La valeur doit être codée au format URL.
La structure de l'URL doit être la suivante :
https://<SharePointDomain> /_layouts/15/appredirect.aspx?client_id=<app_client_GUID> &redirect_uri=<URL-encoded_redirect_URI>
L’exemple ci-dessous montre comment effectuer une demande dans ASP.NET en utilisant le fichier TokenHelper :
Response.Redirect(TokenHelper.GetAppContextTokenRequestUrl(sharePointUrl, Server.UrlEncode(Request.Url.ToString())));
Exemple d’un jeton de contexte
Voici un exemple de jeton de contexte. Le petit objet JavaScript Object Notation (JSON) dans la partie supérieure contient des métadonnées sur le jeton. Ces propriétés sont les mêmes que dans les jetons d’accès (voir précédemment). La valeur de la propriété alg est le nom de l’algorithme utilisé pour générer la signature qu’ACS ajoute au jeton. Consultez le Tableau 3 pour plus de détails sur les propriétés dans la charge utile du jeton. Notez que toutes les valeurs doivent être en minuscules. (Un espace blanc a été ajouté pour la lisibilité.)
{"typ":"JWT","alg":"HS256"}
.
{
"aud":"a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73",
"iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
"nbf":"1335822895",
"exp":"1335866095",
"appctxsender":"00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
"appctx":"{
\"CacheKey\":\"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\",
\"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
}",
"refreshtoken":"IAAAAC1Lv5w0OrcFAmJx0xk6aaBdhgsw3VPnPzNEDAWypTHtCYytZ2/dBBUKj+HLK8YB3IUCUfDxYpAque
NHKtgs4rYJJ5AegQpNMOJR1yYK8ngivQx0oetj7aSPuGVb+k6at6G0Kx5LZ5vhxkAq8iUSwu8p4L2cvNMzDF1mDKfMivqxgrIZkr2nbf9as0SJFL6VG5hZnDE4HKq
xJnejSW3umatKM4fsfY1MClVCxrkXb2EQ8H/TmwaJc388YW063GEVUS/3BTSgSIRBKQUmXJuJ6BZY7WTm84LaGrx3mIjnUTM/jnqPoPG55JbCC9sS/MeGNPtzPPCDg
6Vv7dVhQ1Dq5Y3fQ65e9LpJ580jCgzYYvpIFT+Wx5V+17mjY2T8wug04K2ts87Znsr+GfFCorf7NS/lj5HjoxRAQ2tva/8dwguSLwxcUwi/Q9MbpR0NNtlpwVazqi9O
hJ4Df7gVhUDdJ0Dtc6aFCPbl5ZLDDRs42xK2",
"isbrowserhostedapp": "true"
}
Les revendications aud, iss, nbf et exp sont exactement les mêmes que pour un jeton d’accès, tel que décrit dans le Tableau 1.
Les revendications appctxsender, appctx, CacheKey, SecurityTokenServiceUri, refreshtoken et isbrowserhostedapp sont décrites dans le tableau suivant.
Tableau 3. Revendications et informations de jeton de contexte
| Claim | Description | Valeur correspondante dans l’exemple de jeton de contexte |
|---|---|---|
aud |
a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73 |
|
iss |
00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73 |
|
nbf |
1335822895 |
|
exp |
1335866095 |
|
appctxsender |
Abrégé pour « expéditeur de contexte d’application ». Il représente l’application qui a envoyé le jeton de contexte au complément SharePoint. Il prend la forme GUID of principal@SharePoint realm, où GUID of principal correspond à l’ID constant du principal de l’application, qu’il s’agisse de SharePoint, d’Exchange, de Lync ou de Workflow. |
00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73 |
appctx |
Abréviation de « contexte de complément ». l s’agit d’un objet JSON contenant les éléments CacheKey et SecurityTokenServiceURI. | CacheKey:"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\", SecurityTokenServiceUri:"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\" |
CacheKey |
Valeur unique qui peut servir de clé à tout cache structuré au format clé/valeur pour stocker et récupérer le jeton de contexte. Cette valeur peut également être utilisée en tant que valeur d'une colonne de clé dans une ligne de base de données. | KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw= |
SecurityTokenServiceURI |
URI du service d’émission de jeton. | https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2 |
refreshtoken |
Le jeton d’actualisation pour le complément. | IAAAAC1Lv5w0OrcFAmJx0xk6??? |
isbrowserhostedapp |
Champ Boolean qui indique si la demande au complément qui contient le jeton de contexte émane d'un navigateur (true) ou d'un récepteur d'événements distant (false). | true |
Utiliser le jeton de contexte pour limiter l’accès aux seuls utilisateurs de SharePoint
Si vous souhaitez limiter l’accès à votre composant distant, tel qu’un service WCF, aux utilisateurs SharePoint, votre code peut simplement valider le jeton de contexte dans la requête HTTP. (Si vous utilisez du code managé, vous pouvez simplement appeler TokenHelper.ReadAndValidateContextToken()).
Votre code peut vérifier que la revendication d’acteur du jeton commence par 00000003-0000-0ff1-ce00-000000000000, si vous souhaitez vous assurer qu’il s’agit de SharePoint (et non, par exemple, d’Exchange, de Lync ou de Workflow). Si vous souhaitez effectuer une validation supplémentaire nécessitant un appel à SharePoint, comme la restriction de l’accès aux utilisateurs ayant un certain rôle dans SharePoint, vous pouvez mettre en cache le fait que vous avez effectué cette validation pour un utilisateur donné (à l’aide de la clé CacheKey du jeton de contexte) pour ne le faire qu’une seule fois.
Jetons d’actualisation
Un jeton d’actualisation est inclus dans le jeton de contexte que SharePoint publie pour votre application web lors de son lancement. Le jeton d’actualisation est un jeton chiffré que votre complément SharePoint ne peut pas déchiffrer. Votre code utilise de jeton, ainsi que d’autres informations, pour obtenir un nouveau jeton d’accès lorsque le jeton d’accès actuel a expiré. Il est également utilisé pour obtenir le premier jeton d’accès dans le flux du jeton de contexte. (Lorsque cet article a été rédigé, les jetons d’actualisation émis par ACS pour SharePoint avaient une durée de vie de six mois, mais cela pourrait changer).
Comme un jeton d’accès ne dure que quelques heures (12 actuellement) et qu’un utilisateur final en obtient un nouveau à chaque fois qu’il lance votre complément SharePoint depuis SharePoint, vous n’avez besoin du jeton d’actualisation que pour les scénarios suivants :
Les utilisateurs ouvrent des sessions longues au cours desquelles le complément effectue des appels vers SharePoint durant de nombreuses heures (actuellement plus de 12) après avoir été lancée.
La conception du complément permet aux utilisateurs de planifier le complément pour accéder à SharePoint pendant un certain temps après la fin de la session.
Les deux scénarios impliquent que votre complément mette en cache le jeton d’actualisation, et le second scénario nécessite un cache côté serveur durable pour toutes les sessions. Vos options de mise en cache sont identiques à celles proposées pour le jeton d’accès et, dans le flux du jeton de contexte, vous pouvez utiliser la clé de cache dans le jeton de contexte. (Dans le flux de jeton de contexte, il vous suffit de mettre en cache le jeton de contexte. Il contient le jeton d’actualisation et d’autres informations dont vous avez besoin pour obtenir un nouveau jeton d’accès. Dans le flux de code d’autorisation, il n’y a pas de jeton de contexte. Vous mettez donc en cache le jeton d’actualisation lui-même.)
Si vous mettez en cache le jeton d’actualisation dans un stockage qui persiste pour toutes les sessions d’un utilisateur donné dans votre complément, veillez à le remplacer par le dernier jeton d’actualisation en date. Dans les flux hébergé dans le cloud et du code d’autorisation, l’utilisateur obtient un nouveau jeton d’actualisation à chaque fois qu’il lance le complément.
Si le jeton d’actualisation a expiré, une demande pour un nouveau jeton d’accès auprès d’ACS entraîne une erreur 401 Non autorisé. Votre complément doit répondre à cette erreur en obtenant un nouveau jeton d’actualisation et en l’utilisant pour obtenir un nouveau jeton d’accès. (Comme le jeton d’actualisation est chiffré, votre code ne peut pas vérifier son expiration avant de l’utiliser.)
Dans le flux du jeton de contexte, votre complément obtient un nouveau jeton d’actualisation en obtenant un nouveau jeton de contexte. Dans le flux du code d’autorisation, votre complément obtient un nouveau jeton d’actualisation en redémarrant le flux. Plus précisément, votre code doit répondre à l’erreur en redirigeant l’utilisateur sur la page OAuthAuthorize.aspx de SharePoint, tel qu’expliqué à la section Comprendre le flux OAuth pour les compléments qui demandent des autorisations à la volée.
Codes d’autorisation
Dans le flux du code d’autorisation, le processus d’autorisation commence avec un code d’autorisation émis par ACS, à la demande de SharePoint. SharePoint transmet ensuite ce code à l’application à distance sous forme de paramètre de requête. Le code d’autorisation est propre à chaque paire formée par l’utilisateur et l’application à distance. (Lorsque cet article a été rédigé, les codes d’autorisation émis par ACS pour SharePoint avaient une durée de vie de 5 minutes, mais cela pourrait changer).
La logique dans votre application doit obtenir le code d’autorisation à partir du paramètre de requête et l’utiliser pour demander un jeton d’accès à ACS. Si vous utilisez du code managé, l’exemple de code permettant de créer le jeton se trouve dans le fichier TokenHelper.cs (et .vb). L’exemple de code permettant de lire le paramètre de requête se trouve dans Obtenir un exemple de code-behind pour une page accédant à SharePoint. ACS invalide le code d’autorisation immédiatement après l’émission du jeton d’accès, pour qu’il ne puisse être utilisé qu’une seule fois, et il n’est pas utile de le mettre en cache.
Valeurs de temps JWT
Les revendications nbf et exp sont au format spécifié par la spécification JWT. Elles sont rédigées sous la forme du nombre de secondes écoulées depuis le 1er janvier 1970. Dans C#, vous pouvez traduire ces valeurs avec le code suivant, où jWTTimeStamp est la valeur provenant du jeton, comme 1335822895.
DateTime exp = new DateTime(1970,1,1).AddSeconds(jWTTimeStamp);
Résolution des problèmes de gestion de jeton
L’outil Fiddler gratuit peut être utilisé pour capturer les demandes HTTP envoyées par le composant à distance de votre complément à SharePoint. Il existe une extension gratuite de l’outil qui décode automatiquement les jetons dans les requêtes.