Aperçus authentifiés

Présentation

Les aperçus authentifiés garantissent l’affichage correct de l’aperçu de votre contenu sur Workplace. Cela implique de prendre en charge des métadonnées d’aperçu authentifié dans un format reconnu par Workplace, pour que lors du partage des URL de votre contenu, Workplace puisse extraire ces métadonnées et créer un aperçu. Ce processus est souvent désigné sous le terme de déploiement de liens.

Si Facebook peut obtenir les métadonnées pour déployer une URL publique via le protocole Open Graph et le robot d’indexation Facebook, ce processus est impossible pour les URL privées qui sont plus fréquemment partagées dans Workplace. Lorsqu’une personne partage une URL privée dans Workplace, un webhook est généré vers une URL de rappel que vous définissez. Vous êtes alors en mesure de répondre avec une charge utile de métadonnées décrivant l’URL pour la personne qui la partage, de manière à afficher un aperçu du lien.

Le même processus se répète pour chaque personne visualisant l’URL partagée sur Workplace, ce qui vous offre la possibilité de contrôler la visibilité des aperçus par utilisateur.

Les aperçus authentifiés pour Workplace permettent aux personnes de partager des informations sur Workplace facilement et en toute sécurité, dans le respect de la confidentialité du contenu source. En prenant en charge les aperçus authentifiés, vous avez l’assurance que les aperçus de vos contenus s’affichent correctement sur Workplace, de manière sécurisée et respectueuse de la confidentialité.

Partage d’URL privées

Sur Workplace, les utilisateurs partagent souvent des liens vers des ressources d’entreprise internes, que seules certaines personnes peuvent consulter. Sur Facebook, au contraire, les utilisateurs partagent fréquemment du contenu public, comme des articles de presse ou des publications de blog.

URL publiques et privées sur Workplace

Pour permettre à Workplace de générer l’aperçu d’un contenu d’entreprise privé, il convient de lui fournir certaines métadonnées. En tant que fournisseur, vous pouvez choisir de fournir ou non les métadonnées pour la personne qui consulte Workplace, selon qu’elle est ou non autorisée à visualiser le contenu.

Dans ce document

Ce document présente les composants requis pour l’activation des aperçus authentifiés, à savoir :

• Aperçus authentifiés
• Mappage d’identité

Configuration

Pour activer les aperçus authentifiés, vous devez configurer votre application comme suit :

• Installation sur une communauté Workplace, ou dans un ou plusieurs groupes
• Autorisation de déploiement de liens
• Domaine ou ensemble de domaines comprenant les URL qui seront déployées par votre intégration
• Abonnement à la section Lien du webhooks pour l’aperçu du champ, et URL de rappel pour la fourniture des métadonnées

Webhooks

Réception de webhooks

Nous envoyons une requête au fournisseur dans différentes situations :

1. Une nouvelle URL que nous n’avons pas encore vue est partagée (toujours depuis l’éditeur).
2. Un nouvel utilisateur consulte un contenu alors que nous ignorons s’il y a accès (toujours depuis le fil).
3. Un contenu est partagé de nouveau ou est arrivé à expiration (soit depuis l’éditeur, soit depuis le fil).

Format de requête de webhook

Dans tous ces cas de figure, un webhook est envoyé sous la forme d’une requête POST au format suivant :

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "preview",
          "value": {
            "community": {
              "id": string,
            },
            "user": {
              "id": string,
            },
            "link": string,
          }
        }
      ]
    }
  ]
}
    

Cette charge utile contient les champs suivants :

Exemple

POST /callback HTTP/1.1
Host: third-party.com
Accept: application/json
Content-Type: application/json
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587
...

{
    "object": "link",
    "entry": [{
        "time": 1501515097793,
        "changes": [{
            "field": "preview",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
                "link": "https://company.third-party.com/document-about-this"
            }
        }]
    }]
}
    

Format de réponse de webhook

Lorsque vous recevez une requête de webhook, vous devez fournir une charge utile de métadonnées dans un format de réponse spécifique :

{
  "data": [
    {
      "link": string,
      ?"canonical_link": string,
      ?"title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": 'organization' | 'accessible' | 'inaccessible',
      ?"type": 'document' | 'folder' | 'task' | 'link',
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
          ?"color" => 'blue' | 'green' | 'yellow' | 'orange' | 'red',
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

Cette charge utile doit contenir les champs suivants :

Exemple de réponse complète

HTTP/1.1 200 OK
Content-Type: application/json
X-Hub-Signature: sha1=b5a6f32f084100ae5b355174b9bb8398f5fbe983
...

{
  "data": [
    {
      "link": "https://taaskly.herokuapp.com/task/4",
      "title": "Launch Workplace Integration for F8",
      "privacy": "organization",
      "type": "task",
      "additional_data": [
        {
          "title": "Owner",
          "format": "user",
          "value": "319922278498384"
        },
        {
          "title": "Created",
          "format": "datetime",
          "value": "2018-02-28T03:35:40.827Z"
        },
        {
          "title": "Priority",
          "format": "text",
          "value": "high",
          "color": "red"
        }
      ]
    }
  ],
  "linked_user": true
}
    

Modes de confidentialité

Le mode de confidentialité détermine la visibilité, qui indique si nous exigeons ou non l’authentification de l’utilisateur actuel et des utilisateurs suivants.

1. organization : contenu visible par l’utilisateur, aucune authentification des utilisateurs requise
   Si le contenu est visible par l’utilisateur, nous pouvons l’afficher directement. Cette valeur prend en charge les cas dans lesquels un contenu est censé être visible par tous les membres du domaine (entreprise). Nous n’envoyons pas de webhook chaque fois qu’une autre personne consulte le nouveau contenu.
2. accessible : contenu visible par l’utilisateur actuel, mais un mappage d’identité d’utilisateur peut être requis pour les autres personnes
   Le fournisseur sait que cet utilisateur est autorisé à consulter ce contenu, mais cela ne signifie pas nécessairement que le contenu soit visible par d’autres personnes. Nous affichons l’aperçu, mais nous continuons à envoyer des webhooks pour tous les autres utilisateurs.
3. inaccessible : contenu non visible par l’utilisateur
   Le fournisseur connaît l’utilisateur et sait que celui-ci n’est pas autorisé à consulter le contenu. Nous affichons un avis de confidentialité (non disponible, privé, etc.).

Données supplémentaires

Si vous souhaitez ajouter d’autres informations sur l’aperçu d’un lien, vous pouvez envoyer jusqu’à trois éléments de données supplémentaires. Un élément de données supplémentaires comporte un ensemble d’éléments de valeurs clés. Mais la valeur peut présenter différents formats.

Pour l’instant, quatre formats sont pris en charge :

• text : affiche la valeur telle quelle. La valeur doit être une chaîne. Dans le cas de ce format, les données supplémentaires peuvent également comporter une propriété color, qui doit présenter la valeur blue, green, yellow, orange ou red. Si cette propriété est indiquée, ce format affiche la valeur en utilisant cette couleur en arrière-plan.
• date : analyse la valeur en tant que format de date ISO-8601 sans heure et l’affiche sans indication d’heure.
• datetime : analyse la valeur en tant que format de date ISO-8601 avec heure et fuseau horaire, et l’affiche avec indication d’heure dans le fuseau horaire des utilisateurs.
• user : analyse la valeur en tant qu’identifiant utilisateur et affiche le nom de l’utilisateur.

Si des données supplémentaires sont définies, le paramètre download_url est ignoré.

Affichage des aperçus de fichiers (facultatif)

Si le mode de confidentialité de votre document présente la valeur organization ou accessible, et qu’une URL de téléchargement est fournie, nous envoyons une requête supplémentaire concernant le téléchargement des données.

GET /download/super-fancy-document HTTP/1.1
Host: provider.com
Accept: <some mime types>
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587

Workplace convertira alors ce fichier en photos pour en générer une publication contenant plusieurs photos.

Mappage d’identité

Comme indiqué ci-dessus, la fourniture d’aperçus authentifiés requiert un mappage d’identité. Le mappage d’identité détermine si un utilisateur Workplace est autorisé à consulter le contenu dont l’aperçu s’affiche, et garantit le respect des règles d’accès de votre contenu sur Workplace.

Mappage à l’échelle de l’organisation

La forme de mappage d’identité la plus simple est le mappage à l’échelle de l’organisation, pour lequel il suffit d’appartenir à une communauté Workplace pour autoriser la présentation des aperçus aux utilisateurs sur Workplace. Ce scénario est courant en cas d’affichage de l’aperçu des liens dans un intranet d’entreprise, ou dans un service dans lequel tous les objets (ou au moins leurs métadonnées) sont visibles par la totalité de l’entreprise.

Lorsque votre intégration est installée sur une communauté Workplace, vous pouvez vérifier l’ID de communauté via le point de terminaison /community, à l’aide du token d’accès que vous avez récupéré lors de l’installation. Vous pouvez stocker cet ID de communauté avec le token, et le mapper sur un identifiant de locataire ou d’organisation dans votre service. Cette opération crée un mappage entre une communauté Workplace et l’organisation dans votre service.

Par la suite, lorsque vous répondez aux requêtes de webhook d’aperçu authentifié, vous pouvez vérifier que l’ID de communauté de la charge utile du webhook correspond à l’ID de communauté associé à l’organisation. Cela vous permet alors de décider si vous pouvez renvoyer une charge utile de métadonnées en toute sécurité. La définition de la confidentialité de cette charge utile sur la valeur ORGANIZATION nous évite d’avoir à envoyer des webhooks supplémentaires pour chaque utilisateur de cette communauté Workplace.

Mappage par utilisateur

Si vous avez besoin d’autorisations plus granulaires, vous pouvez prendre en charge un mappage par utilisateur ; cela vous permet d’afficher ou non les métadonnées pour chacune des personnes qui consulte du contenu sur Workplace. Workplace envoie un identifiant utilisateur dans chaque charge utile de webhook pour les aperçus authentifiés. Pour prendre en charge le mappage par utilisateur, vous devez savoir à quelle entrée utilisateur de votre système correspond l’identifiant utilisateur Workplace envoyé dans la charge utile de webhook.

Si vous rencontrez un identifiant utilisateur Workplace donné pour la première fois, vous pouvez répondre en définissant le champ linked_user sur false. Workplace sera chargé d’afficher un bouton Activer l’aperçu qui invite l’utilisateur à associer son compte.

Lorsque ce bouton est sélectionné, Workplace affiche une boîte de dialogue d’un point de terminaison d’association de compte que vous définissez, et qui vous permet de valider la session utilisateur dans votre service. Workplace ouvre cette URL via une requête POST et transmet un paramètre de requête signé, qui contient l’identifiant utilisateur et l’ID de communauté actuels.

POST https://www.example.com/account_linking?redirect_uri=https%3A%2F%2Ffoxfabrics.facebook.com%2Flink_complete HTTP/1.1
Host: foxfabrics.third-party.com
Origin: http://www.facebook.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
...

signed_request=238fsdfsd.oijdoifjsidf899
    

La charge utile comporte un paramètre signed_request qui contient des informations sur cet utilisateur. Cette requête peut être décodée comme suit :

1. Divisez le contenu en deux parties, délimitées par un caractère « . ».
2. Décodez la première partie (la signature) avec base64url.
3. Décodez la seconde partie (la charge utile) avec base64url, puis décodez l’objet JSON résultant.
4. Vérifiez que la signature correspond à l’algorithme HMAC de la charge utile encodée basée sur votre clé secrète.

La charge utile contient les champs suivants :

{
  "algorithm": "HMAC-SHA256",
  "user_id": "88575656148087",
  "community_id": "138169208138649"
}
    

À ce stade, vous disposez d’un ID utilisateur et d’un ID de communauté Workplace, ainsi que d’une session utilisateur validée dans votre service, et vous êtes en mesure d’enregistrer l’ID Workplace de cet utilisateur à côté de son identifiant dans votre service. Une fois cette opération effectuée, vous devez inclure une redirection vers l’URL fournie dans la requête initiale en tant que paramètre de requête redirect_uri.

GET {$redirect_uri} HTTP/1.1
Host: foxfabrics.facebook.com
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
Referer: https://www.example.com/account_linking
...
    

Workplace détecte alors que le mappage d’identité est terminé, et tente de redemander les métadonnées d’aperçu authentifié. Cette fois-ci, vous êtes en mesure de répondre en définissant le champ linked_user sur true, et vous pouvez fournir les métadonnées requises.

Questions/réponses