Autorisations

Vue d’ensemble

En tant qu’admin système Workplace, vous pouvez contrôler les fonctionnalités offertes à chaque intégration en créant des applications et en leur accordant des autorisations spécifiques. Chaque application peut être nommée de manière à refléter le service qu’elle active. Les applications sont fournies avec des tokens d’accès et autorisations uniques qui déterminent les informations qu’elles peuvent lire ou écrire.

Ce guide décrit en détail le modèle d’application et d’autorisation.

Commandes d’autorisation lors de la modification d’une application d’intégration personnalisée

Autorisations disponibles

Chaque application Workplace peut se voir accorder son propre ensemble d’autorisations, qui contrôle le niveau de fonctionnalités auquel elle a accès dans l’API Graph et l’API de gestion des comptes.

Lorsque vous créez une application et que vous accordez des autorisations, celles-ci sont appliquées à chaque compte de votre communauté. Les détenteurs d’un compte n’ont pas besoin d’accorder d’autorisations supplémentaires à l’application pour bénéficier de ses fonctionnalités. Cette approche diffère du modèle d’autorisation sur Facebook, dans lequel chaque utilisateur accorde des autorisations de manière individuelle à une application lorsqu’il se connecte.

Vous trouverez ci-dessous la liste complète des autorisations d’application disponibles pour les intégrations, avec une description de leurs modes d’utilisation.

Autorisations au niveau du groupe

Dans le cas de certaines autorisations, il est possible de limiter l’activation d’une intégration à des groupes spécifiques. Cela vous permet de restreindre l’accès d’une intégration au contenu que vous souhaitez exposer.

Par exemple, vous pouvez faire en sorte qu’une intégration de publication d’alertes ne puisse publier du contenu que dans le groupe d’une équipe, ou qu’une intégration d’application pour employés puisse uniquement lire le contenu de groupes ouverts spécifiques.

Pour spécifier les autorisations au niveau du groupe d’une intégration personnalisée, utilisez la boîte de dialogue Définissez les accès des groupes à l’intégration.

Activation d’une autorisation au niveau du groupe pour cette intégration

Les autorisations au niveau du groupe s’appliquent aux autorisations suivantes :

• Lire le contenu du groupe : permet de lire les publications, les commentaires et les profils de membre dans les groupes sélectionnés
• Gérer le contenu du groupe : permet de gérer les publications et les commentaires dans les groupes sélectionnés
• Gérer les groupes : permet de modifier ou de supprimer les groupes sélectionnés et leurs membres

Vous pouvez choisir entre trois options pour configurer les autorisations au niveau du groupe d’une intégration : Tous les groupes, Groupes spécifiques (choisis par un admin système) ou Permettre aux admins de groupes de l’activer pour leurs groupes.

Flux d’installation admin

Si l’autorisation Permettre aux admins de groupes de l’activer pour leurs groupes est activée, l’admin d’un groupe voit s’afficher un nouvel onglet Intégrations sous l’écran Gérer le groupe, qui lui permet d’activer l’intégration sur son groupe.

Exemple d’application pouvant à présent être activée par l’admin du groupe

Tokens et utilisation des applications

Lorsque vous créez une application pour Workplace, cette opération génère un token d’accès destiné à être utilisé avec l’API Graph, l’API Account Management ou les webhooks.

Ce token d’accès n’apparaît qu’une seule fois. Vous devez donc l’enregistrer dans un endroit sûr pour pouvoir le réutiliser par la suite dans le code.

Flux de réinitialisation du token pour une application d’intégration personnalisée

Les tokens d’application Workplace n’arrivent jamais à expiration et n’ont pas besoin d’être actualisés, sauf s’ils ont été réinitialisés manuellement. Si vous modifiez les autorisations disponibles pour une application donnée, le token existant continue de fonctionner, et vous n’avez donc pas à en générer un autre.

Si vous avez besoin d’invalider un token, vous pouvez le réinitialiser via le bouton Réinitialiser le token d’accès de la boîte de dialogue Modifier l’application. Un nouveau token est généré et affiché, et le token existant est aussitôt invalidé.

Sécurité des tokens

Les tokens d’accès sont particulièrement puissants. Ils accordent l’accès aux données de votre entreprise sur Workplace. Lorsque vous créez une application, déterminez l’ensemble minimal d’autorisations nécessaires pour implémenter les fonctionnalités d’intégration, et n’accordez pas d’autorisations superflues.

Lorsque vous stockez des tokens ou que vous les ajoutez à des référentiels de code, évitez impérativement de les partager avec des personnes non autorisées.

Pour mettre en place une couche de sécurité supplémentaire pour les intégrations, ajoutez une liste blanche d’adresses IP, qui restreindra l’utilisation des tokens aux serveurs figurant sur cette liste.

Ajout d’une liste blanche d’adresses IP restreignant l’utilisation des tokens aux serveurs spécifiés et exigence d’une preuve de clé secrète

Retrait automatique des autorisations inutilisées

Si une intégration personnalisée ne fait jamais appel à une autorisation spécifique sur une période de 30 jours, cette autorisation est retirée. Lorsqu’une intégration personnalisée a fait une fois l’objet d’un retrait de ce type, une option permet de désactiver ce processus de retrait.

Si un abonnement webhook valide a été configuré, les webhooks envoyés par ce dernier comptent comme une utilisation de l’autorisation correspondante.

Commandes de retrait automatique des autorisations

Preuve de clé secrète

Les tokens d’accès pour Workplace n’arrivent jamais à expiration. Les intégrations personnalisées peuvent ajouter une couche de sécurité supplémentaire en exigeant une preuve de clé secrète. L’activation de l’option Exiger une preuve de clé secrète garantit que les appels d’API sont systématiquement effectués à partir d’un code côté serveur. Une preuve de clé secrète avec date d’expiration sera alors requise avec le token d’accès lors de l’exécution des appels d’API.

Pour générer une preuve de clé secrète avec date d’expiration, vous devez concaténer le token avec un horodatage UNIX, séparé par une barre verticale |, puis créer un hachage SHA-256 de la chaîne concaténée en utilisant votre clé secrète en tant que clé. En voici un exemple en PHP :

$appsecret_proof = hash_hmac('sha256', $access_token.'|'.time(), $app_secret); 

Pour effectuer des appels d’API avec votre preuve de clé secrète, transmettez en même temps que votre token d’accès le hachage généré via le paramètre appsecret_proof, avec le paramètre appsecret_time défini sur l’horodatage que vous avez utilisé lors du hachage de la clé secrète.

GET https://graph.facebook.com/v2.9/community/groups?
&access_token={access-token}
&appsecret_proof={appsecret_proof}
&appsecret_time={appsecret_time}

Découverte des fonctionnalités d’API avec Postman

Postman est un outil communément utilisé avec les API Web. Postman se révèle pratique pour explorer l’API Workplace. Toutefois, le paramètre $appsecret_proof présente une complication, puisque cette valeur doit être calculée et arrive à expiration au bout de cinq minutes. Cela simplifierait donc les choses si Postman pouvait générer cette valeur au moment de la requête. Il s’avère que Postman peut effectuer cette opération à l’aide de ses scripts de pré-requêtes et fonctionnalités de paramètres. Vous pouvez utiliser le script ci-dessous comme point de départ :

// Add to Postman's Pre-request Script Tab
var access_token = "replace-me";
var app_secret = "replace-me";
var time = (new Date().getTime()/1000|0);
postman.setEnvironmentVariable("access_token", access_token)
postman.setEnvironmentVariable("appsecret_time", time);
postman.setEnvironmentVariable("appsecret_proof", CryptoJS.HmacSHA256(access_token + '|' + time, app_secret));

1) Créez un environnement actif (il n’en existe pas par défaut). 2) Puis, ajoutez ces trois paramètres qui sont calculés par votre script de pré-requête.