Prévias autenticadas

Visão geral

As prévias autenticadas mostram a visualização correta do seu conteúdo no Workplace. Isso implica oferecer compatibilidade com metadados de prévia autenticada em um formato esperado pelo Workplace; desse modo, quando os URLs do seu conteúdo são compartilhados, o Workplace pode buscar esses metadados e criar uma prévia. Esse processo normalmente é chamado de autenticação de link.

Embora o Facebook consiga obter metadados para autenticar URLs públicos por meio do protocolo Open Graph e do Rastreador do Facebook, não é possível realizar esse processo em URLs privados, que são compartilhados com mais frequência no Workplace. Quando alguém compartilha um URL privado no Workplace, um webhook é emitido para um URL de retorno de ligação que você definiu; assim, você poderá responder com uma carga de metadados descrevendo o URL da pessoa que está compartilhando para renderizar uma prévia do link.

O mesmo processo será repetido para cada pessoa que visualizar o URL compartilhado no Workplace, permitindo que você controle a visibilidade da prévia por usuário.

O recurso Autenticado para o Workplace permite que as pessoas compartilhem informações com segurança e facilidade no Workplace, de forma que respeite a privacidade do material de origem. Ao oferecer compatibilidade com as prévias autenticadas, é possível garantir que as prévias do seu conteúdo sejam exibidas corretamente no Workplace, com segurança e privacidade.

Compartilhar URLs privados

No Workplace, são compartilhados links para recursos internos das empresas, que só podem ser visualizados por determinadas pessoas. Por outro lado, no Facebook, as pessoas compartilham conteúdo público, como artigos de notícias ou publicações de blog.

URLs públicos e privados no Workplace

Para que o Workplace gere uma prévia do conteúdo privado de uma empresa, alguns metadados precisam ser fornecidos. Como fornecedor, você pode escolher se deseja fornecer metadados para o visualizador atual no Workplace, embora ele precise de permissão para ver o conteúdo.

Sobre este documento

Este documento descreve os componentes para habilitar as prévias autenticadas, incluindo:

• Prévias autenticadas
• Mapeamento de identidade

Configuração

Para habilitar as prévias autenticadas, você precisará definir as seguintes configurações no app:

• Instalação em uma comunidade do Workplace ou em um ou mais grupos
• A permissão Autenticação de link
• Um domínio ou um conjunto de domínios, incluindo os URLs que serão autenticados pela integração
• Uma assinatura para o link do tópico do webhook, para a prévia do campo e um URL de retorno de chamada para fornecer metadados

Webhooks

Receber Webhooks

Enviaremos uma solicitação ao fornecedor em várias situações, por exemplo:

1. Se um novo URL desconhecido for compartilhado (sempre do compositor).
2. Se um novo usuário estiver vendo um conteúdo ao qual não sabemos se ele tem acesso (sempre do feed).
3. Se um conteúdo existente for compartilhado novamente ou expirar (do compositor ou do feed).

Formato de solicitação de webhook

Nos cenários anteriores, um webhook será enviado como uma solicitação POST no seguinte formato:

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

Essa carga contém os seguintes campos:

Exemplo

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"
            }
        }]
    }]
}
    

Formato de resposta do webhook

Ao receber uma solicitação de webhook, você precisará fornecer uma carga de metadados em um formato de resposta específico:

{
  "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
}

Essa carga deve conter os seguintes campos:

Exemplo de resposta completa

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
}
    

Modos de privacidade

O modo de privacidade determina a visibilidade, ou seja, se precisaremos da autenticação para os usuários atuais e subsequentes.

1. organization: Visível para o usuário. Não é necessária autenticação do usuário.
   Se estiver visível para o usuário, poderemos mostrar o conteúdo sem nenhum problema. Isso inclui, por exemplo, um conteúdo que deve estar visível para qualquer pessoa no domínio (empresa). Desse modo, não enviaremos um webhook sempre que alguém novo estiver vendo os novos conteúdos.
2. accessible: Visível para o usuário atual, mas o mapeamento da identidade pode ser necessário para outras pessoas.
   O fornecedor sabe que esse usuário específico tem permissão para ver o conteúdo, mas isso não significa que outras pessoas possam vê-lo. Mostraremos a prévia, mas continuaremos enviando webhooks para outros usuários.
3. inaccessible: Não visível para o usuário.
   O fornecedor conhece o usuário e sabe que ele não tem permissão para ver o conteúdo. Então, renderizaremos um aviso de privacidade (indisponível, privado etc.).

Dados adicionais

Para adicionar mais informações sobre uma prévia de link, você pode enviar até três itens de dados adicionais. Um item de dados adicionais é constituído por um conjunto de elementos de valores-chave, que pode ser formatado de diversas maneiras.

Atualmente, quatro formatos diferentes são compatíveis:

• text: o valor será renderizado do modo como está, mas ele deve ser uma string. Para esse formato, dados adicionais também podem conter uma propriedade color que deve ser blue, green, yellow, orange ou red. Nesse caso, o plano de fundo será renderizado na cor definida.
• date: o valor será analisado como o formato de data ISO-8601 sem hora e será renderizado sem indicação de hora.
• datetime: o valor será analisado como o formato de data ISO-8601 com hora e fuso horário e será renderizado com indicação de hora no fuso do usuário.
• user: o valor será analisado como um ID de usuário, e o nome do usuário será renderizado.

Se dados adicionais forem definidos, o parâmetro download_url será ignorado.

Renderizar prévias de arquivos (opcional)

Se o modo de privacidade do documento estiver marcado como organization ou accessible e um URL de download estiver presente, enviaremos uma solicitação adicional para baixar os dados.

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

O Workplace converterá esse arquivo em fotos, ou seja, fará uma publicação com várias fotos.

Mapeamento de identidade

Como mencionamos anteriormente, para fornecer prévias autenticadas, é preciso haver algum tipo de mapeamento de identidade. O mapeamento de identidade controla se um usuário do Workplace tem permissão para ver a prévia do conteúdo e garante o cumprimento das regras de acesso ao conteúdo no Workplace.

Mapeamento em toda a organização

A forma mais simples de mapeamento de identidade é o mapeamento em toda a organização, em que a participação de uma comunidade do Workplace é suficiente para permitir que as prévias sejam mostradas aos usuários no Workplace. Isso acontece na exibição de prévias de links para a intranet de toda uma empresa ou de qualquer serviço cujos objetos (ou pelo menos seus metadados) sejam visíveis para toda a empresa.

Quando sua integração é instalada em uma comunidade do Workplace, a identificação da comunidade pode ser verificada por meio do ponto de extremidade /community, utilizando o token de acesso recuperado após a instalação. É possível armazenar esse número de identificação da comunidade com o token e associá-lo a um locatário ou identificador da organização dentro do seu serviço. Isso cria um mapeamento entre uma comunidade do Workplace e a organização no seu serviço.

Depois, ao responder a solicitações de webhook de prévias autenticadas, você poderá verificar se a identificação da comunidade da carga do webhook corresponde à identificação da comunidade associada à organização; assim, é possível decidir se é seguro retornar uma carga de metadados. Se a privacidade dessa carga for definida como "ORGANIZATION", não precisaremos enviar webhooks adicionais para cada usuário nessa comunidade do Workplace.

Mapeamento por usuário

Se for necessário mais detalhamento para as permissões, você poderá oferecer compatibilidade com um mapeamento por usuário e, com isso, poderá escolher se deseja renderizar metadados para cada visualizador no Workplace. O Workplace envia uma identificação do usuário em cada carga de webhook para prévias autenticadas. Para oferecer compatibilidade com o mapeamento por usuário, você precisará saber qual registro de usuário no seu sistema é associado à identificação do usuário no Workplace enviado na carga do webhook.

Na primeira vez que você encontrar determinada identificação de usuário no Workplace, poderá responder com o campo booliano linked_user definido como false. Essa ação fará com que o Workplace mostre um botão Ativar prévia, solicitando que o usuário vincule a conta.

Quando o botão for pressionado, o Workplace abrirá uma caixa de diálogo para um ponto de extremidade de vinculação de conta definido; assim, você poderá validar a sessão do usuário no seu serviço. O Workplace usará uma solicitação POST para abrir esse URL e enviará um parâmetro de solicitação assinado, que contém o número de identificação do usuário atual e da comunidade.

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
    

Um parâmetro signed_request que contém informações sobre esse usuário estará presente na carga. Essa solicitação pode ser decodificada da seguinte forma:

1. Divida o conteúdo em duas partes delimitadas por um caractere ".".
2. Decodifique a primeira parte, a assinatura, a partir da codificação base64url.
3. Decodifique a segunda parte, a carga, a partir da codificação base64url e depois decodifique o objeto JSON resultante.
4. Verifique se a assinatura corresponde ao código HMAC da carga codificada com base na chave secreta do app.

A carga contém os seguintes campos:

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

Neste momento, você terá um número de identificação do usuário do Workplace e da comunidade, com uma sessão de usuário validada no seu serviço, e poderá registrar o número de identificação do Workplace para esse usuário, além da identificação dele no seu serviço. Após a conclusão, você deverá redirecionar para o URL fornecido na solicitação original como o parâmetro de consulta 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
...
    

Assim, o Workplace reconhecerá que o mapeamento de identidade está concluído e tentará solicitar novamente os metadados da prévia autenticada. Desta vez, você poderá responder com linked_user definido como true e fornecer os metadados necessários.

Perguntas frequentes