Créer et utiliser des jetons d’accès dans des compléments SharePoint à niveau de confiance élevé hébergés par un fournisseur

Les compléments SharePoint qui utilisent le système d’autorisation à haut niveau de fiabilité pour accéder à SharePoint doivent transmettre un jeton d’accès (au format JSON Web Token) pour SharePoint avec chaque demande de création, de lecture, de mise à jour ou de suppression (CRUD). SharePoint valide le jeton et effectue la demande.

Cet article fournit des informations sur la manière dont votre code crée et transmet le jeton d’accès.

Dans le système d’autorisation à haut niveau de fiabilité, le composant à distance de votre complément SharePoint crée le jeton d’accès. Si le composant à distance utilise du code managé pour son code côté serveur, la majeure partie du codage pour créer les jetons est faite pour vous dans les fichiers SharePointContext.cs (ou .vb) et TokenHelper.cs (ou .vb) qui sont inclus dans les Outils de développement Office pour Visual Studio.

Comme le client d’un complément SharePoint à haut niveau de fiabilité dispose de SharePoint en local, il n’est probablement pas réticent à utiliser ASP.NET, IIS et Windows Server comme pile d’hébergement pour le composant à distance. Vous devez envisager d’utiliser cette pile car les deux fichiers générés vous permettent d’économiser beaucoup en main-d’œuvre de codage et de test.

Si le composant à distance doit utiliser une langue non-.NET, et si le composant à distance et la batterie de serveurs SharePoint sont connectés à Internet, vous devez envisager d’utiliser le système d’autorisation à bas niveau de fiabilité au lieu du haut niveau de fiabilité. Dans le système Microsoft Azure Access Control Service (ACS), toute la création des jetons est réalisée par ACS, de telle sorte que vous économisez beaucoup de travail.

Le reste de cet article est principalement destiné à fournir des conseils aux développeurs qui créent des compléments SharePoint avec des composants à distance non-.NET et qui utilisent le système d’autorisation à haut niveau de fiabilité. Il peut également fournir certaines informations utiles pour le débogage de compléments SharePoint basés sur .NET, qui utilisent le système à haut niveau de fiabilité.

Gestion des jetons d’accès

Les détails dans cette rubrique sont fournis pour aider les développeurs qui n’utilisent pas du code managé (et pour aider ceux qui résolvent des problèmes avec les jetons). Des liens vers des bibliothèques OAuth pour de nombreuses langues et plates-formes sont disponibles sur le site OAuth 2.0 (faites défiler jusqu’à Client Libraries). Vous trouverez plus d’informations en recherchant « OAuth 2 » et « JSON Web Token » (sans les guillemets) sur le site GitHub.

Votre code doit :

1. Créer un jeton d’accès. Les tâches subordonnées pour la création de ce jeton varient selon si l’application web à distance effectue des appels complément uniquement, des appels utilisateur+complément ou les deux, vers SharePoint. (Pour plus d’informations, consultez la rubrique Types de stratégie d’autorisation des compléments dans SharePoint.)

   • Si le complément effectue des appels utilisateur+complément, la création du jeton d’accès comprend les tâches subordonnées suivantes :

     1. Créer un jeton acteur qui identifie le complément SharePoint et indique à SharePoint de déléguer l’authentification et l’autorisation des utilisateurs à votre complément, et de l’encoder en base 64. Les détails sur les revendications et la structure du jeton acteur se trouvent dans le Tableau 2. Les détails concernant le codage et la signature du jeton sont disponibles à la section Encoder et signer des jetons.
     2. Signer le jeton acteur avec des informations d’identification provenant d’un certificat X.509 configuré par un administrateur de la batterie de serveurs SharePoint pour que SharePoint l’approuve.
     3. Intégrer le jeton acteur dans le jeton d’accès.
     4. Ajouter d’autres revendications requises au jeton d’accès. Les détails sur les revendications et la structure du jeton se trouvent dans le Tableau 1.

   • Si le complément effectue des appels complément uniquement, votre code doit seulement effectuer les deux premières tâches subordonnées de cette liste. Le jeton acteur sert de jeton d’accès.

   • Si le complément effectue des appels utilisateur + complément et des appels complément uniquement, il doit créer un jeton acteur simple pour les appels complément uniquement, et un jeton d’accès imbriqué plus étendu pour les appels utilisateur + complément. Un même jeton d’accès ne peut pas être utilisé pour les deux appels.

2. Incluez le jeton d’accès dans chaque requête HTTP adressée à 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.

3. Mettre en cache le jeton d'accès pour le réutiliser lors de demandes ultérieures (facultatif).

Ces tâches doivent être effectués avec le code côté serveur. Si vous utilisez du code managé, l’exemple de code pour certaines de ces tâches se trouve dans les fichiers SharePointContext.cs (ou .vb) et TokenHelper.cs (ou .vb) générés par les outils de développement Microsoft Office pour Visual Studio.

Mettre en cache le jeton d’accès

Une fois le jeton créé, il peut être réutilisé lors d’appels ultérieurs vers SharePoint jusqu’à ce qu’il expire. Selon l’architecture et la plate-forme d’hébergement du composant à distance, 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
• Dans une base de données
• Dans un système memcached

Si le stockage de cache est partagé par différentes sessions utilisateur, comme le cache de l’application, veillez à utiliser une clé de cache propre à la session.

Si le cache est partagé par plusieurs applications, votre code doit également relativiser la clé de cache pour cette variable. Il est également possible que votre complément accède à différentes batteries de serveurs SharePoint. Vous avez besoin de jetons d’accès distincts pour chacune d’elles. Ainsi, dans ce scénario, votre clé de cache doit être relativisée pour la batterie de serveurs.

De plus, vous aurez peut-être besoin de clés de cache basées sur un ou plusieurs ID d’utilisateur et ID d’application, et sur un ou plusieurs domaines SharePoint. Envisagez l’utilisation d’un système de clés de cache similaire à celui utilisé par les compléments SharePoint qui utilisent le système d’autorisation à bas niveau de fiabilité. Pour plus d’informations, consultez la rubrique Comprendre la clé de cache.

Au fond, vous devez concaténer un ou plusieurs de ces trois ID (et éventuellement hacher le résultat en une chaîne plus courte) pour servir de clé de cache.

Gérer les jetons d’accès arrivés à expiration

Le jeton d’accès possède un délai d’expiration que votre code peut définir sur n’importe quelle valeur souhaitée. Si votre complément crée un nouveau jeton d’accès pour chaque demande, chaque jeton doit uniquement exister suffisamment longtemps pour être validé par SharePoint, pas plus de quelques secondes, sauf si le réseau local du client est généralement congestionné. Vous pouvez définir l’expiration sur des années futures, mais même dans le scénario « tout en local » pour lequel les compléments à haut niveau de fiabilité sont conçus, il existe certains dangers liés au vol des jetons d’accès. Vous devez donc envisager de définir l’expiration sans aller au-delà de quelques heures. (Si vous travaillez avec du code managé, l’exemple de code de création de jeton dans le fichier TokenHelper.cs [ou .vb] définit l’expiration sur 12 heures.)

Si la session d’un utilisateur avec votre complément SharePoint dure plus longtemps que la durée de vie du jeton d’accès mis en cache, la première demande à SharePoint après l’expiration du jeton entraîne une erreur 401 Non autorisé. Votre code doit gérer cette réponse. Par ailleurs, il peut tester le délai d’expiration du jeton d’accès avant de l’utiliser. Votre code doit répondre à un jeton d’accès expiré en créant un nouveau jeton d’accès et en répétant la demande qui a échoué.

Structure des jetons d’accès

L’exemple qui suit concerne un jeton d’accès généré par un complément SharePoint à haut niveau de fiabilité. Plus précisément, ce jeton a été généré par l’exemple de code du fichier TokenHelper.cs (ou .vb), qui fait partie du modèle de projet de complément SharePoint créé par les Outils de développement Office pour Visual Studio. Le jeton a été décodé et un espace blanc a été ajouté pour la lisibilité. Les jetons d’accès utilisés dans le système à haut niveau de fiabilité sont conformes au MS-SPS2SAUTH : protocole d’authentification OAuth 2.0 : Profil SharePoint, qui est également appelé protocole de serveur à serveur ou S2S. Ces informations sont fournies pour permettre aux développeurs utilisant du code managé de déboguer des compléments SharePoint à haut niveau de fiabilité et pour fournir quelques conseils aux développeurs utilisant d’autres langages pour créer les jetons.

Ce jeton d’accès est généré si le complément effectue un appel à SharePoint en utilisant la stratégie utilisateur+complément. Si le complément utilise la stratégie complément uniquement et s’il effectue un appel complément uniquement avec SharePoint, le jeton acteur (qui est un jeton enfant compris dans le jeton d’accès utilisateur+complément, dont la description est disponible ci-dessous) devient le jeton d’accès (et il n’existe pas de jeton parent).

L’en-tête compte deux propriétés. L’élément « typ » correspond au type de jeton. Le code dans l’application web à distance doit toujours définir cette valeur sur « JWT ». L’élément « alg » est l’algorithme utilisé pour signer le jeton. Comme le jeton externe d’un appel utilisateur+complément provenant d’un complément à haut niveau de fiabilité n’est pas signé, définissez cette valeur sur « none ». Consultez le Tableau 1 pour plus d’informations sur les valeurs dans la partie corps du jeton d’accès à haut niveau de fiabilité.

{"typ":"JWT", "alg":"none"} 
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"s-1-5-21-2127521184-1604012920-1887927527-2963467",
 "nii":"urn:office:idp:activedirectory",
 "actortoken":"6sMZhbw … [remainder of long base 64 string omitted] … "
}

Le tableau suivant fournit quelques conseils quant aux propriétés que votre code doit inclure dans le jeton d’accès et aux valeurs à définir pour ces propriétés. Si vous utilisez du code managé, les fichiers SharePointContext.cs (ou .vb) et TokenHelper.cs (ou .vb) créent les jetons pour vous. Par exemple, votre code effectue un appel unique à la méthode SharePointContext.CreateUserClientContextForSPHost. Il appelle, en retour, les méthodes de la classe TokenHelper qui construisent le jeton d’accès, qui est ensuite incluse dans chaque appel effectué vers SharePoint par l’objet de contexte client SharePoint renvoyé par SharePointContext.CreateUserClientContextForSPHost.

Tableau 1 : Revendications de jetons d’accès de complément émis par une application

L’exemple suivant montre l’élément actortoken décodé. Le petit objet d’en-tête JavaScript Object Notation (JSON) de la partie supérieure contient des métadonnées sur le jeton, notamment le type de jeton et l’algorithme utilisé pour le signer. La propriété x5t de l’en-tête est une synthèse effectuée à partir de l’empreinte numérique du certificat X.509 qui est officiellement l’émetteur du jeton. Pour créer cette valeur, votre code effectue les opérations suivantes :

1. Obtenir la version tableau d’octets (et non chaîne) de l’empreinte numérique du certificat. Il s’agit d’une synthèse SHA-1 du certificat. (Dans le code managé, cette opération peut être effectuée avec la méthode GetCertHash(). Vous avez besoin d’un équivalent dans le langage que vous utilisez.)

2. Encodez le tableau d’octets en URL base 64.

3. Définition de la valeur de la propriété x5t sur le chiffrement encodé.

Le tableau 2 décrit les revendications que votre code doit inclure dans le corps du jeton et les valeurs à définir pour celles-ci.

{"typ":"JWT","alg":"RS256","x5t":"7MjK99QvkVdwz6UrKldx8AG7ydM"}
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "trustedfordelegation":"true"
}

Tableau 2 : Revendications actortoken émises par un certificat

Codage et signature de jetons

Après que votre code a ajouté toutes les propriétés et valeurs aux objets JSON d’en-tête et de corps, il doit les encoder, les combiner pour former un JSON Web Token (JWT) et signer ce dernier. Voici la marche à suivre.

1. Encodez l’en-tête en URL base 64.
2. Encodez la charge utile en URL base 64.
3. Concatènez le corps encodé après l’en-tête codé avec un caractère « ». Il s’agit du JWT.
4. Créez une signature SHA256 en utilisant le JWT et la clé privée du certificat.
5. Encodez la signature en URL base 64.
6. Ajoutez la signature à la fin du JWT en insérant le caractère « . » entre les deux.

Pour un jeton acteur utilisé pour un appel complément uniquement, le jeton acteur sert de jeton d’accès. Il n’y a pas de jeton externe. Pour un jeton d’accès utilisé pour un appel utilisateur+complément, les étapes précédentes permettent de créer un jeton acteur, qui est ensuite inséré dans le corps d’un jeton d’accès comme valeur de la propriété actortoken. Le jeton d’accès complet est ensuite codé et créé selon les trois premières étapes décrites ci-dessus, mais il n’est pas signé, de telles sorte que les étapes restantes ne sont pas utilisées pour le jeton externe.

Résolution des problèmes de jetons d’accès

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.

Voir aussi

• Article de Steve Peschka, Sécurité dans les compléments SharePoint - Partie 7
• Article de Kirk Evan, Compléments SharePoint à haut niveau de fiabilité sur les plates-formes autres que Microsoft
• OAuth 2.0
• Types de stratégie d’autorisation des compléments dans SharePoint
• Création de compléments pour SharePoint qui utilisent l’autorisation à haut niveau de fiabilité
• Autorisation et authentification des compléments dans SharePoint