Permissões

Visão geral

Com a função de administrador do sistema do Workplace, é possível controlar os recursos oferecidos a cada integração ao criar apps com permissões específicas. O nome de cada app pode ser determinado de acordo com o serviço para o qual ele é usado. Os apps são equipados com permissões e tokens de acesso únicos que servem para controlar quais informações os apps podem ler ou gravar.

Este guia descreve em mais detalhes o modelo de permissão e app.

Controles de permissão ao editar um app de integração personalizada

Permissões disponíveis

Cada app do Workplace pode receber o próprio conjunto de permissões para controlar o nível de funcionalidade disponibilizado na Graph API e na API de Gerenciamento de Contas.

Quando o app é criado, as permissões concedidas a ele são aplicadas a todas as contas da comunidade. Para aproveitar a funcionalidade do app, os proprietários das contas não precisam conceder permissões adicionais. Isso é diferente do modelo de permissões do Facebook, em que cada usuário concede permissões ao entrar no app.

Confira abaixo a lista completa das permissões do app disponíveis para integração, bem como uma visão geral de como cada uma pode ser usada.

Permissões no nível do grupo

Em algumas permissões, é possível limitar a ativação de uma integração em grupos específicos. Isso permite restringir o acesso da integração apenas ao conteúdo que você deseja expor.

Por exemplo, é possível permitir que uma integração de publicação de alertas publique apenas no grupo da equipe ou que a integração de um app de funcionário leia o conteúdo apenas de grupos abertos específicos.

Para especificar uma permissão no nível do grupo em uma integração personalizada, use o painel de acesso do grupo no diálogo Editar integração.

Como ativar permissões no nível do grupo nesta integração

As permissões no nível do grupo podem ser aplicadas às seguintes permissões:

• Ler conteúdo do grupo: ler publicações, comentários e perfis dos membros em grupos selecionados.
• Gerenciar conteúdo do grupo: gerenciar publicações e comentários em grupos selecionados.
• Gerenciar grupos: editar ou remover grupos selecionados e respectivos membros.

É possível configurar uma integração para que as permissões no nível do grupo sejam aplicadas a todos os grupos ou a grupos específicos, conforme escolhido por um administrador do sistema, ou ainda Permitir que os administradores ativem para os seus respectivos grupos.

Fluxo de instalação do administrador

Quando a função Permitir que os administradores ativem para os seus respectivos grupos estiver ativa, um administrador do grupo verá uma nova aba Integrações na tela Gerenciar grupo, o que permite ativar a integração no grupo.

Exemplo de app que pode ser ativado pelo administrador do grupo

Uso e tokens do app

Quando você cria um novo app para o Workplace, um token de acesso é gerado para uso na Graph API, na API de Gerenciamento de Contas ou nos Webhooks.

O token de acesso será mostrado apenas uma vez. Por isso, é importante armazená-lo de forma segura para uso posterior no código.

Fluxo de redefinição de token para um app de integração personalizada

Os tokens de app do Workplace não expiram e não precisam ser atualizados, a menos que sejam redefinidos manualmente. Se você editar as permissões disponíveis para um app, o token existente ainda funcionará, e não será necessário gerar um novo.

Caso seja necessário invalidar um token, será possível redefini-lo por meio do botão Redefinir token de acesso no diálogo Editar aplicativo. Um novo token será gerado e mostrado, e o existente será invalidado imediatamente.

Segurança do token

Os tokens de acesso são poderosos porque concedem acesso aos dados da empresa no Workplace. Ao criar um app, considere o conjunto mínimo de permissões necessárias para realizar os recursos de integração. Além disso, não conceda permissões desnecessárias.

Tenha cuidado ao armazenar tokens ou adicioná-los a repositórios de código para que eles não sejam compartilhados com as pessoas erradas.

Para incluir uma camada extra de segurança nas integrações, adicione uma lista de liberação de IPs para restringir o uso dos tokens especificamente aos servidores na respectiva lista de endereços IP.

Como adicionar uma lista de liberação de IPs para restringir o uso de tokens a servidores específicos e como exigir prova da chave secreta do app

Remoção automática de permissões não usadas

Uma permissão específica será removida se não for usada por uma integração personalizada para fazer ligações por 30 dias. Após a primeira ocorrência em uma integração personalizada, será disponibilizada uma opção para impedir o processo de remoção.

Caso uma assinatura válida de webhook seja configurada, os webhooks enviados por ela contam como um uso da permissão em questão.

Controles para remoção automática de permissão

Prova da chave secreta do app

Os token de acesso do Workplace não expiram. As integrações personalizadas podem exigir uma prova da chave secreta do app para incluir uma camada adicional de segurança. A ativação da opção "Exigir prova da chave secreta do app" garante que as ligações da API serão sempre feitas a partir de um código do lado do servidor. Ao fazer ligações da API, será exigida uma prova de chave secreta do app, além do token de acesso.

Para gerar uma prova da chave secreta do app com prazo de validade, será necessário concatenar o token com um registro de data e hora do Unix, separado pelo símbolo de barra vertical |. Depois disso, será preciso criar um hash SHA-256 da string concatenada usando a chave secreta do app. Veja um exemplo em PHP:

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

Para fazer ligações da API usando a chave secreta do app, passe o hash gerado via parâmetro appsecret_proof, com o conjunto appsecret_time definido como o registro de data e hora usado ao converter em hash a chave secreta do app, juntamente com o token de acesso.

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

Como explorar a funcionalidade da API com o Postman

O Postman é uma ferramenta de trabalho muito usada por APIs da web. Apesar da conveniência em explorar a API do Workplace com o Postman, o parâmetro $appsecret_proof apresenta uma complicação, pois o valor precisa ser calculado e expira após 5 minutos. Seria mais simples se o Postman gerasse o valor no momento da solicitação. Na verdade, o Postman faz isso por meio de scripts de pré-solicitação e parâmetros. O script a seguir pode ser usado como ponto de partida:

// 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) Crie um ambiente ativo (não existe um por padrão). Depois, 2) adicione esses três parâmetros, que são calculados pelo recurso "Script de pré-solicitação".